第02章 - 安装部署与快速上手

GeoLibre 的安装路径比大多数桌面 GIS 多：你可以在浏览器里直接用，也可以装桌面应用、手机 App，或在 Notebook 里嵌入。本章先帮你选路径，再给出每个平台的完整安装步骤与验证方法，最后用一份可复现的“第一个地图”把整条链路走通。

本章命令与路径均来自仓库 3.4 的文档与源码；示例中的版本号、文件名以你下载到的实际发布为准。

2.1 五条使用路径与如何选择

2.1.1 路径速览

2.1.2 决策清单

按顺序回答四个问题，就能确定路径：

1. 需要读写本地文件吗？（Shapefile 目录、GeoTIFF、MBTiles、本地工程保存）——需要，选桌面。
2. 需要 Python sidecar 工具吗？（rasterio 全量栅格、GeoPandas 引擎、SQL Server、完整 Conversion）——需要，选桌面；或在自托管 Web 上启用同源 sidecar。
3. 要在手机上做外业采集吗？——是，装 Android/iOS；注意 Conversion、AI Segmentation、sidecar Raster、PostgreSQL/SQL Server 在移动端不可用。
4. 要把地图嵌进网页或 Notebook 吗？——网页用 iframe + postMessage/@geolibre/embed，Notebook 用 Python 包，R 用 R 包。

2.1.3 一份工程，多端打开

GeoLibre 当前把工程保存为 .geolibre 文件，同时继续打开早期的 .geolibre.json 名称。两者内容相同，区别只在扩展名与文件关联：

注意 网页版的“保存”会走浏览器的保存对话框或下载；桌面版才写回原路径。用网页版打开本地文件图层后，刷新页面或换设备时本地路径无法复现，这是浏览器安全模型的限制，不是缺陷。

2.2 在线版：零安装的第一步

2.2.1 打开与能力边界

访问 https://web.geolibre.app 即进入完整应用。它支持：

• 浏览器可选择的矢量数据（由 DuckDB-WASM Spatial 读取），GeoJSON、压缩 Shapefile、KMZ 等有直接处理路径。
• 把 GeoTIFF/COG 拖到地图上添加栅格图层。
• 通过 URL 添加服务与数据集：XYZ、WMS、GeoJSON URL、矢量瓦片、COG、ArcGIS 服务、FlatGeobuf、PMTiles、Zarr、LiDAR、Gaussian splats。
• 样式、属性表、SQL 工作区、Whitebox 工具箱、插件试用。
• 工程保存为下载文件、通过 Project → Share 上传。

需要桌面版的能力：本地文件对话框、本地 MBTiles、本地栅格读取、无浏览器文件选择器的工程保存/打开、Python sidecar。

2.2.2 安装为 PWA 与离线

Web 构建是可安装、可离线的 PWA。安装后：

• 应用外壳与静态资源走 Service Worker 缓存，断网仍能打开。
• Download Offline Area 可预缓存当前地图视图的底图瓦片。
• 首次使用后，CDN 加载的 Pyodide 与 PGlite/PostGIS 引擎也会被 Service Worker 缓存，浏览器内 SQL 与 Python 在离线时仍可用。

提示 离线能力取决于“先在线用过一次”。全新设备直接断网打开，底图与按需加载的引擎仍会缺失。

2.2.3 三条最常用的 URL 参数

网页版支持用 URL 直接打开内容，这是分享与嵌入的基础：

data= 支持 GeoJSON、GeoParquet、PMTiles、COG、LiDAR 点云（LAS/LAZ/COPC/EPT）、返回 GeoJSON 的 REST 端点，以及包含多个 GeoJSON 的 ZIP；style= 可应用矢量或栅格样式。

2.3 Windows 安装

2.3.1 Microsoft Store（推荐）

Store 构建已签名、自动更新、无需处理 SmartScreen。打开 https://apps.microsoft.com/detail/9nwt67rv531x，点击安装即可。

2.3.2 winget

winget 分发的是 GitHub Release 构建（未签名）：

winget install OpenGeos.GeoLibre

升级与卸载：

winget upgrade OpenGeos.GeoLibre
winget uninstall OpenGeos.GeoLibre

2.3.3 手动安装

