第04章 - 项目文件与个人设置

工程文件是 GeoLibre 的“可带走的工作区”：地图视图、图层、样式、插件状态、打印布局与故事地图都在一个 JSON 文件里。个人设置则是“留在设备上的偏好与凭据”：语言、布局、AI Provider、S3 连接，以及不进工程文件的 API key。

本章分两半：4.1–4.11 讲工程文件与保存/分享生命周期，4.12–4.13 讲设置分页与本地存储。读完你应能回答三个问题：这个功能的状态到底存在哪里、分享时什么会被剥离、换设备时哪些东西不会跟着走。

4.1 工程文件：一个文件装下工作区

4.1.1 两个扩展名与文件关联

GeoLibre 当前把工程保存为 .geolibre 文件，同时继续打开早期的 .geolibre.json 名称。两者内容相同：

桌面可执行文件同时接受两种名字：

geolibre-desktop /path/to/watershed.geolibre
geolibre-desktop /path/to/legacy.geolibre.json

提示 文档与旧教程里仍常写 .geolibre.json，那不是错误，只是历史名称。新建工程保存时优先用 .geolibre，团队协作时统一扩展名可以减少“双击打不开”的困惑。

4.1.2 工程里有什么

一个工程文件可以包含：

• 地图视图（中心、缩放、方位、俯仰，可选外包框）与底图设置。
• 图层列表、图层分组、每个图层的源信息与样式。
• 工程级地图偏好（边界限制、缩放范围、最大俯仰、天体、比例尺单位、坐标格式、地图 CRS 等）。
• 插件状态（清单 URL、激活的插件、地图控件位置、插件设置）。
• 图例定制、打印布局、故事地图、Dashboard 部件、书签与书签文件夹。
• 处理模型、处理历史、OBIA 工作台状态。
• 多图网格与副图相机、主图渲染引擎。
• 工程级 Style Manager 条目、评审评论、启动交互状态与自由元数据。

4.1.3 工程里没有什么

工程是引用式的，默认不包含：

• 远程数据本身（WMS、ArcGIS 服务、远程 GeoParquet/COG 等只保存 URL 与参数）。
• 大多数本地文件的二进制内容（本地栅格、MBTiles 等只保存路径；桌面版才能重新读取）。
• 你的账号、API key、S3 密钥等凭据（分享/导出时会被剥离，见 4.10.4）。
• 设备级 UI 状态（面板宽度、当前滚动位置、对话框尺寸）。
• 自动保存快照（存在 IndexedDB，不上传、不写进工程）。

例外是内嵌矢量：通过 Add Data → Vector Layer 添加的本地小矢量图层，可能会把 GeoJSON 写进工程（受大小上限约束），以便浏览器版也能保存与分享；这也是分享时“本地图层可能缺失”提示会区分“内嵌矢量”和“纯路径图层”的原因。

4.2 顶层字段

4.2.1 字段总表

4.2.2 最小可用样例

下面是一个能通过解析的最小工程（省略了可选块）：

{
  "version": "0.2.0",
  "name": "Demo",
  "mapView": { "center": [-100, 40], "zoom": 2, "bearing": 0, "pitch": 0 },
  "basemapStyleUrl": "https://tiles.openfreemap.org/styles/liberty",
  "basemapVisible": true,
  "basemapOpacity": 1,
  "layers": [],
  "styles": {},
  "preferences": {},
  "metadata": {}
}

4.2.3 必需字段与容错

解析入口（parseProject）只强制三个字段：version、name、mapView。缺任何一个都会抛错：Invalid GeoLibre project: missing required fields。

其余字段遵循“能修就修、修不了就默认”的策略：

提示 手改工程文件时，最安全的做法是只改确定存在的键，并用应用打开验证；不要指望“写错一个字段整份文件还能完全按原意生效”。GeoLibre 的容错目标是“能打开且不崩”，不是“修复你的笔误”。

4.2.4 省略即默认

为了向后兼容，很多字段“默认值不写”：

