浏览器里的开源云原生 GIS：GeoLibre 免安装工作流指南

浏览器里的开源云原生 GIS：GeoLibre 免安装工作流指南

【免费下载链接】GeoLibreA lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs in the web browser, on the desktop, on mobile, and inside Jupyter notebooks.项目地址: https://gitcode.com/GitHub_Trending/ge/GeoLibre

GeoLibre 是一个免费的开源 GIS 平台，主打云原生地理空间工作流：它直接运行在浏览器、桌面应用和 Jupyter Notebook 三种环境里，不装任何软件就能打开它。跟着这篇指南走完，你能从空工作区做出一张带样式和属性表的地图，流式加载远程的 GeoParquet 与 COG，完成缓冲、叠加、DEM 地形分析和空间 SQL 查询，最后把成果发布成公开链接并嵌入任意网页。

三种运行环境，先搞清楚你要什么

GeoLibre 的三个形态各有所长，选错环境会在中途卡住：

📌 只有两件事是桌面端专属：读写你电脑上的项目文件，以及 Python 侧车（rasterio 栅格处理与部分格式转换）。浏览器版的 Whitebox 工具箱（1000+ 工具，WebAssembly 运行）和 SQL 工作区都不受此限制。官方教程入口在 docs/tutorials/index.md。

五分钟做出一张带样式和属性表的地图

目标：从零到一张可检查、可分享的地图，全程浏览器完成。

1. 打开添加数据 → 矢量图层（Add Data → Vector Layer），在面板里粘贴教程常用的示例数据地址：

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

   点加载（Load），世界国家图层countries就出现在图层面板里。

2. 选中该图层，展开右侧样式面板：调填充颜色（Fill color）、轮廓颜色（Outline color）和填充不透明度（Fill opacity）。想做分级统计图，把样式类型（Style type）切到Graduated，选一个数值字段（如POP_EST或GDP_MD_EST），定好类别数（Classes）、配色方案（Scheme）与色带（Colormap），再点应用样式类型（Apply style type）。

3. 点状态栏的属性表（Attribute table）展开它，载入记录后可以按列排序、在搜索属性（Search attributes）里找要素，选中某一行地图上对应国家会高亮。点探索（Explore）能一次性看到每个字段的类型、完整度和取值分布。

4. 给图层开启要素识别（Identify features），然后点地图上的国家，属性就会弹在窗口里。

保存分两种：桌面应用走项目 → 保存（Project → Save）写出.geolibre.json；任何环境都能用项目 → 分享（Project → Share）上传拿公开链接。更多数据源类型见 添加数据。

不下载加载大数据：GeoParquet、FlatGeobuf 与 COG 的流式读法

目标：远程大数据集不用整包拷进内存，浏览器按需抓取。

• GeoParquet：打开添加数据 → GeoParquet 图层（或矢量图层），粘贴 URL 后勾选流式 GeoParquet（不拷贝）（Stream GeoParquet (no copy)）。它靠 HTTP range 请求"原地查询"文件，只取相关的 row group——对按空间排序（如 Hilbert 序，GeoLibre 自己的转换工具写出的就是这种序）的大文件效果最好。底层读取逻辑可以看 duckdb-vector-loader.ts。
• FlatGeobuf（.fgb）：打开添加数据 → FlatGeobuf 图层，URL 一填即可；格式自带空间索引，GeoLibre 尽量只取当前视野内的要素。
• COG（Cloud-Optimized GeoTIFF）：打开添加数据 → 栅格图层（Raster Layer）加载.tif，之后可在样式面板调亮度、对比度、饱和度与色相。本地 GeoTIFF 也可以直接拖到地图上。

要把本地数据变成云原生文件，走处理 → GeoLibre 工具箱 → 转换（Processing → GeoLibre Toolbox → Conversion）：矢量转 GeoParquet（Vector to GeoParquet）和CSV 转 GeoParquet在浏览器里用 DuckDB-WASM 完成；矢量转 FlatGeobuf（Vector to FlatGeobuf）、矢量转 PMTiles（Vector to PMTiles）、栅格转 COG（Raster to COG）则跑在桌面端的 Python 侧车上。

💡 进阶：加载完的 Parquet、COG 可以进 SQL 工作区直接查（下节详述），也可以配时间滑块插件做 COG 序列的时间动画，见 数据集成。

