第01章 - GeoLibre 概述与核心理念

本章回答四个问题：GeoLibre 到底是什么、它为什么这样设计、它现在能做什么、以及它适合谁。读完本章，你应当能判断一个具体任务该不该交给 GeoLibre，并知道后续章节分别深入哪一块能力。

本教程基于 GeoLibre 3.4（仓库 package.json 中 version 为 3.4.0），所有功能名、菜单路径与参数名以该版本仓库中的实现与文档为准。

1.1 定位：一个能在任何宿主里打开的 GIS 工作区

1.1.1 一句话定义

GeoLibre 的官方定义是：一个免费开源、轻量、云原生的 GIS 平台，用于可视化、浏览与分析地理空间数据。它同时运行在网页浏览器、桌面、移动端与 Jupyter Notebook 中，并且默认让数据留在本地。

这句话里有三个关键词，对应三种不同的取舍：

“云原生”在这里不等于“必须联网”。它指的是数据组织方式：GeoLibre 可以直接对远程对象存储里的云优化文件发起分段读取，而不必先把整份数据下载下来；同一套能力在断网时依然可以处理本地文件。

1.1.2 它不是什么

明确边界比罗列功能更有用。根据官方文档的自我描述，GeoLibre 不是：

1. 不是 QGIS 的替代品。 官方在对比文档里用“专业相机与手机相机”作类比：QGIS 成熟、强大、可扩展；GeoLibre 追求可及性、跨平台与“打开就能用”。两者服务不同的人与不同的时刻。
2. 不是在线 SaaS。 网页版是托管在 GitHub Pages 上的静态站点，没有服务器账号，数据在浏览器会话内本地处理。只有当你主动添加远程 URL 或主动分享工程时，数据才会离开浏览器。
3. 不是纯地图查看器。 它带有 1,000+ 地理处理工具、空间 SQL、属性表编辑、符号化、打印布局与故事地图，属于“做数据工作”的工具，而不是只用来“看地球”的工具。
4. 不是企业级地理数据库管理系统。 版本化编辑、复制、企业地理数据库运维不在它的范围内，这类需求仍应交给 ArcGIS 体系或 PostGIS 工程实践。

1.1.3 四类工具的定位对比

1.2 设计哲学：本地优先、云原生、跨平台

1.2.1 本地优先（Local-first）

GeoLibre 把“数据默认留在本地”当作产品承诺，而不是一句营销话。具体表现为：

• 网页版把矢量、栅格、SQL 计算全部放在浏览器内完成；托管的公开站点只统计页面访问量，分析代码看不到你加载的数据。
• 分享工程时上传的是工程文件（图层引用、样式、视图状态），不是你磁盘上的数据文件；本地文件图层会在分享前被明确警告。
• 需要完全私有化时，可以把同一份 Web 构建部署到自己的服务器，与数据同源放置。
• 桌面版提供本地文件对话框、MBTiles、本地栅格读取、工程保存/打开等浏览器做不到的能力。

提示 “本地优先”不等于“离线优先”。GeoLibre 的底图、云原生数据、在线目录都需要网络；它的意思是计算与数据归属在本地，而不是所有资源都已缓存。离线使用请参考桌面版、PWA 与“Download Offline Area”工具。

1.2.2 云原生（Cloud-native）

GeoLibre 的云原生性体现在数据格式与访问方式上，而不是“提供一个云服务”：

这套组合的意义是：你不需要先建一个 GIS 服务器，才能用云上的数据。 一个放在对象存储里的 GeoParquet 或 COG，可以直接被浏览器按需读取；需要服务端时，也支持 WMS/WFS/WMTS、ArcGIS 服务与自托管目录。

1.2.3 跨平台（One codebase, many hosts）

GeoLibre 用同一套 React 代码库构建多种宿主：

同一份 .geolibre 工程可以在这些宿主之间移动，是这套设计最实际的好处：在桌面做数据准备，在网页分享结果，在 Notebook 里用 Python 复现，在手机上查看现场。