• primaryRenderer 省略表示 maplibre；所有在它之前保存的工程与从未离开 MapLibre 的工程保持字节级兼容。
• mapLayout 只在网格大于 1×1 时写入。
• printLayout 只在设置偏离默认时写入。
• bookmarks、bookmarkGroups、widgets、storymap 在为空时省略。
• styleLibrary 只写工程级条目，应用级库不进工程。

这带来一个实际好处：工程文件的 diff 更小，团队用 Git 管理工程时噪音更低。

4.3 图层对象与类型

4.3.1 图层对象字段

4.3.2 图层类型

4.3.3 样式：layer.style 与 project.styles

图层自己的 style 是保存时的样式快照；project.styles 是“按图层 id 索引的样式表”。应用在加载时会用 styles 中的条目水合图层样式（hydrateProjectLayer），因此：

• 想批量改样式，优先改 styles 对应条目。
• 想复制样式到另一个工程，用导出的样式文件（4.11.1）而不是手工搬 JSON。
• 某些样式属性只对特定类型有意义（如 circleRadius 对点、rasterBrightnessMin 对栅格），无关属性会被忽略。

4.3.4 图层分组与顺序

layerGroups 是扁平数组，通过 parentId 表达嵌套；layers 数组保持“同组连续”，分组才能作为一个块渲染。分组有自己的 visible 与 opacity，在同步到地图前与子图层的可见性/透明度合并，子图层自身保存的值不被改写。

4.3.5 图层级扩展字段

现代工程里，图层对象还可能带这些块：

警告 capabilities 是“图层声明的能力”，由应用在 UI 层执行，不是访问控制机制。真正的权限必须由数据库授权或服务端校验保证；不要把它当安全边界。

4.3.6 本地数据如何进入工程

4.4 插件状态

4.4.1 结构

plugins 记录“这个工程需要哪些插件、哪些处于激活、控件放在哪、插件自己的设置是什么”：

{
  "manifestUrls": ["https://example.com/plugins/example-plugin/plugin.json"],
  "activePluginIds": ["maplibre-layer-control", "maplibre-gl-swipe"],
  "mapControlPositions": {
    "maplibre-layer-control": "top-right",
    "maplibre-gl-swipe": "top-left"
  },
  "settings": {
    "maplibre-gl-swipe": {
      "orientation": "vertical",
      "position": 50,
      "collapsed": false,
      "active": true,
      "leftLayers": ["layer-a"],
      "rightLayers": ["layer-b"]
    }
  }
}

4.4.2 清单 URL 的安全限制

清单 URL 通过 isAllowedPluginManifestUrl 校验，只接受允许的协议与形式；工程里写一个 file:// 或非 HTTPS 地址不会被执行。外部插件本身仍属“受信任代码”，安装前应确认来源。

4.4.3 没有 plugins 的工程

省略 plugins 时，工程按内置默认插件状态打开。这也是旧工程能无缝打开的原因：新增插件字段是可选块，而不是迁移步骤。

4.5 图例、打印布局与故事地图

4.5.1 图例（legend）

打印布局的图例始终从可见图层的符号化自动派生；legend 只保存“用户编辑”，因此增删图层不会让定制失效：

{
  "title": "Legend",
  "groupByLayer": true,
  "order": ["layer-b", "layer-a"],
  "overrides": {
    "layer-a": { "label": "Roads" },
    "layer-b::0": { "label": "Low" },
    "layer-b::1": { "hidden": true }
  }
}

4.5.2 打印布局（printLayout）

打印布局属于工程，重开时恢复原样；从未打开过编辑器时不写这个键。核心字段：

{
  "title": "Dentists by region",
  "subtitle": "2026",
  "paperSize": "a3",
  "orientation": "portrait",
  "pageMargin": "normal",
  "showLegend": true,
  "showScaleBar": true,
  "showNorthArrow": true,
  "showDataTable": true,
  "tableLayerId": "layer-a",
  "tableColumns": ["name", "count"],
  "atlasEnabled": false
}