几何分析三步走：先选对引擎，再谈缓冲与叠加

先说最容易踩的坑：处理菜单里藏了两个工具箱。分隔线上方的处理 → 矢量（Vector）属于 Whitebox 目录（1000+ 工具的 WASM 目录）；分隔线下方的处理 → GeoLibre 工具箱 → 矢量（Processing → GeoLibre Toolbox → Vector）才是带引擎选择器的内置矢量对话框。详细对照见 两个工具箱。

以缓冲（Buffer）为例：设好输入图层、距离与单位（公里/米/英里），关键一步是选引擎（Engine）：

⚠️ 客户端引擎在地理坐标（经纬度）下算缓冲，大范围区域要精确的米制距离时，务必换两个 GeoPandas 引擎之一——它们会先重投影再缓冲。

叠加与连接工具都在同一对话框里：裁剪（Clip，保留输入落在叠加层内的部分并保留其属性）、相交（Intersection，只留重叠区）、差异（Difference）、合并（Union，两种引擎下都不保留属性）、空间连接（Spatial join，按相交/包含/位于内部关系把连接层属性挂到输入要素上，任何几何类型都行）和属性连接（Attribute join，按关键字段匹配、一对一、首行命中生效，可选内连接/左连接）。

跑完之后用属性表抽查结果，并调样式让它和输入图层区分开。每次运行都会记进处理 → 历史（Processing → History），一键重跑，还能复制等价的 Python 代码。结果想落盘为云原生文件，回到转换工具。

从 DEM 派生山体阴影、坡度与等高线

目标：一份高程模型（DEM）进，三类地形产品出。工具都在处理 → GeoLibre 工具箱 → 栅格（Raster）下，每个工具顶部的引擎选择器会告诉你当前环境能跑哪些。

先加一个高程栅格图层（GeoTIFF 或 COG 的 DEM 均可）。注意栅格工具是"文件进、文件出"，本地或可访问的文件路径效果最好。

1. 山体阴影（Hillshade）：选 DEM 为输入，按需设方位角、高度角和 z 因子，运行后浮雕栅格落到地图上。把它放到其他图层下方，再把上方图层的混合模式（Blend mode）设为正片叠底（Multiply）——地形起伏会从颜色里透出来，比单纯降不透明度干净得多。
2. 坡度（Slope）算陡峭程度，坡向（Aspect）算最陡坡面的罗盘方向；任选其一跑完，用色带（colormap）上色，再从控件菜单（Controls menu）打开色条（Colorbar）显示数值标尺。
3. 等高线（Contour）：设好间距（interval，线间高差）运行，产出的是矢量图层，可以像普通矢量一样标注和样式化。
4. 要限制研究区，用按范围裁剪（Clip by extent，边界框，浏览器可跑）或按掩膜图层裁剪（Clip by mask layer，矢量掩膜）。

⚠️ 引擎分界：山体阴影、坡度、坡向都有客户端（浏览器）引擎，零安装可跑；但等高线和按掩膜图层裁剪只走 rasterio Python 侧车，必须用桌面应用。大栅格或地理坐标系统下的地形分析，官方建议也优先侧车引擎。

空间 SQL 查询并直接上图

目标：在浏览器里用 DuckDB Spatial 查数据，把结果当图层用。入口是处理 → SQL 工作区（Processing → SQL Workspace），底层是 DuckDB-WASM，浏览器和桌面都能跑。

每个已加载的矢量图层就是一张表。假设你加了上文的国家图层，直接写：

SELECT NAME, CONTINENT, GDP_MD_EST FROM countries ORDER BY GDP_MD_EST DESC LIMIT 10;

点运行（Run），GDP 预估最高的十个国家立刻出现在结果表里。换一份数据集时列名会变，先跑DESCRIBE SELECT * FROM '<文件URL>'摸清结构。

更省事的是裸 URL：工作区会识别FROM子句里没加载过的 URL，自动包上正确的读取器，再走 HTTP range 流式读取——不必先下载。空间扩展已加载，所有ST_*函数可用；注意 EPSG:4326 下ST_Area(geom)的单位是平方度，要平方公里请用ST_Area_Spheroid(geom) / 1e6。