从 https://github.com/opengeos/GeoLibre/releases 下载 .msi 或 -setup.exe 并运行。该构建未签名，Windows SmartScreen 可能提示；选择 More info → Run anyway 继续。

2.3.4 便携版（免安装）

下载名称形如 *-x64-portable.zip 的资源，解压到任意位置（包括 U 盘），运行 geolibre-desktop.exe。便携版：

• 不需要安装程序或管理员权限。
• 每次启动会为当前用户注册 org.geolibre.desktop: 登录链接的处理器（写入 HKCU\Software\Classes），这是它唯一的注册表改动。
• 不自动更新，升级需重新下载 zip。
• 依赖 Microsoft Edge WebView2 Runtime（Windows 11 与较新的 Windows 10 已预装；缺失时安装 Evergreen Runtime）。
• 可选的 Python sidecar 工具仍需要本机有 Python；Whitebox 工具箱走 WebAssembly，不需要。

2.3.5 验证安装

1. 启动应用，看到地图与左侧 Layers 面板。
2. Help → About 查看版本号，确认与下载的版本一致。
3. Add Data → Vector Layer，用示例 URL 加载一个小数据集，确认网络与 DuckDB-WASM 正常。
4. Project → Save 保存到本地，确认文件对话框出现（这是桌面版与网页版的关键差异）。
5. Help → Diagnostics 应无红色错误计数。

2.4 macOS 安装

2.4.1 Homebrew（推荐）或 DMG

Homebrew 是官方 Cask，无需 tap：

brew install --cask geolibre
brew upgrade --cask geolibre
brew uninstall --cask geolibre

手动安装：下载对应架构的 DMG（Apple Silicon 用 aarch64，Intel 用 x64），打开后把 GeoLibre Desktop 拖入 Applications，再从 Applications 启动。DMG 使用 Apple Developer ID 签名并经 Apple 公证，Gatekeeper 不会拦。

2.4.2 Mac App Store 与功能裁剪

Mac App Store 版本（org.geolibre.desktop）是同一个应用的沙盒构建，安装与更新走商店，但不能下载或运行会改变功能的可执行代码（App Store 指南 2.5.2），因此以下能力被编译掉：

沙盒还带来三个行为差异：

• 松散 Shapefile 必须一次选中所有分片（.shp、.dbf、.prj 等），或使用压缩包；单独选 .shp 会丢属性和 CRS。
• 沙盒应用不继承登录 shell 的环境变量，API key 要在 Settings 里填。
• 重新打开引用本地路径的工程时，之前的文件授权已随进程结束，需要重新添加该图层。

2.4.3 旧版本的 quarantine

v1.4.1 起的 DMG 已签名并公证。若你安装的是 v1.4.0 及更早（ad-hoc 签名），首次打开需要：

xattr -dr com.apple.quarantine "/Applications/GeoLibre Desktop.app"

每次升级后需要重复执行。

2.5 Linux 安装

2.5.1 六种渠道

Flatpak 首次需要添加远程：

flatpak remote-add --if-not-exists flatpark https://dl.flatpark.org/flatpark.flatpakrepo
flatpak install flatpark app.geolibre.GeoLibre

RHEL 系若没有 COPR 插件，先安装 dnf-plugins-core。openSUSE 安装 RPM 用 sudo zypper install --allow-unsigned-rpm ./...rpm。

2.5.2 AppImage 与增量更新

chmod +x GeoLibre.Desktop_<version>_amd64.AppImage
./GeoLibre.Desktop_<version>_amd64.AppImage

AppImage 需要 FUSE。发行版不再默认提供时，安装 libfuse2（如 sudo apt install libfuse2），或加 --appimage-extract-and-run 运行。

v2.3.0 之后的 AppImage 内嵌更新信息，并随发布提供 .zsync，可用 AppImageUpdate、AppImageLauncher、AppManager、AM 做差分更新：

appimageupdatetool GeoLibre.Desktop_<version>_amd64.AppImage
./GeoLibre.Desktop_<version>_amd64.AppImage --appimage-updateinfo

2.5.3 WebKitGTK：空白窗口、闪烁与性能

Linux 桌面使用 WebKitGTK。应用启动时会按 WebKitGTK 版本与 GPU 选择已知可用的渲染设置，多数系统无需配置：