1.2.4 可审计、可撤销的自动化

GeoLibre 的 AI 能力被刻意设计成“通过应用执行操作”，而不是“让模型直接改文件”：

• AI 助手把自然语言请求转换成 GeoLibre 操作（空间 SQL、符号化、增删数据、地图控制），这些操作走应用自己的命令通道，因此可审计、可撤销。
• 每次地理处理都会进入 Processing History，可一键重跑并复制等价 Python 代码。
• MCP 服务器（geolibre-mcp）以无头方式编写 .geolibre 工程，读写被限制在 --root 或 GEOLIBRE_MCP_ROOTS 指定的根目录内。
• 部署侧另有 capability 模型，可按 project:edit、data:add、processing:run、export:data、plugins:install、settings:manage 六项能力独立收紧界面。

注意 AI 助手默认关闭，直到你配置了 Provider 与凭据。它不是一个“云端代做 GIS”的服务：模型只产出操作意图，真正的执行仍在你的浏览器/桌面进程里。

1.2.5 各宿主共享的行为契约

跨平台最容易“看起来一样、用起来不一样”。GeoLibre 用一份行为契约来约束差异，判断一个功能在哪端可用时，可以按这张表核对：

看表的规律很清楚：越靠近“本地文件系统与本地进程”，桌面越是唯一完整答案；越靠近“分享与嵌入”，Web 越是首选。

1.3 项目脉络：从 v0.1 到 v3.4

1.3.1 关键里程碑

GeoLibre 的 docs/roadmap.md 按版本记录了全部发布内容。下面抽取对理解产品形态最有帮助的节点：

提示 版本号不是“功能开关”。GeoLibre 的工程文件带 version 字段（当前写入 0.2.0），但应用版本与工程格式版本是两条线；用 3.4 打开早期工程通常无需迁移。

1.3.2 三条主线

回看这条版本线，可以把它归纳为三条同时推进的主线：

理解这三条主线，就能理解 GeoLibre 的功能为什么这样分布：入口尽量的宽，分析尽量留在客户端，产出尽量做成可带走的文件。

1.3.3 本教程的版本基准

1.4 核心能力全景

1.4.1 1,000+ 浏览器内地理处理工具

Processing → Whitebox Toolbox 打开的工具箱包含 1,000+ 个地理处理工具，通过 WebAssembly 运行时在浏览器内执行，具备原生栅格与矢量 I/O。它们来自 Whitebox Next Gen 套件加上 GeoLibre 自有的 WASM 工具，按类别组织：

合计 1,068 项（按上表逐项相加）。此外，Processing → GeoLibre Toolbox 下还有矢量工具（Turf.js 客户端、可选 GeoPandas/Pyodide 或 sidecar 引擎）、栅格工具（rasterio sidecar，带客户端回退）、Conversion、Spatial Statistics 与 Network 工具。这两套工具箱在同一个 Processing 菜单里，因此部分类别名会出现两次，这是正常现象。

注意 “浏览器内执行”意味着数据不上传，但也意味着受浏览器内存与 WebAssembly 限制。多 GB 的本地处理任务仍应交给桌面 GIS；GeoLibre 的定位是“把大部分常见分析放到手边”，不是“无限算力”。

1.4.2 四种渲染引擎

同一个工程可以切换四种渲染引擎（View → Rendering engine），并且可以在分屏中混用：

引擎选择随工程保存；切换时相机、图层、分组、可见性、透明度与受支持的样式会保留。菜单、工具与插件会按当前引擎的能力进行门控。

1.4.3 SQL 工作区与三种引擎

SQL 工作区（Processing → SQL Workspace）支持三种引擎：

裸 URL 会自动包裹成匹配的读取器并发起 HTTP Range 请求；结果可以加回地图，也可以导出为 CSV 或 GeoParquet。SQL 工作区可停靠为地图旁的调整大小面板，并带表名、列名与关键字自动补全。

1.4.4 AI 助手、MCP 与智能体技能

