不用装软件,也能跑 700 个 GIS 工具——GeoLibre 把地理处理搬进了浏览器

乍看界面，你很容易把 GeoLibre 当成一个普通的开源地图查看器：左边图层、中间地图、右边样式，顶部几个菜单。

但真正深入研究后，你才会惊呼：这简直是个宝藏！ 它的功能全面得离谱，我玩了一整晚，竟然还没完全搞懂所有用法。

但读完代码会发现，它真正有意思的地方不在菜单数量，而在架构取舍：GeoLibre 用一个 React/Tauri 应用壳，把 MapLibre 地图渲染、DuckDB-WASM Spatial 数据读取与 SQL、Turf/sidecar/Pyodide 处理工具、插件系统、Jupyter 联动和项目文件状态，压进了同一个工作台。

这篇文章不做泛泛功能介绍，而是顺着代码结构看：GeoLibre 为什么能在浏览器、桌面、移动端和 Notebook 里复用同一套体验；一个图层从文件进入，到变成 MapLibre 图层，中间经历了什么；SQL 工作区和处理工具为什么不是简单的 UI 拼装。

一、先看项目分层：它不是一个“大 React 页面”

GeoLibre 的代码主干大致可以分成四层：

• apps/geolibre-desktop
  ：产品壳。这里放 React 页面、菜单、对话框、Tauri 文件能力、运行时 hooks。
• packages/core
  ：核心状态和项目模型。图层、地图视图、项目文件、图层组、仪表盘、故事地图、撤销重做都在这里抽象。
• packages/map
  ：MapLibre 适配层。负责把 GeoLibre 的图层模型同步成 MapLibre source/layer，并维护地图控制器。
• packages/processing
  ：处理算法层。矢量、栅格、网络分析、统计等工具以算法定义的形式注册，UI 按定义生成参数表单。
• packages/plugins
  ：插件与外部图层能力。3D Tiles、COG、LiDAR、PMTiles、deck.gl 等复杂图层并不都塞进核心 map 包，而是通过插件/外部 native layer 的方式接入。

这个分层决定了 GeoLibre 的扩展性：界面是 React 写的，但它不是“React 组件直接控制一切”。React 更像操作台，真正的地图同步、数据读取、处理算法都有自己的边界。

二、启动入口：先把运行环境铺好，再挂应用壳

入口在 apps/geolibre-desktop/src/main.tsx。

它做了几件很关键的事：

• 注册各种 MapLibre 插件样式，包括 3D Tiles、raster、vector、Earth Engine、Overture、Time Slider 等；
• 初始化 RTL 文本插件，保证阿拉伯语、希伯来语、波斯语等底图标签不会反向显示；
• 安装诊断捕获和 stale chunk reload，处理线上更新后懒加载 chunk 失效的问题；
• 注册 PWA service worker，但刻意不在新 SW 激活时强制刷新页面，避免用户正在看的地图状态被打断；
• 并行加载 App 和错误边界，再用 i18next provider 包起来。

App.tsx 反而很薄。它主要挂全局 hooks：主题、布局、项目 URL 加载、最近项目持久化、运行时环境变量、撤销重做快捷键、离开页面保护、启动更新检查。最后把所有东西交给 DesktopShell。

这说明 GeoLibre 的启动设计很清楚：入口负责“运行环境”，App 负责“全局副作用”，真正工作台在 DesktopShell。

三、核心状态：useAppStore 是整个项目的中枢

GeoLibre 的状态在 packages/core/src/store.ts，用 Zustand 加 zundo 做撤销重做。

AppState 里不只是几个 UI 开关，而是完整项目模型：

• mapView
  ：中心点、缩放、方位角、俯仰、bbox；
• basemapStyleUrl
  、basemapVisible、basemapOpacity；
• layers
  ：所有业务图层；
• layerGroups
  ：图层组、组可见性、组透明度；
• legend
  、storymap、models、widgets；
• mapLayout
   和 secondaryMapViews：多地图网格；
• selectedLayerId
  、selectedFeatureId、identifyLayerId；
• ui
  ：处理、SQL、Python、Notebook、属性表、仪表盘等面板状态；
• collaboration
  ：多人协作里的参与者、presence、follow host 等临时状态。