应用判断 NVIDIA 的依据：启动显示由 nvidia 驱动、__NV_PRIME_RENDER_OFFLOAD 非 0，或 __GLX_VENDOR_LIBRARY_NAME=nvidia。它还会设置 GTK_USE_PORTAL=1，让文件对话框走桌面门户。

你显式设置的值永远优先——应用只填环境里没有的变量。若窗口空白、地图闪烁或平移很慢：

# 空白或闪烁：退回传统渲染器（更慢、最兼容）
WEBKIT_DISABLE_DMABUF_RENDERER=1 geolibre-desktop

# 被应用放到传统渲染器后很慢：试默认渲染器
WEBKIT_DISABLE_DMABUF_RENDERER=0 geolibre-desktop

geolibre-desktop 是 .deb、.rpm 与 AUR 包安装的命令；AppImage 运行文件路径；Flatpak 用 flatpak run --env=WEBKIT_DISABLE_DMABUF_RENDERER=1 app.geolibre.GeoLibre。

2.5.4 无 AVX 的 CPU

在老 Intel Celeron/Pentium N、Atom 或 Sandy Bridge 之前的 x86-64 机器上，WebKitGTK 可能在 GeoLibre 开始使用 WebAssembly 时直接杀掉渲染进程，窗口永远不绘制（WebKitWebProcess 中的 SIGILL）。应用会在 Linux 启动时检测 AVX，没有则固定两个 JavaScriptCore 选项：

JSC_useWasmOSR=false
JSC_useBBQTierUpChecks=false

两者必须成对生效。代价可控：在 WebKitGTK 2.52.6 上，一次 DuckDB-WASM 查询约慢 2 倍，而彻底关闭 WebAssembly JIT 会慢 34 倍。若仍崩溃，可退回 JSC_useBBQJIT=false。检测是运行时 CPU 特性测试，有 AVX 的机器与 arm64 不受影响。

2.6 Android、iOS 与 Chrome 扩展

2.6.1 Android

从 Google Play 安装（包名 org.geolibre.app），签名构建、自动更新：https://play.google.com/store/apps/details?id=org.geolibre.app。

侧载：每个 release 附带按 ABI 签名的 APK（现代手机几乎都是 geolibre-android-arm64.apk），允许未知来源后点击安装，或用 ADB：

adb install -r geolibre-android-arm64.apk

警告 Play 构建与侧载 APK 使用不同签名，Android 不会把一个升级成另一个。切换前先卸载现有版本（adb uninstall org.geolibre.app），否则会报签名冲突。

2.6.2 iOS

从 App Store 安装（iPhone/iPad）：https://apps.apple.com/app/geolibre/id6796039674。GeoLibre 不面向最终用户发布可侧载的 .ipa；release 中的 *_ios_app-store.ipa 是 App Store 提交包，不能直接安装。未发布版本需要自己在 Mac 上构建。

2.6.3 移动端能力裁剪

移动端隐藏依赖“本地桌面进程”的工具，避免展示无法运行的功能：

移动端的地图界面是响应式的：手机上 Layers/Style 面板以滑入式抽屉覆盖地图，面板边缘可拖拽调整，工具栏避开系统状态栏。

2.6.4 Chrome 扩展

Open data in GeoLibre 在 Chrome Web Store：https://chromewebstore.google.com/detail/open-data-in-geolibre/joinecgbfoldanidcoakpjgkbaceaooj。

它收集当前页面上的受支持数据集链接与地图服务（WMS、WMTS、WFS、OGC API - Features、ArcGIS Feature Services、XYZ/TMS、矢量瓦片），让你勾选后在同一个 GeoLibre 地图中打开；选项页可把目标指向自托管的 GeoLibre。也支持从 release 里的 geolibre-chrome-<version>.zip 解压加载。

2.7 从源码运行

2.7.1 前置条件

2.7.2 获取与安装

git clone https://github.com/opengeos/GeoLibre.git
cd GeoLibre
npm install

这是 npm workspaces 单仓库，根目录安装一次即可。根 trustedDependencies 允许 @google/genai、core-js、esbuild、protobufjs、sharp、workerd 的安装脚本。

2.7.3 开发模式