Provider 支持 Google Gemini、Anthropic、OpenAI、OpenRouter、Vercel AI Gateway、Amazon Bedrock、本地 Ollama，以及任意 OpenAI 兼容端点。凭据保存在本机（桌面进系统凭据库），不写进共享工程文件。

1.4.5 插件系统与插件市场

• 内置插件覆盖图层控制、底图、MapLibre 组件、卷帘、街景、时间滑块、Overture Maps、LiDAR、GeoAgent、GeoEditor、大气效果等。
• 外部插件通过 plugin.json 清单从 zip、目录或市场安装；市场安装与更新会校验发布的 bundle hash，并遵守 registry blocklist。
• 插件可以注册右侧面板、工具栏菜单与浮动面板，可以声明支持的渲染引擎，也可以向 AI 助手注册工具与提示词。

插件 API 的细节留给第21章 插件系统与插件开发。

1.4.6 工程格式与产出

一个 .geolibre 工程文件装下：地图视图、底图、每个图层的源与样式、地图偏好、插件状态、图例、打印布局、故事地图、Dashboard 部件、书签、交互状态与元数据。工程是引用式的：它保存图层来源，而不是把远程数据复制进文件。

产出渠道包括：

• 单文件离线 HTML（Project → Export → Export as HTML…），可离线打开、无需服务器。
• 打印布局导出 PNG/PDF/可编辑 SVG，支持图集（Atlas / map series）。
• 故事地图与故事地图的独立 HTML 导出。
• 分享链接（share.geolibre.app 或自托管服务）。
• 样式与图层文件：SLD / QML / Mapbox GL JSON / GeoLibre URL style、图层样式文件、图层列表文件。

1.4.7 数据入口矩阵

1.4.8 主要产出格式

GeoLibre 的产出并不只有“分享链接”。不同任务对应不同格式，选错格式会让下游多走很多弯路：

提示 工程文件是“引用”，导出格式是“数据”。要交付给别人长期保存时，优先导出 GeoParquet/COG 这类自包含数据，再把工程里的图层指向它，而不是把数据塞进工程。

1.5 与主流平台的对比

官方对比文档把对象限定为 QGIS、ArcGIS Pro、ArcGIS Online、CARTO、Felt、kepler.gl，并单独讨论 Google Earth。下面抽取结论性内容，完整表格见仓库 docs/comparison.md。

1.5.1 定位速览

1.5.2 数据与格式

结论很直接：格式广度上 QGIS 仍然第一，GeoLibre 的优势在“云原生格式 + 浏览器内直接读”。 File Geodatabase 这类格式只有桌面版可用。

1.5.3 分析与制图

1.5.4 与 QGIS：互补而非竞争

官方把两者比作“专业相机”与“手机相机”，这个类比值得完整理解：

• QGIS 提供极大的能力、灵活性与控制力，是专业制图、复杂格式与重处理任务的首选。
• GeoLibre 优先考虑可及性、便利性与即时分享，让没有复杂安装环境的用户也能处理空间数据。
• 两者可以组合：在 QGIS 中做数据准备与制图，把结果发布/嵌入为 GeoLibre 工程；GeoLibre 能直接读 QGIS 的 .qgs/.qgz 工程与 QML 样式。

1.5.5 与 ArcGIS 家族

• ArcGIS Pro：企业地理数据库编辑与版本化、最深的 3D 与影像工作流、专业工具箱，仍是 Esri 生态内不可替代的部分。GeoLibre 能读 .aprx/.mapx 的部分内容（第一幅二维地图的范围、本地矢量与 GeoTIFF、嵌套分组、可见性、简单符号、字段标注、矢量瓦片门户项、缓存地图服务），但不支持 File GDB、场景与网络共享路径。
• ArcGIS Online：重点是托管图层、组织共享与权限，以及 Dashboards/StoryMaps/Field Maps/Experience Builder 这套应用家族。GeoLibre 的差异在于工程可带走、可离线、可自托管。

1.5.6 与 CARTO、Felt、kepler.gl