无法识别的值回退默认，因此手改文件不会把编辑器锁死。每会话状态（捕获的地图图像、当前图集页、对话框面板宽度）刻意不保存。

4.5.3 故事地图（storymap）

故事地图把工程变成滚动叙事。每章捕获一个相机视图与文字，并可让工程图层在进入/离开时淡入淡出；没有章节时整个键省略。

{
  "title": "A Tour of Three Cities",
  "theme": "dark",
  "showMarkers": true,
  "markerColor": "#3fb1ce",
  "chapters": [
    {
      "id": "intro",
      "title": "San Francisco",
      "description": "A hilly city. <em>HTML allowed.</em>",
      "alignment": "left",
      "location": { "center": [-122.4194, 37.7749], "zoom": 11, "pitch": 45, "bearing": 0 },
      "mapAnimation": "flyTo",
      "onChapterEnter": [{ "layerId": "layer-a", "opacity": 1, "duration": 2000 }],
      "onChapterExit": [{ "layerId": "layer-a", "opacity": 0 }]
    }
  ]
}

• alignment 为 left/center/right/full。
• mapAnimation 为 flyTo/easeTo/jumpTo。
• 透明度变化引用工程图层 id；章节还可带图片、隐藏标记与旋转动画。
• 从 Project → Story Map… 构建与演示，或导出为自包含 HTML。

4.6 仪表盘、书签与交互

4.6.1 Dashboard 部件

widgets 把图表绑定到图层属性，dashboardColumns 控制网格列数（1–6，默认 2）：

{
  "widgets": [
    { "id": "w1", "layerId": "layer-a", "type": "histogram", "field": "pop", "bins": 12 },
    { "id": "w2", "layerId": "layer-a", "type": "bar", "category": "kind", "aggregation": "sum", "valueField": "pop" }
  ]
}

color 可选，接受 #rgb/#rrggbb；无关键被忽略。部件绑定到 GeoJSON 矢量图层或 DuckDB 查询图层；绑定到缺失图层时显示为空。

4.6.2 书签

bookmarks 按面板顺序保存地图视图，bookmarkGroups 是可选的文件夹（不嵌套）：

{
  "bookmarkGroups": [{ "id": "hoods", "name": "Neighborhoods", "collapsed": false }],
  "bookmarks": [
    {
      "id": "downtown",
      "name": "Downtown",
      "lng": -83.92,
      "lat": 35.96,
      "zoom": 14,
      "pitch": 30,
      "bearing": 340,
      "createdAt": 1700000000000,
      "groupId": "hoods",
      "extra": { "visibleLayerIds": ["cities"] }
    }
  ]
}

• 范围：lng −180..180、lat −90..90、zoom 0–24、pitch 0–85，bearing 归一到 0–360。
• extra.visibleLayerIds 记录打开该书签时要显示的图层，其余隐藏。
• 相机缺失/越界或 id 重复的书签在加载时被丢弃；指向不存在文件夹的 groupId 被丢弃。
• 工程最多保存 500 个书签（MAX_PROJECT_BOOKMARKS）。

4.6.3 交互（interaction）

interaction 是“打开工程时应用的一次性状态”，由 Python 包从 set_identify 与 show_control/hide_control 写入：

{
  "interaction": {
    "identify": ["layer-a", "layer-b"],
    "controls": { "search": true, "globe": false }
  }
}

• identify 可为图层 id、all（所有可见可查询图层）、图层 id 数组，或 null（关闭）；不存在的 id 被跳过。
• controls 的键可以是工具栏面板（bookmark、search、measure、minimap、print）或内置地图控件（navigation、fullscreen、compass、geolocate、globe、scale、attribution、logo）；其他名字被忽略。
• 应用保存工程时原样写回这个块；在界面里开关 Identify 或控件不会改它。这保证 Notebook 生成的工程在网页/桌面打开时保持作者设定的初始状态。

4.7 保存、另存、模板与副本

4.7.1 Save 与 Save As