# 浏览器开发服务器（http://localhost:5173）
npm run dev

# 桌面应用（需要文件对话框、本地 MBTiles、本地栅格时用这个）
npm run tauri:dev

浏览器开发服务器支持 DuckDB-WASM Spatial 能读的本地矢量文件（GeoJSON、zip Shapefile、KMZ 有直接路径），也可拖入 GeoTIFF/COG。但文件系统对话框、本地 MBTiles、本地栅格读取、工程保存/打开等操作依赖 Tauri。

2.7.4 构建与产物位置

npm run build          # Web 生产构建
npm run tauri:build    # 桌面安装包
npm run tauri:build:native-duckdb   # 启用原生 duckdb-rs 的更大二进制

在 Linux 上默认构建 deb 与 rpm；传入 --bundles 会替换默认选择而不是追加，所以三种格式都要时写成：

npm run tauri:build -- --bundles deb,rpm,appimage

2.7.5 常用命令

后端测试前置：pip install -e "backend/geolibre_server[test]"，否则矢量/栅格/SQL/ML 测试会自动跳过。

2.7.6 Docker 单容器

docker build -t geolibre .
docker run --rm -p 8080:80 geolibre

或直接拉取已发布镜像：

docker pull ghcr.io/opengeos/geolibre:latest
docker run --rm -p 8080:80 ghcr.io/opengeos/geolibre:latest

打开 http://localhost:8080。容器内是 nginx 服务的静态构建，可选 sidecar 反向代理在 /sidecar：

• 仅当部署策略授予 processing:run 或 data:add 且未设置 GEOLIBRE_DISABLE_SIDECAR=1 时，uvicorn 才启动。
• 同源访问示例：http://localhost:8080/sidecar/conversion/status。
• sidecar 只能在它自己的文件系统里读写，路径限制在 GEOLIBRE_CONVERSION_ROOTS（镜像内默认 /data）。挂载数据：

docker run --rm -p 8080:80 -v "$PWD/data:/data" ghcr.io/opengeos/geolibre:latest

• 只要 nginx（纯 Web 行为）：-e GEOLIBRE_DISABLE_SIDECAR=1。
• 密码保护：-e GEOLIBRE_AUTH_USER=admin -e GEOLIBRE_AUTH_PASSWORD='change-me'，nginx 会对应用与 /sidecar 启用 HTTP Basic Auth（单组共享凭据）；/healthz 不鉴权以保持健康检查。
• 镜像不含 pyodbc 与 Microsoft ODBC Driver 18；SQL Server/Azure SQL 需要派生镜像安装驱动与 [mssql] extra。
• freestiler 与 whitebox-workflows 没有 linux/arm64 wheel，只在 amd64 安装；浏览器自身的 PMTiles 与 Whitebox 引擎是 WebAssembly，任何架构都能跑。

2.7.7 docker compose：带分享、协作与数据库

仓库根的 docker-compose.yml 会同时启动 Web、项目服务端、Node 协作中继与 Postgres：

POSTGRES_PASSWORD=choose-a-password docker compose up --build

POSTGRES_PASSWORD 是必填而不是默认值：它拥有全部项目元数据，若提交到仓库就会在每个部署上相同。Compose 未设置时会报错退出。

打开 http://localhost:8080；项目 API 在 http://localhost:8000，协作中继在 ws://localhost:8787。

警告 密码会被原样代入数据库连接串，两个字符要当心：@ 会提前截断 URL（p@ssw0rd 被解析成密码 p、主机 ssw0rd@postgres），% 会触发百分号转义。要么避开这两个字符，要么在 URL 中百分号编码（%40、%25），同时保持 POSTGRES_PASSWORD 为字面密码。

Postgres 只在初始化数据目录时应用密码；之后修改密码不会改变已有卷上的密码。要轮换，在运行中的数据库里 ALTER USER，或重建卷。

2.8 可选凭据、国内底图与离线镜像

2.8.1 影像与街景凭据

在 apps/geolibre-desktop/.env.local 中设置：

VITE_GOOGLE_MAPS_API_KEY=your_google_maps_api_key
VITE_MAPILLARY_ACCESS_TOKEN=your_mapillary_access_token