1.5.7 与 Google Earth / Google Earth Pro

Google Earth 是“虚拟地球”，GeoLibre 是“恰好带地球的 GIS”。两者的重叠只在“看”的瞬间：

Google Earth 仍更强的地方是影像档案、历史影像、街景与真实感三维；GeoLibre 更强的是“看之后的一切”：属性、连接、工具箱、SQL、数据驱动符号化、打印布局、重投影与开放工程文件。

1.5.8 选择结论

1.6 技术栈与架构鸟瞰

本节只建立“地图”，细节留给第23章 源码架构与二次开发。

1.6.1 技术栈

1.6.2 仓库版图

1.6.3 单向数据流

应用是 store-driven 的，数据流严格单向：

1. 数据入口：Add Data、Tauri 文件对话框、文件选择、拖拽或插件发起加载。
2. 解析：本地矢量优先由 DuckDB-WASM Spatial 读成 GeoJSON（INSTALL spatial; LOAD spatial; ST_Read）；GeoParquet 走 Parquet reader；zip Shapefile 走 shpjs 并以 DuckDB 兜底；KMZ 客户端解压。
3. 入库：调用 addGeoJsonLayer，生成 GeoLibreLayer 记录写入 Zustand store。
4. 订阅：MapCanvas 订阅 layers，MapController.syncLayers 比较前后差异，协调 MapLibre 的 source/layer 增删改。
5. 回写：用户编辑走 store action，再由第 4 步反映到地图。

这条链路有一条硬规则：禁止 UI 直接修改 MapLibre 对象。要让地图变化，就改 store，让同步层去应用。否则撤销/重做、工程保存与协作补丁都会与地图实际状态脱节。

提示 这条规则同样适用于二次开发与插件开发。插件通过宿主 API 注册图层与面板，而不是自己抓 map 对象硬改；这样切换渲染引擎时插件才能被正确挂起与恢复。

1.6.4 渲染分层

• MapLibre 主图：矢量、栅格瓦片、COG、PMTiles、WMS/WMTS 等；样式与图层顺序由 store 同步。
• deck.gl 叠加：点云、3D Tiles、I3S、Gaussian splats、Deck.gl Layer builder 图层。
• Cesium 地球：作为主图时替换整个工作区（旧画布卸载）；作为分屏时与二维相机同步。
• Mapbox / ArcGIS：各自的原生图层体系，能力按引擎门控。

四种引擎共享同一份工程状态，因此“切换引擎不丢图层”是设计目标，而不是逐引擎重做一遍工程。

1.6.5 可选服务端

这些组件全部可选。GeoLibre 的核心工作流（加载、样式、属性表、矢量工具、Whitebox、DuckDB SQL、打印、导出）在一个静态 Web 构建里即可完成。

1.6.6 嵌入协议与协作

如果要把 GeoLibre 嵌进自己的系统，需要理解两条“对外接口”：

（1）iframe 的 postMessage 协议。 宿主页面通过版本化协议控制被嵌入的应用，协议 v2 为当前版本，v1 宿主仍受支持。典型命令包括：加载工程、移动相机、高亮要素、打开处理工具、切换与列出图层、应用过滤、读取视口、添加图层、导出 PNG，以及 getLayerFeatures 与 getDrawnFeatures 读回要素。

应用回传的事件：

协议默认关闭，除非部署方用 GEOLIBRE_EMBED_ORIGINS 声明可信来源；来源白名单决定“谁能发命令”，部署 capability 决定“哪些命令存在”，两者是独立的两道闸门。

（2）类型化客户端。 geolibre/embed 把上述协议封装成 Promise 风格的 API：connect() 在应用就绪后 resolve，每个命令返回与 ack 关联的 Promise，事件按名称订阅。它的版本随 GeoLibre 发布，避免手写 postMessage 的字符串与竞态。

注意 嵌入 API 不是“远程控制任意部署”的通道。没有配置可信来源时它完全关闭；即使开启，也只对白名单来源开放，并受部署能力约束。

