maplibre-mapbox-migration

从 Mapbox 迁移到 MapLibre

本技能将指导你把应用从 Mapbox GL JS 迁移到 MapLibre GL JS。这两个库有共同的起源（MapLibre 于 2020 年 12 月从 Mapbox GL JS v1.13 分叉而来），因此 API 基本相同。主要变化包括：更换软件包、替换命名空间、移除 Mapbox 访问令牌，以及选择新的瓦片源（MapLibre 不使用 mapbox:// 样式）。

主要参考资料：MapLibre 官方 Mapbox 迁移指南。

适用场景

• 将现有的 Mapbox GL JS 应用迁移到 MapLibre
• 评估 MapLibre 是否适合作为 Mapbox 的开源替代方案
• 了解 API 兼容性以及可能导致的问题
• 迁离 Mapbox 后选择瓦片源和服务

为什么迁移到 MapLibre？

团队从 Mapbox 切换到 MapLibre 的常见原因：

• 开源许可证——MapLibre 使用 BSD-3-Clause 许可证；没有供应商锁定或专有条款
• 无需访问令牌——该库不需要 Mapbox 令牌；瓦片源可能需要各自的密钥，也可能不需要（例如 OpenFreeMap）
• 成本——避免 Mapbox 地图加载和 API 费用；改用免费或固定成本的瓦片与地理编码服务提供商
• 自行托管——使用自己的瓦片（PMTiles、tileserver-gl、Martin）或任意第三方数据源
• 社区——MapLibre 由 MapLibre 组织和社区维护；样式规范和 API 在开放环境中持续演进
• 社区支持的资金——MapLibre 由许多公司和个人捐款资助；没有单一的商业资助方，因此项目始终与社区保持一致
• 开放的矢量瓦片格式（MLT）——MapLibre 提供 MapLibre Tile (MLT)，这是 Mapbox Vector Tiles（MVT）的现代替代格式，压缩效果更好，并支持 3D 坐标和高程；GL JS 和 Native 均支持该格式，且可通过 Planetiler 生成

**迁移后将失去：**Mapbox Studio 集成、由 Mapbox 托管的瓦片和样式、Mapbox Search/Directions/Geocoding API，以及 Mapbox 官方支持。

了解此分叉项目

• 2020 年 12 月： Mapbox GL JS v2.0 改用了专有许可证。社区将 v1.13 分叉为 MapLibre GL JS。MapLibre 组织和 GL JS 仓库是官方项目所在地。
• API： MapLibre GL JS v1.x 在很大程度上与 Mapbox GL JS v1.x 向后兼容。大多数地图代码（方法、事件、图层、数据源）只需少量修改即可使用。
• 分叉后的版本发布： MapLibre 已推出自己的版本系列。v2.2 新增了 3D 地形，v3 转向 WebGL2；v4 在公开 API 中引入了 Promise（替代许多回调）；v5 新增了地球投影；v6（2026-07-22）仅以 ES modules 形式发布——UMD 包和默认导出已移除（请参阅下文的更新导入语句和 CSS）——并更改了多项默认设置（请参阅 v5 到 v6 迁移指南）。请参阅版本发布记录和 CHANGELOG。
• 样式规范： MapLibre 维护自己的 MapLibre Style Specification（从 Mapbox 规范分叉而来）。它与大多数样式兼容，但也新增了部分功能，并在一些方面有所差异；使用较新功能或 MapLibre 专属功能时，请查阅样式规范网站。
• 生态系统： 除 GL JS 外，MapLibre 组织还维护了 MapLibre Native（iOS、Android、桌面）、Martin（基于 PostGIS/PMTiles/MBTiles 的矢量切片服务）以及 MapLibre Tile (MLT) 格式。路线图和新闻：maplibre.org/roadmap、maplibre.org/news。

分步迁移

1. 安装软件包

npm install maplibre-gl

2. 更新导入语句和 CSS

// Before (Mapbox)
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

// After (MapLibre) — v6 ships ES modules only; the default export is gone
import * as maplibregl from 'maplibre-gl';
// or pull in just what you need: import {Map} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

CDN： 将 Mapbox 脚本/链接替换为 MapLibre。不要假设 Mapbox 的 <script src> 模式可以不经修改地直接沿用——MapLibre 分发包的格式在不同主版本间有所变化（v6 移除了 UMD 构建版本）。直接照搬以下代码片段之前，请先查看 当前版本发布说明：

<script src="https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.css" rel="stylesheet" />


<script type="module">
  import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs';
</script>
<link href="https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.css" rel="stylesheet" />

3. 替换命名空间

将所有 mapboxgl 替换为 maplibregl（并将软件包名称或路径中的 mapbox-gl 替换为 maplibre-gl）。例如：

// Before (Mapbox)
const map = new mapboxgl.Map({ ... });
new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new mapboxgl.NavigationControl());

// After (MapLibre)
const map = new maplibregl.Map({ ... });
new maplibregl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new maplibregl.NavigationControl());