• Save 写回工程已有的路径。
• Save As… 提示新名称与位置。
• 两者都会捕获保存瞬间的地图视图、底图、图层、样式、偏好与插件状态。
• 从 URL 打开的工程没有可写本地路径，Save 与 Save As 都退化为保存对话框。
• 浏览器构建里，Chromium 系浏览器使用浏览器保存对话框；否则要求输入文件名并下载到下载目录。

4.7.2 Duplicate project

Project → Duplicate project 把当前工程复制成一个新的未保存工程，适合在不影响原文件的前提下做分支实验。它是“另开一份”，不是“另存为同一份”。

4.7.3 模板

Project → Save as template… 把当前工程保存为个人模板库中的可复用模板，可填名称与描述。勾选 Strip data layers 后，模板保留底图、图层分组、样式、图例、部件与布局，但剥掉数据图层内容——适合作为团队“房屋风格”的起点。新建工程时，模板出现在底图库上方的 Saved Templates。

提示 模板库是应用级（IndexedDB）而不是工程级。它不会随工程分享，也不会进 .geolibre；需要在团队间共享时，用样式文件与图层文件代替。

4.7.4 打开方式与只读

Project → Open From 支持 File、URL、Gallery。从 URL 打开的工程默认没有本地写权限，适合查看与复制；Gallery 里的条目可以一键打开，也可以“打开副本”。桌面版还支持双击 .geolibre 或把工程拖到地图上切换工程（会保留未保存提示；坏文件报“工程错误”而不是“图层加载失败”）。

4.8 历史、快照与崩溃恢复

4.8.1 自动保存

GeoLibre 在你工作时自动保存快照：一次更改（加图层、改样式、移动相机）稳定约 3 秒后写入浏览器的 IndexedDB。

关键区别：

快照从不写 .geolibre 文件，只有 Save 会。

4.8.2 History

Project → History… 按从新到旧列出当前工程的快照，每条显示图层数与缩放级别：

• Restore 把快照载回工作区，作为可撤销的一步。
• 没有手动删除；快照达到上限后自动淘汰最旧的。
• 快照按工程分键（已保存工程用路径，未保存工程用名称），只存在生成它的设备上，不上传、不分享。

4.8.3 Compare 与单图层恢复

Compare 显示快照与当前工程（或两个快照之间）的差异，按可折叠分区组织：

• 新增/删除/重命名/重排/改样式的图层（含每个样式、标注、过滤与源设置的前后值，以及内嵌要素的增删改计数）。
• 相机、底图与投影。
• 插件。
• 工程标题、详情与偏好。

与“当前工程”比较时，Restore this layer 只恢复快照里的单个图层（包括把已删除的图层加回来），不动其他部分，并且可以撤销。恢复已删除图层会一并带回删除时被清掉的相关内容：Dashboard 部件、要素评论、图例顺序与覆盖、故事地图的透明度步骤、其他地图窗格中的可见性，以及引用了它的打印布局表格/图表/图集块；你在快照之后做过的其他修改保持不变。

4.8.4 上限

超过单个快照上限的大工程不会被自动保存；达到总量后从最旧的开始淘汰。

4.8.5 崩溃恢复

在独立浏览器（非 iframe 嵌入）中，GeoLibre 会在工作时标记会话为打开状态。如果标签页/浏览器异常消失，且存在比上次显式保存更新的自动保存，下次启动会提供 Recover unsaved work?，可选择恢复或丢弃。

桌面版与嵌入部署保留 History 列表，但不弹这个恢复提示。

4.8.6 不进入工程的状态

以下状态只在本机，且通常不进 .geolibre：

• 面板宽度/折叠、对话框尺寸、滚动位置。
• 最近工程列表（localStorage）。
• 模板库、应用级 Style Manager、Layer Library（IndexedDB）。
• 自动保存快照（IndexedDB）。
• API key、token、S3 密钥（桌面进系统凭据库）。
• 插件安装记录（浏览器 IndexedDB；桌面在应用数据插件目录）。

4.9 导入 QGIS 与 ArcGIS Pro