图层操作也集中在这里。例如 addGeoJsonLayer 会创建一个 GeoLibreLayer：

constlayer: GeoLibreLayer = {  id,  name,type: "geojson",source: { type: "geojson" },visible: true,opacity: 1,style: {    ...DEFAULT_LAYER_STYLE,simpleStyleEnabled: hasSimpleStyleProperties(geojson),  },metadata: {},  geojson,  sourcePath,};

然后调用 addLayer 插入到 layers 数组里，选中新图层，并标记项目为 dirty。

这一步很关键：GeoLibre 的图层不是 MapLibre 原生 layer，也不是 React 组件，而是一个应用级 layer model。后面所有渲染、样式、导出、项目保存、SQL 注册，都是围绕这个模型展开。

四、地图渲染：状态不是“渲染”到地图，而是同步到 MapLibre

Map 相关代码主要在 packages/map。

MapController 是对 MapLibre 实例的封装。它负责：

• 初始化 maplibregl.Map；
• 应用底图样式、投影、地形、控件；
• 处理 canvas 导出所需的 preserveDrawingBuffer；
• 管理图层控制器；
• 把 GeoLibre 图层同步到 MapLibre；
• 给故事地图播放、图层透明度动画、相机跳转提供受控 API。

核心方法是 syncLayers(layers)：

syncLayers(layers: GeoLibreLayer[]): void {if (!this.isStyleReady() || !this.map) return;const nextIds = layers.map((l) => l.id);for (const id ofthis.layerIds) {if (!nextIds.includes(id)) {removeLayerFromMap(map, id, oldLayer);    }  }for (const [index, layer] of layers.entries()) {syncLayer(map, layer, this.getBeforeStyleLayerId(layers, index));  }this.layerIds = nextIds;this.syncedLayers = layers;}

它做的是增量同步：删除已经不存在的图层，再逐个把当前 layer model 同步到 MapLibre。

真正分发在 packages/map/src/layer-sync.ts 的 syncLayer：

• geojson
  ：小数据直接 GeoJSON source，大数据走 client-side vector tiling；
• raster / wms / wmts / xyz
  ：转成 raster tile layer；
• vector-tiles
  ：转 MapLibre vector source/layer；
• mbtiles
  、video、image：走各自同步逻辑；
• 外部 native layer：交给插件注册的 MapLibre 原生 layer 或 deck.gl layer。

ensureLayer 则是一个非常典型的工程化细节：如果 layer 已存在，不重建，只更新 paint、layout、filter、zoom range，再移动顺序；如果不存在，才 map.addLayer。这样可以避免频繁重建图层导致闪烁、状态丢失或性能浪费。

这也是 GeoLibre 能承载复杂图层管理的原因：React 状态变化不直接重建地图，地图层有自己的同步协议。

五、数据加载：DuckDB-WASM Spatial 是浏览器端 GIS 能力的底座

GeoLibre 的数据加载并不是“读文件，然后 JSON.parse”这么简单。

在 apps/geolibre-desktop/src/lib/duckdb-vector-loader.ts 里，项目创建了一个全局复用的 DuckDB-WASM 实例：

• 手动选择 mvp / eh bundle；
• 创建 worker；
• db.open({})
   初始化 DuckDB 运行时和文件系统；
• 懒加载 spatial extension；
• 对 h3 extension 也做 promise 级别的并发去重。

ensureSpatialExtension 里有一个非常值得注意的兼容处理：某些 duckdb-wasm 版本在先 LOAD spatial 再读 Parquet 时会触发远程读取问题，所以代码提供 beforeLoad warm-up，在加载 spatial 前先做一次轻量读取，给连接“预热”。

这不是炫技，是浏览器端 GIS 工程里很真实的问题：WASM、worker、远程 range request、DuckDB extension、GDAL reader 几个系统叠在一起，边界条件会很多。

GeoLibre 对不同格式也分流：

• Parquet / GeoParquet 用 read_parquet；
• 其他矢量格式多走 ST_Read；
• GeoPackage 有专门路径。代码注释里明确提到，单线程 DuckDB-WASM 对 GeoPackage 的 ST_Read 在一些场景会崩，所以项目用 sql.js + WKB decode 做兜底读取；
• Shapefile 需要同时注册 .dbf/.shx/.prj/.cpg 等 sibling files；
• 大文件加载前有 feature count guard，避免用户无意识把浏览器拖死。