CSS 类名： 如果你通过类名设置控件或界面的样式，请将 mapboxgl-ctrl 重命名为 maplibregl-ctrl（其他类似前缀也一样）。

4. 移除访问令牌

MapLibre 不使用 mapboxgl.accessToken。请移除任何设置此值的代码行。

切片和 API 密钥（例如托管切片服务或地理编码服务的密钥）应按服务配置，而不是在地图实例上配置。

5. 替换样式 URL（关键）

Mapbox 样式（mapbox://styles/...）无法在 MapLibre 中使用。你必须将地图指向使用非 Mapbox 瓦片源、精灵图和字形的样式。

最简单的做法是使用无需 API 密钥的样式 URL，例如 OpenFreeMap。OpenFreeMap 由社区资助，可免费使用且无需 API 密钥；如果你的应用在生产环境中依赖它，请考虑捐赠以支持该项目。测试并确认迁移成功后，你可以探索许多可用选项（更多建议请参阅 awesome-maplibre 或 MapLibre Tile Sources）。

示例：

// Before (Mapbox)
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-122.42, 37.78],
  zoom: 12
});

// After (MapLibre)
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/liberty', // or your chosen style
  center: [-122.42, 37.78],
  zoom: 12
});

接下来，你可以安装 MapLibre Style Specification & Utilities，用于验证和调试样式：

npm install --save-dev @maplibre/maplibre-gl-style-spec

自定义 Mapbox 样式： 如果你在 Mapbox Studio 中设计了样式，就无法在 MapLibre 中直接加载。请导出样式 JSON，并将 Mapbox 源 URL 替换为所选瓦片源的 URL。除非且直到你调整所有对 Mapbox 瓦片架构的引用，使其与新瓦片源的瓦片架构一致，否则样式将无法渲染。 除了更新源 URL，这还意味着要调整样式 JSON 中的 id、source 和 source-layer 属性，使其与新源和图层名称一致。

Mapbox 样式中的大多数属性都与 MapLibre 兼容。请查看 MapLibre Style Specification，了解支持的属性和类型。你可以使用 MapLibre 的样式编辑器 Maputnik 直观地测试和调试样式 JSON，并使用 MapLibre Style Spec CLI Tools 检查兼容性及其他验证问题。

npx gl-style-validate style.json

6. 更新插件（如有使用）

许多 Mapbox 插件无需修改即可与 MapLibre 配合使用，也有许多插件已分叉或被原生支持 MapLibre 的版本取代。如果存在原生支持 MapLibre 的替代方案，请优先选用，以确保长期兼容性。

请查看 awesome-maplibre 中的 User Interface Plugins、Geocoding & Search Plugins 和 Map Rendering Plugins 部分，查找兼容的插件和替代方案。

7. 替换 Mapbox API（搜索、路线规划等）

如果你的应用调用了 Mapbox Geocoding、Directions 或其他 REST API，请将其替换为开放服务或第三方服务：

• 地理编码 / 搜索：Nominatim、Photon、Pelias 或 MapTiler Geocoding
• 路线规划 / 路线导航：OSRM、OpenRouteService、Valhalla

**使用政策与可持续性：**这些开放服务或由社区资助的服务都有需要在生产环境中考虑的条款：

• Nominatim — 必须注明 OpenStreetMap 来源；公共实例仅供测试和低频使用。请参阅 Nominatim 使用政策。对于生产工作负载，请自行托管或使用托管服务提供商（例如 MapTiler Geocoding）。
• OSRM 演示服务（router.project-osrm.org）— 明确禁止用于生产环境；不提供 SLA 或正常运行时间保证。对于生产应用，请自行托管或使用托管服务（例如 OpenRouteService、MapTiler Directions）。
• 如果你的应用大规模依赖由社区维护的服务，请回馈社区：自行托管以减轻共享基础设施的负载、捐款，或向上游贡献代码或文档。

更新代码以使用新的端点和响应格式；使用 MapLibre 时，地图图层和交互代码（例如添加路线线条）保持不变。

8. 保持不变的部分

大多数地图代码无需更改：

• 地图方法：setCenter、setZoom、fitBounds、flyTo、getBounds 等。
• 事件：map.on('load')、map.on('click', layerId, callback) 等。
• 标记、弹出窗口、控件（导航、地理定位、全屏、比例尺）
• 数据源和图层：addSource、addLayer、setPaintProperty、setFilter
• 样式规范中的 GeoJSON 和表达式

因此，替换软件包、命名空间、令牌和样式（以及任何插件 / API）后，其余逻辑可以保持不变。

9. 转换仅适用于 Mapbox v2 的 API，不要查找它们

Mapbox GL JS v2 中分叉后新增的方法，在 MapLibre 中不会以 Mapbox 的名称出现，也没有任何 MapLibre 版本会添加这些方法。搜索 Mapbox 名称并得出“肯定是版本问题”的结论，是迁移中常见的死胡同——请改为查找 MapLibre 中对应的名称。