查询返回几何列时，点添加为图层（Add as layer）即可把结果变成新图层（可命名，可一次加多个），随后照样支持识别、选择和属性表。导出 CSV与导出 GeoParquet两个按钮就摆在添加为图层旁边；没有头绪时用示例查询（Sample queries）菜单起步，用历史重跑旧查询。完整参考见 SQL 工作区。

发布与嵌入：把地图变成公开链接和网页组件

目标是两件事：拿一个公开链接，再把地图塞进你自己的网页。

第一步，配一次分享令牌。分享走share.geolibre.app，需要个人 API 令牌：打开设置 → 环境变量（Settings → Environment Variables），把令牌粘进Share.GeoLibre API token字段（令牌在 share.geolibre.app/settings 的"设置 → API 令牌"下创建）。只需做一次。

第二步，上传项目。调好图层、样式和视图后打开项目 → 分享...（Project → Share...），确认标题并上传，得到一个形如https://share.geolibre.app/you/my-map.geolibre.json的公开地址。注意：分享文件只存项目本身（图层、样式、插件状态、视图），绝不上传你的数据文件——读取本机文件的图层会被对话框列为缺失，这些本地数据需要自己另行托管。

第三步，打开与嵌入。把项目地址作为url参数传给在线版即可打开；嵌入网页则用<iframe>加参数：

<iframe src="https://web.geolibre.app/?url=https://share.geolibre.app/you/my-map.geolibre.json&amp;maponly" title="GeoLibre map" width="100%" height="600" style="border: 0;" loading="lazy" allow="fullscreen; geolocation" ></iframe>

常用参数可自由组合：

• maponly：去掉全部界面外壳，只留地图——地图只作为页面插图时用；
• layout=viewer：只读模式，图层开关、底图切换、搜索/识别都在，但一切修改项目的入口被隐藏——读者可以逛但不能改；
• layout=compact：保留一条纯图标的细工具栏；
• toolbar=none：隐藏顶部工具栏，保留面板和状态栏；
• panels=none：隐藏侧边与底部面板，保留工具栏；
• theme=dark：加载时强制深色主题。

完整参数表见 URL 参数。

第四步（可选），运行时双向对话。URL 参数只在加载时生效一次。想让你的页面持续驱动地图——用户点了一条记录就飞过去、同时监听地图内的选择变化——安装类型化客户端：

import { connect } from "@geolibre/embed"; const map = await connect(document.querySelector("iframe"), { origin: "https://web.geolibre.app", }); map.on("selectionChanged", ({ featureIds }) => showRecordFor(featureIds[0])); await map.setView({ bbox: field.bbox }); await map.highlightFeature({ layerId: "fields", filter: { parcel_id: field.id }, fit: true });

⚠️ 关键限制：该 API默认关闭，只有把页面源（origin）加入白名单的部署才生效——公开的 web.geolibre.app 没有给任何源开白名单，所以运行时接口只适用于你自己托管的构建版（Docker 镜像里设GEOLIBRE_EMBED_ORIGINS环境变量即可开启）。客户端实现见 packages/embed，协议细节与免依赖的原始postMessage写法见 嵌入文档。

常见坑速查与继续深入

• 在处理 → 矢量（Whitebox 目录的矢量类）和处理 → GeoLibre 工具箱 → 矢量之间迷路：前者是 1000+ WASM 工具的目录，后者才是带引擎选择器的内置对话框，文档里凡是"缓冲/叠加/转换"指的都是后者。
• 大范围缓冲出来"距离不对"：多半是用了客户端（Turf.js）引擎，换 Pyodide 或侧车引擎即可。
• 分享后打开是空图：本地文件图层没随项目走，先把数据发布到可公开访问的地址。
• 嵌入里点了没反应：运行时 API 需要自建部署并配置GEOLIBRE_EMBED_ORIGINS。

文字之外，视频教程 收录了 9 段实操演示（含 1 小时的项目总览和网络研讨会），覆盖流式加载 180 GB 数据集、Whitebox 工具箱、浏览器内规整建筑足迹、影像地理配准等主题，可作为本文的视觉补充。

【免费下载链接】GeoLibreA lightweight, cloud-native GIS platform for visualizing, exploring, and analyzing geospatial data. It runs in the web browser, on the desktop, on mobile, and inside Jupyter notebooks.项目地址: https://gitcode.com/GitHub_Trending/ge/GeoLibre