这部分让 GeoLibre 和普通 Web 地图工具拉开差距：它把“空间数据读入”当成核心能力，而不是只支持 GeoJSON。

六、SQL 工作区：不是把 SQL 丢给 DuckDB 就完事

SQL 工作区在 apps/geolibre-desktop/src/lib/sql-workspace.ts。

它做了几层包装：

1. 清理 SQL 末尾分号和注释；
2. 检测多语句，拒绝一次执行多条 SQL，避免 DuckDB-WASM 只返回最后一个结果而用户误判；
3. 把 s3://、gs://、az:// 这类云对象地址改写成公开 HTTPS；
4. 把 FROM https://.../data.parquet 这种裸 URL 改写成 read_parquet('...') 或 ST_Read('...')；
5. 对远程文件调用 db.registerFileURL(handle, url, DuckDBDataProtocol.HTTP, true)，强制走 HTTP range 读取；
6. 把当前地图里的 GeoJSON 图层注册成 DuckDB 临时表；
7. 执行查询；
8. 如果结果有 geometry column，就额外生成 ST_AsText 给表格显示，同时用 ST_AsGeoJSON 生成 FeatureCollection，方便“把查询结果加回地图”。

这里的设计很贴心：用户可以写接近自然的 SQL：

SELECT*FROM https://example.com/data.parquetWHERE population >1000000

内部再把它改写成 DuckDB 能稳定执行的形式。

这说明 GeoLibre 的 SQL 工作区不是一个简单 textarea，而是一个“面向 GIS 用户的 DuckDB 包装层”。它把空间数据、远程数据、当前图层、结果图层化这几件事串起来了。

七、处理工具：算法定义驱动 UI，而不是每个工具写一套页面

packages/processing/src/vector-tools.ts 里，每个矢量工具都是一个 ProcessingAlgorithm。

以 Buffer 为例，它包含：

• id
• name
• description
• group
• parameters
• run(ctx)

UI 侧的 VectorToolsDialog.tsx 并不为每个工具手写表单，而是读取 VECTOR_TOOLS，按 group 分组，再根据参数定义渲染 ParameterField。

执行引擎也不是单一路径：

• client
  ：浏览器端 Turf.js / DuckDB 能力；
• sidecar
  ：桌面或 Docker 里可用的 Python/FastAPI 重处理服务；
• pyodide
  ：浏览器内 Python/GeoPandas 路线。

这解释了为什么 GeoLibre 的处理菜单能不断扩展，而不至于变成一堆难维护的对话框。新增工具的主要方式是新增算法定义，而不是复制一套 UI。

八、Tauri 边界：同一套 UI，浏览器和桌面走不同文件能力

apps/geolibre-desktop/src/lib/tauri-io.ts 是多端差异的关键。

它同时处理：

• Tauri 桌面端的 @tauri-apps/plugin-dialog、plugin-fs；
• 浏览器端的 File System Access API；
• 普通浏览器 fallback；
• 拖拽文件；
• 项目文件读写；
• Shapefile sibling files；
• KMZ/KML、GPX、CSV 坐标字段识别；
• 可恢复本地路径的白名单校验。

这就是 GeoLibre 多端能力的实际落点：UI 看起来一样，但文件读写和本地路径恢复在桌面端、浏览器端并不相同。项目没有把这些差异散落在各个按钮里，而是集中在 tauri-io.ts 这样的边界模块中。

九、多地图网格：一个小功能背后的状态设计

GeoLibre 支持多地图网格，这个功能在 MapGrid.tsx 和 store 里体现得很清楚。

store 中有：

• mapLayout.rows / cols
• secondaryMapViews
• 每个 secondary pane 自己的 view
• 每个 pane 自己的 layerVisibility override；
• syncView控制相机同步。

MapGrid 本身只负责布局：主地图放在第一个格子，其余格子渲染 SecondaryMapCanvas。每个副地图可以单独切图层可见性，但图层数据仍然共享主 store。

这是一种很实用的设计：多地图不是复制 N 份项目状态，而是在共享图层之上叠加“视图差异”和“可见性差异”。比较不同底图、不同时间、不同图层组合时，这个模型会比复制项目轻很多。