Mapbox GL JS v2	MapLibre GL JS	备注
map.setFog({...})，样式中的根级 fog	map.setSky({...}) / map.getSky()，样式中的根级 sky	MapLibre 的任何版本中都没有 setFog 方法；sky 和 setSky 从 GL JS v4.5.0 起可用。大气效果由 sky 控制，其属性包括 sky-color、horizon-color、fog-color、fog-ground-blend、horizon-fog-blend、sky-horizon-blend 和 atmosphere-blend。样式规范将 sky 标记为实验性功能。
map.getFreeCameraOptions() / map.setFreeCameraOptions()，FreeCameraOptions	map.calculateCameraOptionsFromCameraLngLatAltRotation(...) → jumpTo / easeTo / flyTo	MapLibre 没有 FreeCameraOptions 类，也没有 getFreeCameraOptions/setFreeCameraOptions。其相机参数包括 center、zoom、pitch、bearing，以及 CameraOptions 中的 elevation 和 roll（两者均自 v5.0.0 起可用）。若要通过相机自身的经纬度和海拔来定位，请使用 calculateCameraOptionsFromCameraLngLatAltRotation(cameraLngLat, cameraAlt, bearing, pitch, roll)（v5.0.0）进行转换；若要指定观察目标，则可使用 calculateCameraOptionsFromTo(from, altitudeFrom, to, altitudeTo)（v2.4.0）。然后将返回的 CameraOptions 传给 jumpTo、easeTo 或 flyTo。

// Mapbox GL JS v2
map.setFog({ 'horizon-blend': 0.3, color: '#ffffff' });

// MapLibre GL JS — the same idea, different property names
map.setSky({
  'sky-color': '#199EF3',
  'horizon-color': '#ffffff',
  'fog-color': '#0000ff',
  'fog-ground-blend': 0.5,
  'horizon-fog-blend': 0.5,
  'sky-horizon-blend': 0.5,
  'atmosphere-blend': 1.0
});

在假定升级会恢复其他 v2 方法之前，请先对照 Map API 参考进行核实。

检查清单

• 卸载 mapbox-gl，安装 maplibre-gl
• 替换导入和 CSS（mapbox-gl → maplibre-gl）
• 将所有 mapboxgl 替换为 maplibregl（并将 CSS 类 mapboxgl- → maplibregl-）
• 移除 mapboxgl.accessToken
• 将 style 设置为非 Mapbox URL（托管的样式或你自己的样式）
• 将不兼容的 Mapbox 插件替换为 MapLibre 插件或开放替代方案
• 将 Mapbox Geocoding/Directions 替换为 Nominatim、OSRM 或其他开放替代方案
• 替换仅适用于 Mapbox v2 的 API（setFog → setSky，free camera → calculateCameraOptionsFromCameraLngLatAltRotation + jumpTo/easeTo/flyTo）
• 测试地图加载、控件以及所有由 API 驱动的功能

相关技能

• maplibre-tile-sources — 为你的数据选择源类型
• maplibre-pmtiles-patterns — 使用 PMTiles 提供无服务器瓦片

本技能使用的来源

创建本技能时使用了以下来源。你可能需要联系维护这些来源或曾为其做出贡献的贡献者：

1. MapLibre 官方迁移指南 — maplibre.org/maplibre-gl-js/docs/guides/mapbox-migration-guide/ — 主要的分步参考（软件包、命名空间、CSS、CDN）。
2. MapLibre GL JS 文档 — maplibre.org/maplibre-gl-js/docs/ — API 和概念。
3. MapLibre Style Specification — sky — maplibre.org/maplibre-style-spec/sky/ 和 Map.setSky — 替代 Mapbox fog 的大气属性；Map.calculateCameraOptionsFromCameraLngLatAltRotation 和 CameraOptions — 替代 Mapbox free camera 的相机定位方式。
4. MapLibre GL JS GitHub — github.com/maplibre/maplibre-gl-js — README、版本发布记录和分叉历史。
5. mapbox-agent-skills — Mapbox 仓库中的 mapbox-maplibre-migration 技能介绍了相反方向（MapLibre → Mapbox）的迁移。本技能借鉴了其主题结构和对比内容，用于介绍 Mapbox → MapLibre 迁移。改编部分的版权归 Mapbox, Inc. 所有。
6. 本仓库的技能 — maplibre-tile-sources、maplibre-pmtiles-patterns；maplibre-open-search-patterns 和 maplibre-geospatial-operations 尚未加入仓库 — 用于迁移后的瓦片源和服务替代方案。

---

本技能是某一时点的快照。 如果主要来源与本技能内容相矛盾——包括上方的参考资料、MapLibre 当前文档，或实际运行时 MapLibre 的行为——以该来源为准。遵循该来源，然后报告此处的不一致，并注明来源和你的 MapLibre 版本：编辑你安装的副本无法帮助其他人，而且下次更新时会被覆盖。