4.9.1 QGIS 工程

Project → Import → Import QGIS Project… 读取 .qgs/.qgz，重建：

• 图层（文件型矢量 + 应用能打开的栅格）。
• 图层分组（含嵌套）、分组可见性、图层顺序。
• 样式与保存的地图视图。

导入器逐层报告而不是整单失败：不支持的提供者、不支持的文件格式、缺失源、网络共享路径、远程源都会被列出；同一原因的图层合并成一行并带数量，展开可看图层名。浏览器版无法重开本地磁盘路径，这类图层会被标为跳过；同样的工程在桌面版可加载。

4.9.2 ArcGIS Pro 工程

Project → Import → Import ArcGIS Pro Project… 读取 .aprx 或独立的 .mapx。它直接解析文件里的 CIM JSON，不需要安装 ArcGIS Pro 或 ArcPy。

一个 ArcGIS Pro 工程可能有多幅地图；GeoLibre 导入第一幅二维地图，保留：

• 保存的范围。
• 文件型要素图层与 GeoTIFF 栅格。
• 嵌套分组、可见性、简单符号、字段标注。
• ArcGIS 矢量瓦片门户项与缓存地图服务。

不支持的内容（File Geodatabase、场景、网络共享路径）会在其余部分导入后按原因分组列出。File GDB 图层会被明确标成该类，而不是笼统的“不支持格式”：桌面版可用 Add Data → File Geodatabase (GDB) 添加其要素类，而 .gdb 里的栅格需要先导出为 GeoTIFF。浏览器版无法重开本地数据路径。

4.9.3 跳过原因与处理

4.9.4 迁移建议

• 先在 QGIS/Pro 里把不支持的图层“降级”为通用格式，再导入，报告会更干净。
• 样式优先用 QML/SLD 交换，而不是期待所有符号 1:1 还原；复杂标注需要手工重建。
• 导入后立即做一次 Share 就绪检查，能提前发现跨域、凭据与本地路径问题。

4.10 分享、脱敏与导出 HTML

4.10.1 Share 流程

Project → Share… 把当前工程上传到 share.geolibre.app（或部署配置的自托管服务），返回公开 URL。上传的文件就是本地保存的同一份工程，因此接收方看到的图层、样式与视图一致。

连接账号的三种方式：

4.10.2 分享就绪检查

分享对话框打开时会检查工程引用的数据源，列出接收方可能加载不了的图层及原因：

检查在浏览器内、且不带你的凭据执行，因此它看到的就是接收方看到的结果。它不会阻止上传——把内网地图分享给内网同事是正常需求，列表是提示而不是闸门。

4.10.3 本地数据警告

工程保存引用，不保存数据；share.geolibre.app 只存工程文件，从不上传你电脑上的文件。因此从本地 GeoTIFF、GeoPackage、Shapefile 等添加的图层，在你这里正常，在接收方那里“图层存在但画不出来”。没有 URL 的查询图层（PostGIS、DuckDB SQL、sidecar 结果）同理。

分享对话框会把这些列在 N layers will be missing from the shared map 下，按钮变成 Share anyway。要真正包含它们：

1. 托管数据：栅格转 COG，矢量转 PMTiles 或 GeoParquet，放到公开 HTTPS（GitHub、Hugging Face、对象存储），再用 URL 添加。
2. 让小矢量随工程走：通过 Add Data → Vector Layer 添加的本地矢量会自动内嵌到上传中，因此不会出现在缺失列表；但每条要素都会在打开工程时解析，大数据仍应托管。
3. 私有网络地址不算“本地文件”，它会留在较软的就绪检查列表里，而不是这条硬警告里。

警告 即使不点 Share，手动把保存的 .geolibre 上传到分享站点也会发生同样的图层缺失。对话框在配置 token 之前就会警告，正是为了避免这种“静默丢图层”。

4.10.4 凭据脱敏

任何离开本地工作区的工程都必须先通过 redactCredentials(project)。GeoLibre 把这条不变量应用于：

