GeoLibre 项目管理完全指南：从新建、导入、自动保存到分享发布的 .geolibre 项目工作流

GeoLibre 项目管理完全指南从新建、导入、自动保存到分享发布的 .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 的Project菜单为主线完整讲解.geolibre.json项目从创建、打开、保存、自动快照与崩溃恢复到 QGIS / ArcGIS Pro 项目导入、模板复用、在线分享、HTML 导出、协作与离线底图的完整生命周期。读完你既能熟练操作 Project 菜单的每一项功能也能理解.geolibre.json的底层文件格式、快照存储边界与凭据脱敏机制知道每个操作背后由哪段源码支撑。项目是什么一个文件承载整个工作区在 GeoLibre 中一个项目project把整个工作区完整封装进单个.geolibre.json文件包括地图视图中心点、缩放级别、旋转角与俯仰角底图当前使用的 MapLibre 样式 URL 及其可见性、不透明度每个图层数据源source与样式style地图偏好环境变量、地理编码设置等插件状态启用的插件、控件位置与插件设置其他工作区状态打印布局、图例定制、仪表盘组件、故事地图等。所有相关操作都集中在Project菜单对应工具栏的文件夹图标其菜单结构见 apps/geolibre-desktop/src/components/layout/toolbar/ProjectMenu.tsx。注意部分菜单项可能被隐藏。Project 菜单会按当前激活的 UI 配置文件 过滤且少量条目仅桌面版可用。如果某个条目缺失请先检查当前 UI profile以及你运行的是否是浏览器构建版本。新建项目Project → New...Project → New...会开启一个全新项目。GeoLibre 会先询问是否保存当前项目然后将图层、地图视图、控件与插件状态全部重置为默认值。New project对话框包含两个核心设置项目名称project name起始底图可选范围包括OpenFreeMap 官方样式Regional分组区域性底图集合月球、火星等其他天体的专属底图分区空白背景blank background自定义 MapLibre 样式 URL 或 PMTiles URL。从源码看空项目由 packages/core/src/project.ts 的createEmptyProject()构建默认名称为Untitled Project默认地图视图为center: [-100, 40], zoom: 2, bearing: 0, pitch: 0默认底图取DEFAULT_BASEMAP同时初始化空图层列表、空样式表与默认偏好DEFAULT_PROJECT_PREFERENCES。该函数也支持通过CreateProjectOptions注入basemapStyleUrl、mapView与天体 IDellipsoidId这正是新建对话框里月球/火星与自定义底图选项的底层支撑。打开项目Open From 与 Open RecentOpen From 的三个来源Project → Open From提供三个入口File...从磁盘打开.geolibre.json文件桌面版专属URL...从 HTTP/HTTPS URL 加载公开的.geolibre.json。浏览器版同样可用且打开过的项目会加入最近列表Gallery...浏览共享项目画廊Project Gallery单击即可打开任意条目。当部署关闭了分享主机或主机配置无效时该入口会被隐藏或禁用并显示原因见 ProjectMenu 源码中的shareHostStatus逻辑。Open Recent 与最近列表Project → Open Recent列出此前打开过的项目每条记录显示名称、路径与上次打开时间。你可以单击条目重新打开用行内小删除按钮移除单条记录该按钮会stopPropagation避免误触发行条目本身的重开逻辑选择Clear Recent Projects清空整个列表。桌面版最近列表跨会话持久化浏览器版则只跟踪基于 URL 的项目。菜单源码对空列表显示noRecentProjects占位项并禁用子菜单。启动时直接加载项目两种方式可以在启动时打开指定项目URL 查询参数把项目 URL 传给url参数例如?urlhttps://share.geolibre.app/you/project.geolibre.json浏览器与桌面版均适用详见 Embedding Sharing 的 URL 参数表桌面版启动偏好在 Settings → Startup 中配置让 GeoLibre 每次启动时重新打开最近一次本地项目、或指定某个本地项目远程分享链接绝不会在启动时自动重放。地址栏中的项目 URL 优先级始终高于启动偏好。保存、另存为与复制项目Save写回项目现有的文件路径Save As...提示输入新名称与新位置。两者都会在保存瞬间捕获当前地图视图、底图、图层、样式、偏好与插件状态。从 URL 打开的项目没有可写的本地路径因此 Save 与 Save As 都会回退到保存对话框。保存功能要求桌面版——浏览器构建没有本地文件写入能力。Project → Duplicate project复制项目会把当前打开的项目复制为一份新的、未保存的项目适合在不触碰原文件的前提下开一个实验分支。这四个保存类条目共享同一个project:save部署能力门控被部署禁用时整组变灰并显示统一说明。项目历史与崩溃恢复自动快照机制自动保存工作 3 秒后落盘到 IndexedDBGeoLibre 会在你工作时持续自动保存当一次变更新增图层、编辑样式、移动相机等稳定下来 3 秒后它向浏览器本地 IndexedDB 写入一个快照。关键边界是自动保存永不触碰你的.geolibre.json文件——只有显式Save才会写文件快照按项目存储以文件路径为键尚未保存过的项目则以名称为键快照只存在于产生它的设备上不上传、不共享、不属于.geolibre.json文件内容。History 对话框恢复任意时间点Project → History...列出当前项目的快照最新的在最上面每条快照以图层数量与缩放级别汇总。单击Restore会把该快照加载回工作区且恢复本身是一个可撤销步骤——你可以反悔退出这次恢复。这里没有手动删除入口快照达到上限后会自动老化淘汰。对应实现见 apps/geolibre-desktop/src/lib/project-history-store.ts常量MAX_SNAPSHOTS 20、MAX_TOTAL_BYTES 50 * 1024 * 1024、MAX_SNAPSHOT_BYTES 10 * 1024 * 1024与文档承诺的三重上限完全一致。快照的元数据ID、创建时间、大小、名称、图层数、相机状态单独存放在snapshot-metadatastore 中列表 UI 见 ProjectHistoryDialog.tsx。存储上限三重封顶历史存储是有界的因此不会无限膨胀上限数值每个项目最多快照数20 个单个快照最大体积10 MB历史总存储50 MB达到任一上限后最旧的快照被丢弃单个快照装不下的超大项目不会被自动保存。崩溃恢复Recover unsaved work?崩溃恢复是独立浏览器构建的特性。在浏览器构建、且非嵌入iframe会话中工作时 GeoLibre 将会话标记为打开中若标签页/浏览器未正常关闭就消失且存在比最近一次显式保存更新的自动保存则下次启动会弹出Recover unsaved work?让你选择恢复或丢弃桌面版与嵌入式部署保留历史列表但不显示此提示对应 UI 见 ProjectRecoveryDialog.tsx。导入 QGIS 项目Project → Import → Import QGIS Project…读取 QGIS 的.qgs或.qgz项目文件并在 GeoLibre 中重建为原生项目迁移内容包括图层及其数据源图层组包括嵌套组与组的可见性图层顺序样式保存的地图视图。导入器的容错策略导入器只处理基于文件的矢量图层与 app 能打开的栅格遇到无法迁移的内容时不会让整个导入失败而是项目照常给你 一份跳过清单。被跳过的图层会附带原因包括不受支持的数据提供者provider不受支持的文件格式源缺失missing source网络共享路径远程源。同一原因的跳过图层会被合并为一行并计数因此一个几百个图层共享同一根因的项目一眼就能读懂展开分组可查看具体图层名。在浏览器构建中引用本地磁盘路径的图层会被列入跳过清单浏览器无法重新打开这些路径改用 GeoLibre Desktop 打开同一项目即可加载它们。源码佐证导入逻辑位于 apps/geolibre-desktop/src/lib/qgis-project-import.ts。QgisProjectImportWarning的类型定义揭示了完整的跳过原因集合non-vector、provider、missing-source、format、remote-file、network-path、browser-local-file、browser-local-raster。同文件还包含两个值得注意的工程细节.qgz是压缩包通过fflate的unzipSync解压后解析单个.qgs最大解析体积被限制为 25 MBMAX_QGS_BYTESQGIS 常用 GDAL 的/vsicurl/前缀存 HTTP 图层导入器会先规范化该前缀为 HTTP URL再通过materializeQgisRemoteLayers()以并发 4、单请求 10 秒超时REMOTE_FETCH_CONCURRENCY/REMOTE_FETCH_TIMEOUT_MS拉取远程 GeoJSON 特征因为 GeoLibre 的 GeoJSON 渲染器消费的是内存中的 FeatureCollection。导入 ArcGIS Pro 项目Project → Import → Import ArcGIS Pro Project…读取 ArcGIS Pro 的.aprx项目或独立.mapx地图文件。GeoLibre直接读取文件内嵌的 CIM JSON因此无需安装 ArcGIS Pro 或 ArcPy。导入行为要点一个 ArcGIS Pro 项目可能包含多个地图GeoLibre 导入其第一个 2D 地图保留内容保存的范围、基于文件的要素图层与 GeoTIFF 栅格、嵌套分组、可见性、简单符号、基于字段的标注、ArcGIS 矢量瓦片门户项、缓存的地图服务不受支持的源文件地理数据库、场景、网络共享路径在项目其余部分导入完成后按原因分组列出。File Geodatabase 的特殊处理文件地理数据库File Geodatabase图层会被明确点名而不是笼统地报成不支持格式要素图层与栅格分开报告因为二者的解决方法不同桌面版中GDB 的要素类可用Add Data → File Geodatabase (GDB)直接添加存储在.gdb中的栅格必须先导出为 GeoTIFF 才能使用本地数据路径无法被浏览器构建重新打开。模板把项目变成团队起点Project → Save as template...将当前项目以名称 可选描述存入个人模板库。核心选项Strip data layers剥离数据图层会保留底图、图层组、样式、图例、组件与布局丢弃数据图层内容本身。这对团队统一风格起点非常实用——把公司标准的底图与符号体系固化成模板团队成员新建地图时直接套用无需从零配置。分离后保存的模板不含具体业务数据也不会把敏感数据带入新项目。分享Share... 与分享前就绪检查分享流程Project → Share...会把当前项目上传到share.geolibre.app并返回一个公开 URL你可以发给任何人或直接在在线查看器中打开。要点分享使用个人 API token在Settings → Environment Variables中配置为Share.GeoLibre API token上传的是 app 本地保存的同一个.geolibre.json因此打开链接的人看到的图层、样式与地图视图完全一致完整流程见 Sharing Embedding 教程。从源码结构看ProjectMenu 中 Share 条目的可用性受部署能力project:share与分享主机状态disabled/invalid双重门控关闭分享的部署不会展示该条目配置被拒绝的主机则显示分享主机不可用的说明文字。分享前就绪检查Share-readiness check项目文件大部分是引用所以一个项目可能上传得很干净、对方打开却啥也不画。Share 对话框打开时会检查项目指向的数据源并列出接收方无法加载的那些附带原因与处理建议检查发现说明与建议使用了分享时会被移除的凭据Token 与 API 密钥在上传时被剥离接收方拿到的 URL 没有密钥。把服务改为公开或让对方自备密钥浏览器无法访问该主机主机未发送跨域CORS头或未响应。此类图层在桌面版正常桌面版不受浏览器 CORS 限制但在浏览器查看器中保持空白服务返回 not found已过期的签名 URL或文件被移动指向私有或内网地址内网服务只有同网络的人能访问这可能正是你的分享对象本机文件或完全没有源的图层则不在这个列表而在对话框打开时的单独警告中列出见下文分享本地数据这个检查在浏览器中运行且不附带你的凭据所以它看到的就是接收方会看到的结果。检查永远不会阻止上传——把内网地图分享给内网同事是正常操作列表只是告知而不是拦截。分享本地数据项目文件保存的是数据的引用而非数据本身share.geolibre.app只存储这个文件绝不会上传你电脑上的文件。因此从本地 GeoTIFF、GeoPackage、Shapefile 等磁盘文件添加的图层你自己打开正常别人打开什么都不画——接收方在浏览器中打开项目浏览器读不到你的磁盘同理无 URL 的查询图层PostGIS、DuckDB SQL 图层、sidecar 结果也无法分享私有网络地址localhost、内网服务器的图层不同它可能对同网络的同事正常加载因此它留在上面较软的就绪列表里而不是这个警告。当 Share 对话框发现这类图层时会将其列在N layers will be missing from the shared map下Share 按钮变为Share anyway。你仍然可以分享只是地图不包含这些图层。要把它们真正分享出去把数据托管到线上栅格转成 Cloud Optimized GeoTIFF矢量转成 PMTiles 或 GeoParquet放到 GitHub、Hugging Face 等公开 HTTPS 服务器上再用 URL 添加Add Data → Raster Layer或Vector Layer填入 URL。瓦片服务、WMS、ArcGIS 服务等托管源只要主机允许跨域请求且无需登录就能原样工作让小矢量搭车用Add Data → Vector Layer添加的本地矢量图层会被自动内嵌进上传因此永远不会被列出来。但大矢量数据集更适合托管因为内嵌图层的每个要素在项目打开时都要被解析。该对话框在配置分享 token 之前就会发出警告——因为手动把已保存的.geolibre.json上传到share.geolibre.app会同样静默地丢掉这些图层早警告总比晚发现好。分享的底层保障凭据脱敏分享、导出为 HTML、嵌入快照与协作快照在离开本地工作区前都必须经过redactCredentials()。其实现位于 packages/core/src/credentials.ts顶层维护一份凭据字段注册表PROJECT_CREDENTIAL_FIELDS覆盖偏好environmentVariables、geocoding.apiKeys、图层配置requestHeaders、headers、authorization、apiKey、token、password、clientSecret、connectionString、sasToken等与插件状态URL 形状的值会剥离查询串中的凭据参数包括key、sig、Azure SAS 的sv/sr/st/se/sp/skoid与x-amz-*前缀同时保留{z}/{x}/{y}这类瓦片模板占位符user:pass形式的用户信息也会被移除遍历深度上限为 12MAX_REDACT_DEPTH超过即失败关闭fail closed——宁可删除整块配置也不冒险放行深层凭据外部插件的settings是自由形状、可能藏有凭据因此默认整体剔除仅maplibre-gl-swipe、maplibre-gl-components仅legend/colorbar子键与maplibre-gl-time-slider等第一方地图控件的结构化组合状态被白名单保留否则每次导出都会静默丢掉图例、色带与卷帘本地Save / Save As会询问是否剥离或刻意保留凭据。为了安全地记忆用户的保留决定脱敏结果会返回redactedFingerprints——对每个被移除的值计算 64 位双通道指纹pathhash同一路径上出现不同凭据例如轮换了 token时要求再次确认而不是沿用上一次的答案。导出为 HTMLProject → Export as HTML...把整个项目写进单个独立 HTML 文件离线即可运行、无需服务器。你既可以把它托管到任何地方也可以直接从磁盘双击打开。该条目与离线底图共享export:data部署能力。协作编辑Project → Collaborate...启动或加入实时会话多人可同时编辑同一个项目支持在场光标presence cursors聊天chat按参与者分配的权限。该功能默认关闭除非构建配置了 relay URL见 Collaboration。协作把项目放到本机之外的服务器上与分享是同一性质的操作因此菜单源码中它与 Share 共享project:share能力门控。离线底图Project → Offline Basemap...预先缓存当前地图视图的底图瓦片设备离线时地图仍能绘制。下载后若发现瓦片缺失参考 Troubleshooting。从源码注释看该导出会遍历底图的样式文档来收集所需瓦片因此依赖 Style Spec 能力styleSpec菜单源码中对不具备该能力的渲染引擎会禁用此条目。打印布局Project → Print Layout...打开布局排版器把当前地图导出为PNG 或 PDF。功能清单包括标题块可编辑标题与页脚用户可编辑的图例显式地图比例输入页面尺寸控制自定义打印范围属性表与图表块Atlas / 地图系列生成按要素逐页出图或沿一条线生成均匀序列Copy to Clipboard复制到剪贴板。排版器由 MapLibre Components 插件提供支撑。它的排版配置属于项目的一部分会随项目保存并在下次打开时复原详见下节项目格式。故事地图Project → Story Map...打开滚动驱动的故事构建器把项目变成一段可滚动的叙事每个章节捕获一个相机视角与文本并能在章节进入/离开时淡入淡出项目图层。详见 Story Maps。项目格式.geolibre.json 的底层结构扩展名.geolibre 与 .geolibre.json项目保存为.geolibre文件GeoLibre 仍能打开旧版.geolibre.json名称。统一扩展名是为了让桌面安装器能把项目与 GeoLibre 关联而不用接管系统上所有 JSON 文件。桌面安装器会把.geolibre注册为 GeoLibre Project 文档从文件管理器打开会启动 GeoLibre或唤起已打开的窗口并加载项目。桌面可执行文件同时接受两种名称geolibre-desktop /path/to/watershed.geolibre geolibre-desktop /path/to/legacy.geolibre.json操作系统只能看到.geolibre.json末尾的.json这些旧文件仍可从 GeoLibre 内部与命令行打开但必须重命名为.geolibre才能获得文件管理器的关联文件内容不变。顶层 Schema完整格式规范见 Reference → Project Format顶层字段如下字段类型说明versionstring格式版本0.1.0namestring项目显示名称mapViewobjectcenter、zoom、bearing、pitch可选bboxbasemapStyleUrlstringMapLibre 样式 JSON URL空字符串表示空白背景basemapVisiblebooleanBackground 图层是否可见basemapOpacitynumberBackground 图层不透明度0–1layersarray图层定义见下stylesobject图层 id →LayerStyle的映射pluginsobject可选外部插件 manifest URL、激活插件 id、插件地图控件位置与插件设置legendobject可选打印图例定制标题、分组、排序、逐项重命名/隐藏printLayoutobject可选打印布局设置标题、页面尺寸、方向、块、atlas默认值时省略storymapobject可选滚动故事地图章节与呈现设置无章节时省略widgetsarray可选 Dashboard 面板图表组件见下无组件时省略dashboardColumnsnumber可选 Dashboard 组件网格列数1–6默认 2默认时省略styleLibraryarray可选项目级 Style Manager 条目为空时省略primaryRendererstring可选主地图渲染引擎maplibre2D默认或cesium3D 地球默认时省略metadataobject自由格式项目元数据没有plugins段的项目打开时使用内置默认插件状态。图层对象的持久化细节图层对象见 project-format.md由id、name、type、source、visible、opacity、style含fillColor/strokeColor/circleRadius及一系列raster*参数、metadata、geojson、sourcePath等构成此外还有几类进阶持久化能力值得了解capabilities可选地声明允许的操作集合query/create/update/delete/export每个开关只门控它命名的那类操作。export: false会在分享/发布时剥离该图层内嵌的 GeoJSON包括geojson与metadata.embeddedGeoJSON但保留source/connection——靠 URL 实时取数的图层WFS、ArcGIS FeatureServer、远程 GeoJSON/瓦片 URL仍带可访问的 URL 并在打开时重新拉取数据。注意capabilities描述图层并被 UI 强制执行不是访问控制机制需要对抗不可信客户端时请用数据库授权自动刷新WFS GetFeature 与 GeoJSON URL 图层可用metadata.refreshintervalMs毫秒或顶层connectioninterval秒onFailure为keep-last/clear持久化刷新节奏文件监听桌面版本地文件图层可用metadata.watch开启文件系统监听磁盘文件变化时自动从sourcePath重载要素浏览器构建无效属性连接joins持久化跨图层左连接fields/prefix/enabled可选addedFields与stats为引擎簿记重放时保持幂等项目打开时会按已加载图层集重新解析快捷筛选quickFilters只持久化控件状态而非编译产物categorical/range/date/text四种 kind清空的选择不产生约束持久表达式过滤filterExpression保存的是普通 MapLibre 表达式表达式构建器的变量在应用瞬间被求值为字面值不随地图追踪想跟随缩放请用[zoom]运算符弹出窗口设计popup块决定点击/悬停时查看者看到什么kind可为auto/text/number/date/link/imagefieldVisibility始终优先——被作者隐藏的字段永远到不了弹窗。图层类型速览类型状态geojson导入文件与 GeoJSON URL 均支持xyz栅格瓦片模板wms切片式 WMS GetMap 图层raster栅格瓦片模板带source.ionAssetIdmetadata.sourceKind: cesium-ion时为 3D 地球用 Cesium Ion 影像vector-tilesMapLibre 矢量瓦片源mbtiles桌面版通过本地 MapLibre 协议支持arcgisArcGIS VectorTileServerFeatureServer 存为geojsonMapServer/ImageServer 存为rasterpmtiles/flatgeobuf/zarr/lidar/gaussian-splat通过 Components 插件支持cogCOG 与 GeoTIFF 栅格图层geoparquet经 DuckDB-WASM 导入为 GeoJSONduckdb-querySQL 查询结果图层3d-tiles经maplibre-gl-3d-tiles插件带 Ion 资产信息时为 3D 地球用 Cesium Ion tileset附带的持久化结构项目文件中还可能包含几类附属状态均为可选、按需写入Legend图例始终从可见图层的符号派生legend对象只存用户的覆盖编辑title、groupByLayer、order、按稳定键layerId或layerId::index的overrides因此图层增删后定制仍然存活Print layout只有设置偏离默认值才写入printLayout键未打开过排版器的项目不带此键未知或畸形值回退到该字段的默认值手改文件不会让排版器不可用Story map无章节时整段省略alignment为left/center/right/fullmapAnimation为flyTo/easeTo/jumpToDashboard widgetswidgets数组把图表绑定到图层属性type为histogram/scatter/bar/line/box/pie图表从 GeoJSON 矢量图层与 DuckDB 查询图层读取顶层的dashboardColumns控制组件网格列数。从 API 层面理解项目对开发者而言项目格式的读写入口集中在geolibre/core包实现于 packages/core/src/project.tsimport { createEmptyProject, parseProject, redactCredentials, serializeProject, } from geolibre/core;createEmptyProject()构造默认空项目名称、视图、底图、空图层表parseProject()读取并规范化外部 JSON非法或畸形值回退到该字段默认值保证手写文件也能安全打开serializeProject()输出.geolibre.jsonredactCredentials()是所有外发路径的统一关卡分享、HTML 导出、嵌入快照、协作快照在离开本地工作区前都必须先过脱敏本地 Save / Save As 则询问用户是剥离还是刻意保留凭据。这套一个文件 规范化解析 强制脱敏 快照自动恢复的组合就是 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考