• Google Street View 需为该 key 启用 Maps Embed API；Google Photorealistic 3D Tiles 需启用 Map Tiles API。
• 本地 shell 测试也可用 GOOGLE_MAPS_API_KEY。
• Mapillary 在开发者面板创建应用，使用 client access token。
• 也可以直接在 Street View 面板的 API key 输入框填入并应用；该值会保存（桌面进系统凭据库、网页进浏览器存储），重启后仍在，并优先于同名环境变量。

2.8.2 底图与交通图层

交通叠加在 Basemaps 控件的 Traffic 分类中，可叠加在任意底图上（需打开面板的 add/multiple 开关）。

2.8.3 Cesium Ion

Cesium 地球在没有 token 时也可用，会铺工程的底图；token 解锁 Cesium World Terrain 与 Ion World Imagery。设置方式：

CESIUM_TOKEN=your_cesium_ion_access_token

CESIUM_TOKEN 或 VITE_CESIUM_TOKEN 会被 vite.config.ts 读取并烘进构建。也可以运行时在 Settings → Environment Variables 的 Cesium Ion token 字段设置，无需重建；它保存在本机，不写进工程文件，并覆盖构建时值。

提示 托管网页版自带演示 token；桌面与移动端需要你自己的 token。Ion token 设计上允许出现在客户端包里，请在 Ion 控制台把它限制到部署实际需要的资产。

2.8.4 地理编码

Settings → Geocoding 选择 Provider。Nominatim 是默认且无需 key；需要 key 的 Provider 在该页填写 API key。还可覆盖 Forward endpoint 与 Reverse endpoint（例如指向自托管实例），并给 Nominatim 填联系邮箱。

注意 key 以查询参数发送，会出现在请求 URL 中。使用 ArcGIS GeocodeServer（organization）时，端点字段会变成命名 Locator 列表，每个 Locator 有服务 URL、可选门户与 Check service 按钮。

2.8.5 国内底图与 GCJ-02 警告

GeoLibre 默认底图（OpenFreeMap、Protomaps）托管在中国大陆以外，在中国境内可能很慢或不可达。有两个地方提供境内底图：

• Regional 区（无需 key）：New project 与 Change Basemap 都有折叠的 Regional → China（中国），包含高德地图、高德卫星、高德混合、腾讯地图、腾讯深色。
• Basemaps 控件（增加天地图）：同一批高德/腾讯瓦片，加上天地图（矢量、影像、地形，各带独立标注层）。搜索 Tianditu、Amap、Tencent 或中文名。天地图需要免费 key：https://console.tianditu.gov.cn/api/key。

警告 中国法规要求公开地图服务以 GCJ-02 发布，该基准相对 WGS84 有约 100–700 米的偏移；GeoLibre 与 MapLibre 都不会自动纠正。在高速高德/腾讯底图上叠加自己的数据会明显错位。只要地图还带自己的数据，优先用天地图（CGCS2000，与 WGS84 足够接近）。高德/腾讯瓦片端点并非公开文档 API，适合探索，做产品前应向提供商申请商业 key。

2.8.6 离线与内网镜像

Pyodide 默认从 jsDelivr 加载，DuckDB Spatial 扩展默认从 DuckDB 扩展仓库安装。离线或内网部署可指到镜像：

VITE_PYODIDE_INDEX_URL=https://your-host/pyodide/v0.27.7/full/
VITE_DUCKDB_SPATIAL_EXTENSION_PATH=https://your-host/duckdb/spatial.duckdb_extension.wasm

两者都能在 Settings → Environment Variables 运行时设置，无需重建。

构建期还有一组开关：

2.8.7 环境变量写在哪一层

同一个 key 有两个落点，选错会让“改了没生效”：

运行时设置优先，且可逐条启用/禁用；敏感值会掩码显示。桌面版还会把 AI 相关的系统环境变量（如 OPENAI_API_KEY）作为兜底读取，但界面里填的值优先。

2.9 Python sidecar 与 extras

2.9.1 启动

可选 FastAPI sidecar 面向更重的处理流程，桌面 UI 本身不依赖它：

cd backend/geolibre_server
python -m venv .venv
source .venv/bin/activate
pip install -e .
uvicorn geolibre_server.app.main:app --host 127.0.0.1 --port 8765