十、插件系统：复杂图层不硬塞进核心

GeoLibre 的插件能力分两类：

一类是内置插件，比如 raster、vector、Earth Engine、Overture、USGS LiDAR、Time Slider、3D Tiles 等。另一类是外部插件 manifest/zip。

hooks/usePlugins.ts 里有一个重要设计：外部插件可以拿到 GeoLibre 的 app API，向宿主注册图层、控件、deck.gl layer 等。对 deck.gl，宿主会把自己的 deck.gl 模块传给插件，避免插件打包另一份 deck.gl 后触发版本冲突。

对 MapLibre 来说，某些插件图层是“external native layer”：它们已经在 MapLibre 里创建了原生 layer，GeoLibre 的 store 只保存一个映射和元数据。layer-sync.ts 识别到这类 layer 后，不再按普通 GeoJSON/raster 方式重建，而是同步可见性、顺序、时间过滤等。

这个设计很重要。GIS 的图层类型太多，如果每一种都塞进核心渲染器，核心会迅速膨胀。GeoLibre 选择把核心 layer model 稳住，把复杂图层通过插件和 native layer 注册接进来。

十一、从用户操作到地图结果：一条完整链路

以“拖入一个 GeoPackage/GeoParquet，然后做 SQL 查询并加回地图”为例，代码链路大概是：

1. DesktopShell
    捕获拖拽事件；
2. tauri-io.ts
    根据运行环境读取文件和 sibling files；
3. duckdb-vector-loader.ts
    注册文件到 DuckDB-WASM VFS；
4. 根据格式走 read_parquet、ST_Read 或 GeoPackage 特殊读取；
5. 几何字段被转成 GeoJSON；
6. useAppStore.addGeoJsonLayer
    写入应用级 layer model；
7. MapCanvas
    订阅 store 变化，调用 MapController.waitAndSyncLayers；
8. layer-sync.ts
    把 layer model 转成 MapLibre source/layer；
9. 用户打开 SQL 工作区，当前图层被注册成 DuckDB 表；
10. 查询结果如果包含 geometry，就生成新的 FeatureCollection；
11. 再次调用 addGeoJsonLayer，结果图层回到地图。

这条链路就是 GeoLibre 的核心价值：空间数据不是只“显示”一次，而是在应用内形成一个可继续分析、样式化、导出、保存的对象。

十二、它的工程取舍

读代码后，我觉得 GeoLibre 有几个明显取舍。

第一，它把浏览器能力用得很满。DuckDB-WASM、MapLibre、Turf、Pyodide、PWA cache 都在前端侧承担真实工作。这让 Web 版不仅是 thin client。

第二，它没有迷信纯前端。重处理、桌面文件路径、JupyterLab、部分 raster/conversion 能力仍然通过 Tauri 或 sidecar 补上。

第三，它把“项目状态”放在 packages/core，而不是让 MapLibre 成为事实状态源。MapLibre 负责渲染，GeoLibre store 负责项目真相。这对保存、撤销、协作、故事地图、多地图网格都更稳。

第四，复杂图层通过插件接入。核心 map 包提供同步机制，但不试图自己吞掉所有 GIS 世界的图层类型。

结语：GeoLibre 真正值得看的地方

GeoLibre 的吸引力，不只是“支持很多格式”。

它更值得看的地方，是一个现代开源 GIS 工作台如何组织代码：用核心状态统一项目模型，用 MapController 管 MapLibre，同步层负责图层增量更新，用 DuckDB-WASM Spatial 把数据读取和 SQL 放进浏览器，再通过 Tauri/sidecar/Pyodide 补齐不同运行环境的能力。

这套架构没有把所有问题都压到一个万能组件里，而是把 GIS 应用里最难缠的几件事拆开：状态、渲染、数据、处理、平台边界、插件扩展。

如果你关注 Web GIS、桌面 GIS、DuckDB Spatial、Tauri 或 Jupyter 地图组件，GeoLibre 不只是一个可以试用的工具，也是一个很值得读源码的项目。

如果其中有说错的地方还请指正。链接在下方，赶快用起来吧。

项目地址：https://github.com/opengeos/GeoLibre

在线演示：https://viewer.geolibre.app/