• Share 上传。
• 单文件 HTML 导出。
• 嵌入快照。
• 协作快照。

规则要点：

• 图层 source.requestHeaders 可以引用环境变量，例如 Authorization: Bearer 变量引用；引用按原样保存，请求时从启用的环境变量行解析；变量未设置或为空时该头不发送。只有“可选 scheme 词 + 一个引用”的值能通过脱敏，其他头值被移除。
• preferences.environmentVariables 的每一行默认视为 secret：脱敏会移除；桌面版在名字唯一且非空时把值存进系统凭据库。
• 标记 secret: false 的行是普通值，会留在文件里，并随 Share 与导出保留。
• 脱敏还会移除 URL 中的认证参数；外部插件设置默认不进入分享快照，接收方保留清单与激活信息，但需要自行配置设置。

4.10.5 导出 HTML

Project → Export → Export as HTML… 把整个工程写成单个独立 HTML 文件，可在无服务器、离线状态下打开。它适合：

• 交付给不想安装任何东西的客户。
• 放到静态站点或 U 盘。
• 归档一个“可交互的快照”。

注意它同样经过脱敏：凭据不会写进 HTML，依赖凭据的图层会像分享一样失效；本地路径图层也不会自动带上数据。

4.11 样式文件、图层文件与图层库

4.11.1 样式文件

• Project → Export → Export Layer Styles… 把每个图层的样式写成一个 JSON，按图层名索引。
• Project → Import → Import Layer Styles… 应用到当前工程，名称匹配的图层在一个可撤销步骤里重设样式，并报告没有匹配上的样式。
• Settings → Startup → Default layer styles 选择样式文件后，每个新加入且名称匹配的图层会自动套用；已打开工程里的图层保留自己的样式。
• GeoLibre 会保存该文件的副本，编辑原文件后需要重新选择。

4.11.2 图层文件

• Project → Export → Export Layers… 写出 "type": "geolibre-layers" 的 JSON，供 Settings → Startup → Default layers 使用，让每个新建工程自动带上这些图层。
• 每个图层保留样式、标注、可见性、透明度与文件夹，但数据只保存引用：瓦片/服务 URL、远程文件 URL，或桌面可重读的本地路径。
• 要素不会被内嵌，因此“只存在于工程中的要素”（手绘、处理结果、浏览器打开的文件）会被跳过，GeoLibre 会列出被跳过的图层。
• 导出时移除 API key 与 token，与分享一致。

4.11.3 Layer Library

Layer Library 是“完整配置好的图层”库，入口在 Browser 面板的 My Data：

• 保存源、样式、标注、过滤、连接、虚拟字段与属性表单。
• 一键加入任何后续工程；可改名、删除，导出/导入 JSON 包。
• 保存的是源规格而不是数据，因此 COG、PostGIS 表、远程 GeoParquet 总是反映源的当前内容；纯内存或本地文件的图层会在大小上限内内嵌要素。
• 与“图层文件”的区别：图层文件是启动时批量注入的模板，Layer Library 是手动挑选的可复用条目。

4.11.4 三者对照

4.12 设置分页逐项说明

4.12.1 总览

Settings 菜单打开一个多分页对话框：

4.12.2 Language

• Interface language 以各自文字显示，并附英文名；从右到左语言会镜像整个布局。
• Whitebox language packs 单独管理：Download pack 下载所选语言官方包，Import file 安装本地包，Remove pack 回到英文。语言包只存在当前设备；下载只发送 locale 代码，不发送工程数据。禁用下载的构建只提供 Import file。

4.12.3 Map Preferences

Use Current View 用当前地图设置边界，Reset 恢复默认。这些偏好随工程保存。

提示 在地球投影下 Use Current View 捕获的边界可能略有漂移，对话框会提示。需要严格边界时先切到 Mercator。

4.12.4 Layout 与 Appearance