sidecar 首次使用会自举一个受管运行时；想复用当前环境，设置 GEOLIBRE_CONVERSION_PYTHON=$(which python)。

2.9.2 extras

基础安装刻意很小，按需安装：

pip install -e ".[conversion]"   # DuckDB、rio-cogeo、freestiler
pip install -e ".[vector]"       # GeoPandas、Shapely
pip install -e ".[raster]"       # rasterio、numpy、contourpy
pip install -e ".[ml]"           # AI Segmentation 代理（只是 HTTP 客户端）

在仓库根目录用完整路径，例如 pip install -e "backend/geolibre_server[conversion]"。

2.9.3 浏览器同源代理与限制

要把 sidecar 用于 Web 构建，启动它并从 localhost:5173 提供应用：CORS 只允许该源与 Tauri 源。Docker 镜像则在同源 /sidecar 反向代理。sidecar 的读写限制在 GEOLIBRE_CONVERSION_ROOTS；其 PostGIS 端点默认拒绝任何目标，直到 GEOLIBRE_POSTGIS_HOSTS 列出允许的数据库。

2.9.4 什么时候真的需要 sidecar

工具对话框在 sidecar 或其 extra 不可用时会自动回退到浏览器引擎。

2.10 第一个地图：从空工作区到可分享工程

这一节把官方 Your First Map 教程扩展成一条完整链路：加数据 → 样式 → 查看属性 → 保存/分享 → 导出验证。全程可在网页版完成；用到本地保存时请换桌面版。

2.10.1 目标与准备

完成后你会得到：

• 一个含 countries 图层的工程，按人口或 GDP 分级着色。
• 能打开属性表、排序、搜索与 Explore。
• 一个 .geolibre 文件与一个分享链接。
• 一份导出的 GeoParquet/CSV 作为下游数据。

示例数据是公开的 GeoParquet 世界国家数据集：

https://data.source.coop/giswqs/opengeos/countries.parquet

2.10.2 新建工程与选择底图

1. 打开 https://web.geolibre.app 或桌面应用。
2. Project → New…，输入工程名，例如 World Countries。
3. 在底图库中选择一个底图：OpenFreeMap 样式、Protomaps（有 key 时）、Regional 中国区、行星底图、空白背景或自定义样式 URL。
4. 点击创建。工作区出现地图与空的 Layers 面板。

2.10.3 添加数据

1. 打开 Add Data → Vector Layer。
2. 在 Add Vector 面板的 URL 字段填入上面的 countries.parquet 地址。
3. 点击 Load。
4. 等待 DuckDB-WASM Spatial 读取完成；地图自动缩放到数据范围，Layers 面板出现 countries 图层。

提示 首次加载 GeoParquet 会初始化 DuckDB-WASM 与 spatial 扩展，比后续加载慢。看到网络面板里有扩展下载属正常现象；离线部署请按 2.8.6 配置镜像。

2.10.4 符号化

1. 在 Layers 面板选中 countries。
2. 若右侧 Style 面板折叠，点击 Style 标签展开。
3. 先做基础样式：调整 Fill color、Outline color、Fill opacity。
4. 做分级设色（choropleth）：
   • Style type 设为 Graduated。
   • Attribute 选择数值字段，例如 POP_EST 或 GDP_MD_EST。
   • 设置 Classes（分类数）、Scheme（分级方法）与 Colormap。
   • 点击 Apply style type。
5. 检查图例与颜色是否可读；必要时回到 Style 面板调整分类断点或换色带。

2.10.5 查看属性

1. 点击状态栏的 Attribute table 展开底部表格。
2. 选中 countries 图层加载记录。
3. 按任意列排序，或在 Search attributes 中输入关键字定位要素；选中行会在地图上高亮。
4. 点击 Explore 一次查看每个字段的类型、完整度与取值分布。
5. 打开图层的 Identify features，点击地图上的国家，弹窗显示其属性。

2.10.6 保存

• 桌面版：Project → Save，选择路径写入 .geolibre。
• 网页版：Project → Save 使用浏览器保存对话框（Chromium 系）或下载文件。
• 需要副本时用 Project → Save As…；想在不影响原文件的前提下试验，用 Project → Duplicate project。