1.7 平台矩阵与分发渠道

1.7.1 平台矩阵

1.7.2 桌面分发细节

1.7.3 包与嵌入

1.7.4 更新与信任模型

• GitHub Release 的 Windows 构建未签名，首次运行可能触发 SmartScreen；Store 构建已签名并自动更新。
• macOS DMG 自 v1.4.1 起用开发者 ID 签名并经 Apple 公证，正常打开无需绕过 Gatekeeper；更早的版本需要 xattr -dr com.apple.quarantine。
• 外部插件是受信任代码：安装即授予其与应用同源的权限。市场安装会校验 bundle hash，但沙箱隔离不是插件模型的一部分。
• 桌面版把 API key、token 等敏感值放进系统凭据库；网页版只能放在浏览器存储中，这是“同源脚本可读”的已知权衡。

1.7.5 自托管与服务端形态

自托管不是“二选一”，而是按需要叠加：

关键运行时变量（容器启动时读取，改完重启即可生效，无需重建镜像）：

警告 远程服务必须使用 TLS：应用可能向配置的服务发送凭据。分享/GeoLens 用 https://，协作中继用 wss://；不合规的值会让容器启动失败，而不是悄悄回退到公共服务。

1.8 适用与不适用场景

1.8.1 适合的场景

1. 需要“打开就能用”的 GIS：教学、培训、评审、客户演示，不想让参与者先装软件。
2. 数据不能上传：涉密、受控或客户数据只能留在本机；网页版在浏览器内完成计算。
3. 云原生数据工作流：数据在对象存储里以 COG/GeoParquet/PMTiles/Zarr 存放，需要按需读取与快速预览。
4. 跨端交付：同一份工程在桌面制作、网页分享、手机查看、Notebook 复现。
5. 嵌入到自己的产品：需要开放工程格式、MIT 许可、可版本化的 iframe API 与可自托管部署。
6. 浏览器内的中等规模分析：矢量叠加与缓冲、地形/水文、光谱指数、点云分类、空间 SQL。

1.8.2 不适合的场景

官方在对比文档里明确列出了 GeoLibre 不占优的领域：

1.8.3 组合使用的建议

• QGIS 做数据工程，GeoLibre 做交付：在 QGIS 中整理图层与样式，导出 QML/SLD，GeoLibre 导入样式并把工程分享为网页或单文件 HTML。
• ArcGIS Pro 做权威数据，GeoLibre 做外业查看：Pro 维护企业地理数据库，GeoLibre 通过 ArcGIS 服务或导出文件查看与轻量编辑。
• Python/Notebook 做批量实验，GeoLibre 做可视化验证：用 geolibre Python 包在 Notebook 内嵌应用，边算边看。
• 自托管做团队门户：Docker 部署 Web 应用 + 自托管分享/协作服务，数据与应用同源，避免 CORS 与凭据外泄。

1.8.4 从其它工具迁移的检查清单

把既有工作搬到 GeoLibre 之前，按顺序核对这八项，能避免大部分“打开了但不对”的问题：

1. 数据格式：列出全部源文件格式，标出 GDAL 专有或 GeoLibre 只读的格式（如 File GDB、CAD、专有影像格式）。
2. 坐标系：确认每个图层的 CRS 是否写在数据里；没有 .prj 的 Shapefile 需要手工指定。
3. 数据规模：估算要素数与栅格尺寸；超过浏览器舒适区间的数据先切分、聚合或转云原生格式。
4. 远程服务：检查 WMS/WFS/ArcGIS 服务是否允许跨域、是否使用 token；共享前先看 Share 的就绪检查。
5. 符号与标注：确认 QML/SLD 能否覆盖现有样式；不支持的符号需要手工重建。
6. 分析流程：把桌面工具箱流程映射到 Whitebox、GeoLibre Toolbox、SQL 或 Model Builder，记录没有等价物的步骤。
7. 产出要求：是否需要打印图集、PDF 报告、单文件 HTML 或嵌入页面，提前验证打印布局与导出效果。
8. 数据托管：决定本地文件、对象存储还是数据库；本地文件图层在分享时会被明确列出“将缺失”。