• Layout：Show toolbar labels、Show project info、四个面板的显示开关（Layers、Style、Browser、Comments）。
• Appearance：Mode（Light/Dark）与 Accent color（Blue、Violet、Emerald、Rose、Amber、Custom）。
• 小屏上面板会自动隐藏，这是响应式行为，不受 Layout 开关限制。

4.12.5 Interface

• Experience level：Beginner / Intermediate / Advanced，下面可逐项开关 Data sources、Plugins、Menus（含菜单内条目）。改动任一开关会切到 Custom；Reset 恢复默认。
• 管理员管理 profile 时，此页只读；Help 与 Settings 的入口永远保留。
• Interface file：Export… 写出语言、面板布局、强调主题与 profile；Import… 应用本地文件；Import from URL 从 http(s) 地址加载（服务需允许跨域）。只改文件里包含的设置，文件不含凭据、插件来源或本地路径，也不会锁 profile。

4.12.6 Geocoding

• Provider：Nominatim 为默认且无需 key；需要 key 的 Provider 在此填 API key。
• Forward endpoint / Reverse endpoint：可改到自托管实例。
• Contact email：Nominatim 要求。
• 使用 ArcGIS GeocodeServer (organization) 时，端点字段变为命名 Locators 列表，每项含服务 URL、可选门户与 Check service。
• key 存储在系统钥匙串（可用时），否则进工程文件；它们以查询参数发送，会出现在请求 URL 里。

4.12.7 AI Providers

• 每个配置是一个命名 profile（如 Work Gemini、Local Ollama）：选 Provider、填字段、Save profile。
• 标记一个 Set as default，助手打开时使用；配置一个即可开始聊天。
• 凭据保存在当前设备，绝不进工程文件；有系统钥匙串时 secret 字段进钥匙串。
• 桌面版空白 key 字段会回退到匹配的操作系统环境变量；界面里填的值优先。
• Provider 列表与字段见第18章。

4.12.8 Environment Variables

• Share.GeoLibre account：登录/登出分享服务（网页弹窗；桌面系统浏览器）。
• Share.GeoLibre API token：个人 token，作为分享的兜底（移动端、Notebook 嵌入等）。
• Environment variables：命名键值对（Earth Engine、Street View 等集成），可逐条启用/禁用，secret 值掩码。变量名必须以字母或下划线开头，只含字母、数字与下划线。
• 桌面版 AI 助手还会读取允许列表中的系统环境变量（如 OPENAI_API_KEY），界面值优先。

提示 运行时环境变量是“个人/临时”层：不需要重建即可生效。要固化到自托管部署，用构建期环境变量或部署的 deployment.json，而不是让每个用户手填。

4.12.9 Cloud Storage

Settings → Cloud Storage 保存 S3（及 S3 兼容）连接：访问密钥、AWS profile（含 SSO）、环境变量与 IAM 角色；并设置 S3 Browser 的默认位置。私有桶的密钥部分在桌面版进系统凭据库。

4.12.10 Startup

限制与细节：

• 只有本地工程会被恢复；分享链接按 https:// URL 记入最近列表，但启动恢复会跳过远程条目。
• 地址栏里的工程/?data= 参数总是优先，启动恢复被跳过。
• 启动工程被移动或删除时，GeoLibre 打开默认工作区、用横幅说明，并从最近列表移除该文件。
• 浏览器构建只有空工作区投影选项，三个工程恢复模式仅桌面可见。
• Android 会把启动工程复制到应用私有存储后重开（系统给的文件引用在进程结束后失效）；在别处编辑过的内容需要重新从 Project → Open From → File… 打开。

4.12.11 Updates、Style Manager 与 Manage Plugins

• Updates（桌面）：是否在启动时检查新版本、哪些发布类型提醒；完全离线工作流可关闭检查。
• Style Manager：个人符号/色带/标注预设库，可跨工程应用；也可从图层菜单 Layer actions → Styles → Saved styles (Style Manager)… 进入。工程级条目另存于 styleLibrary。
• Manage Plugins：插件市场（安装、更新、移除、源管理），详见第21章。

4.13 本地存储、凭据与备份