保存的内容包括当前地图视图、底图、图层与样式、地图偏好与插件状态。工程保存的是引用：countries 图层仍指向那个 URL，而不是把数据复制进文件。

2.10.7 分享

1. Project → Share…。
2. 首次使用需连接账号：网页版点 Sign in（弹窗到 share.geolibre.app 同意页）；桌面版在系统浏览器完成并回到应用；移动端/Notebook 可粘贴个人 API token。
3. 分享对话框会做就绪检查：列出接收方打不开的图层及原因（凭据被剥离、浏览器无法跨域、服务 404、私有/本地网络地址）。
4. 若存在本地文件图层，会提示 N layers will be missing from the shared map，此时按钮变为 Share anyway。
5. 上传成功后得到公开链接，可在 live viewer 打开。

警告 分享上传的是工程文件，不是你的数据。本地 GeoTIFF、GeoPackage、Shapefile 或查询结果图层不会随工程上传；要让别人看到，请把数据放到可公开访问的 HTTPS 位置并改用 URL 添加。

2.10.8 导出与验证

1. 属性表 → Export 或图层操作菜单导出 GeoParquet/CSV，确认数据可被下游读取。
2. Project → Export → Export as HTML… 生成单文件离线 HTML，用浏览器直接打开，确认底图与图层都在。
3. Project → Print Layout… 导出 PNG/PDF，检查标题、图例、比例尺与指北针。
4. 重新打开保存的 .geolibre，确认视图、样式与图层顺序与保存时一致。

2.10.9 完整检查表

2.11 常见安装与启动问题

提示 桌面版启动异常时先看 Help → Diagnostics：它统计本次会话的错误与警告，捕获原生 Tauri HTTP 请求，并对失败的 fetch() 分类。报告问题时附上这里的诊断信息，比截图更有用。

2.12 本章小结

• 五条路径分别对应 Web、桌面、移动、Jupyter 与 R；是否需要本地文件与 sidecar 是选择桌面版的关键判断。
• 工程以 .geolibre 保存，仍可打开 .geolibre.json；网页版保存走下载，桌面版写回路径。
• Windows 优先 Store 或 winget；macOS 优先 Homebrew，Mac App Store 版有明确的功能裁剪；Linux 有 AUR/COPR/Flatpak/deb/rpm/AppImage 六种渠道。
• Linux 的 WebKitGTK 渲染器与无 AVX CPU 都有自动处理逻辑，必要时可用环境变量覆盖。
• 移动端隐藏依赖本地进程的工具；Play 与侧载 APK 签名不同，不能互相升级。
• 源码开发需要 Node 22+ 与 Rust（桌面）；npm run dev 跑浏览器，npm run tauri:dev 跑桌面；构建产物位置固定。
• Docker 与 compose 覆盖从单容器到带分享/协作/数据库的完整自托管形态。
• 可选凭据分构建期（.env.local）与运行时（Settings → Environment Variables）两层；国内底图要注意 GCJ-02 偏移。
• Python sidecar 是可选增强，extras 按需安装；Web 使用需同源代理与路径白名单。
• 第一个地图的完整链路是：新建工程 → 加数据 → 样式 → 属性 → 保存 → 分享 → 导出验证。

2.13 实践练习

1. 安装并验证：在你的系统上选择一条安装路径，完成 2.3.5 或对应平台的验证清单，记录版本号与 Diagnostics 状态。
2. 容器部署：用 Docker 启动 Web 版，挂载一个本地数据目录到 /data，在 Add Data 中通过 /sidecar 完成一次格式转换（若 sidecar 被禁用，说明原因）。
3. 离线镜像：为一个内网部署写出 VITE_PYODIDE_INDEX_URL 与 VITE_DUCKDB_SPATIAL_EXTENSION_PATH 的配置，并说明如何验证镜像生效。
4. 第一个地图：按 2.10 完整走一遍，保存工程并分享；再用无痕窗口打开分享链接，记录就绪检查提示了哪些问题。
5. 移动端差异：在 Android 或 iOS 上打开同一份工程，列出三个与桌面不同的行为，并解释原因。
6. 故障排查：故意不设置 POSTGRES_PASSWORD 启动 compose，记录报错信息；再设置一个包含 @ 或 % 的密码，观察并解释失败原因。