1.9 许可、引用、社区与贡献

1.9.1 MIT 许可

GeoLibre 使用 MIT 许可证。对你的实际含义：

注意 MIT 只覆盖 GeoLibre 自身代码。它依赖的第三方库、底图服务、影像服务与数据各有自己的许可与条款；商用前请逐一确认，尤其是底图与影像提供商。

1.9.2 引用

GeoLibre 在 Zenodo 上归档，每次发布都会生成 DOI；概念 DOI 始终解析到最新版本。

Wu, Q. (2026). GeoLibre: A lightweight, cloud-native GIS platform for
visualizing, exploring, and analyzing geospatial data. Zenodo.
https://doi.org/10.5281/zenodo.20785400

BibTeX 与 APA 条目可从仓库根的 CITATION.cff 获取，也可用 GitHub 的 “Cite this repository” 按钮直接复制。

1.9.3 社区与支持渠道

1.9.4 贡献入口

本地质量门禁的核心命令是 npm run ci（lint + 前端构建与测试 + 测试类型检查 + 后端 + Rust 检查）。只想先跑前端时用 npm run ci:frontend。

1.9.5 术语约定

本站教程中的术语按下列约定使用，与界面英文保持一致：

1.9.6 本教程的章节地图

1.10 本章小结

• GeoLibre 是 MIT 许可的免费开源、轻量、云原生 GIS 平台，同一套代码运行在 Web、桌面、Android、iOS 与 Jupyter 中，数据默认留在本地。
• 三条设计承诺是本地优先、云原生格式、跨平台同构；AI 与自动化被约束为“通过应用执行、可审计、可撤销”。
• 版本线从 v0.1（地图查看器）走到 v3.4（OBIA、星载激光、四渲染引擎、完整 ArcGIS 服务编辑），三条主线是数据入口、分析引擎、产出与协作。
• 核心能力可归纳为：1,000+ WASM 工具、四渲染引擎、三种 SQL 引擎、AI/MCP、插件市场、开放工程格式与多种产出渠道。
• 与 QGIS、ArcGIS、CARTO、Felt、kepler.gl、Google Earth 相比，GeoLibre 不追求全面替代，而是用“浏览器内 + 本地数据 + 开放工程”占住一个它们都不完全覆盖的位置。
• 它不适合超大本地数据集、最广格式覆盖、最深专业工具箱与企业地理数据库管理；这些场景应与 QGIS/ArcGIS 组合使用。
• 使用前请确认第三方底图、影像与数据的许可条款；学术引用使用 Zenodo DOI。

1.11 实践练习

1. 定位判断：列出你手头三个 GIS 任务，分别判断应使用 GeoLibre、QGIS 还是 ArcGIS Pro，并写出判断依据（数据规模、格式、是否需要企业地理数据库、是否需要离线分享）。
2. 版本考古：打开仓库 docs/roadmap.md，找出“Cesium 成为主渲染引擎”与“Mapbox/ArcGIS 加入渲染引擎”分别属于哪个版本，并说明这两步对“一个工程四种引擎”的意义。
3. 能力核对：任选一个 Whitebox 工具类别（如 Hydrology），在文档或应用中找到至少三个具体工具名，记录它们的输入、输出与所在菜单路径。
4. 对比写作：以“给一个没有 GIS 背景的同事解释为什么不用 Google Earth 做这份工作”为题，写一段 200 字说明，至少引用本章两个对比维度。
5. 许可检查：为一个准备商用的地图应用列出需要核对的第三方许可清单（GeoLibre 本体、底图提供商、影像服务、数据源），并说明 MIT 覆盖到哪里、不覆盖到哪里。
6. 架构复述：不看本章，用自己的话画出“数据入口 → store → MapCanvas → MapController.syncLayers”的单向数据流，并解释为什么 UI 不能直接改 MapLibre 对象。