4.13.1 存储分层

4.13.2 凭据去哪

• 桌面（Tauri）通过 secure_store_* 命令把每个凭据写进系统凭据库：macOS Keychain、Windows Credential Manager、Linux Secret Service。
• 网页、Jupyter 嵌入与移动端没有系统凭据库，只能放 localStorage；这意味着同源脚本（包括你安装的插件）可以读取。
• 凭据读取在桌面版每次页面加载只允许一次，之后会“封印”，防止后加载的插件读取已保存 token。
• 写入失败不会回退到明文：界面会提示，失败的值只在本会话内存中可用。

警告 不要把敏感值写进会分享的工程。即使暂时保存在本地，Share/HTML 导出/协作快照都会走脱敏；但“本地工程文件”本身仍可能含未脱敏的凭据，尤其是你在网页版手动保存的工程。

4.13.3 脱敏边界

重复或匿名的 secret 环境变量行无法以唯一账户存入钥匙串，因此本地保存/另存会提供与“钥匙串不可用”时相同的保留/剥离选择。

4.13.4 备份与迁移

• 备份工程：复制 .geolibre 文件即可；数据在外部，备份时要一并备份本地数据文件或记录远程 URL。
• 迁移设置：用 Settings → Interface → Export… 带走语言、布局、主题与 profile；AI/S3/分享凭据需要在新设备重新配置（或在桌面凭据库中手动迁移）。
• 迁移插件：桌面插件在应用数据目录，网页插件在 IndexedDB；跨设备最稳妥的方式是从市场重新安装。
• 不要备份 IndexedDB 快照当作长期版本控制；需要版本历史时把工程放进 Git，或用导出的 HTML/PDF 作为发布快照。

4.14 本章小结

• 工程以 .geolibre 保存，仍可打开 .geolibre.json；文件管理器关联只对 .geolibre 生效。
• 工程是引用式的：保存视图、图层源、样式与状态，默认不保存远程数据与凭据。
• 顶层字段覆盖视图、图层、偏好、插件、图例、打印、故事地图、部件、书签、交互与元数据；缺字段有规范化默认，但 version/name/mapView 必需。
• 图层对象除基础字段外，还可带能力、弹窗、连接、虚拟字段、快速过滤、表达式过滤、编辑跟踪与目录元数据。
• 自动保存写 IndexedDB（3 秒去抖，20 个/10 MB/50 MB 上限），只有 Save 写工程文件；崩溃恢复仅在独立浏览器中提示。
• QGIS/ArcGIS Pro 导入逐层报告跳过原因；File GDB、场景与网络路径需要替代方案。
• Share 有就绪检查与本地数据警告；所有离开本地的出口都经过 redactCredentials。
• 设置分页覆盖语言、地图、布局、外观、界面、地理编码、AI、环境变量、云存储、更新、启动、样式管理与插件。
• 设备级状态与凭据不进工程；桌面凭据在系统凭据库，网页在 localStorage，这是必须知道的信任差异。

4.15 实践练习

1. 读工程：新建一个工程，加入一个图层并改样式，保存后用文本编辑器打开，找出 layers、styles、mapView 与 preferences 四个块，记录它们的最小结构。
2. 手改验证：把 mapView.zoom 改成一个越界值（如 99），重新打开，观察应用如何规范化；再把 selectedLayerId 改成不存在的 id，确认不会报错。
3. 快照恢复：连续做三次修改（加图层、改样式、移动相机），打开 History 比较两个快照，用 Restore this layer 恢复单个图层，再用撤销回退。
4. 分享检查：添加一个本地 GeoTIFF 与一个远程 GeoJSON，打开 Share 对话框，记录就绪检查与本地数据警告分别列了什么。
5. 脱敏审计：在 Environment 里添加一个 secret 变量与一个 secret: false 变量，导出 HTML，用文本搜索确认哪个值被剥离、哪个保留。
6. 迁移设置：导出界面文件，在另一浏览器 profile 导入，列出被带过去与未被带过去的设置，并解释原因。