Back to Details

maplibre-mapbox-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Mapbox to MapLibre Migration

Mapbox 到 MapLibre 迁移指南

This skill guides you through migrating an application from Mapbox GL JS to MapLibre GL JS. The two libraries share a common ancestry (MapLibre forked from Mapbox GL JS v1.13 in December 2020), so the API is largely the same. The main changes are: swap the package, replace the namespace, remove the Mapbox access token, and choose a new tile source (MapLibre does not use 
mapbox://
styles).
Primary reference: MapLibre official Mapbox migration guide.
本指南将带你完成应用从Mapbox GL JS到MapLibre GL JS的迁移流程。这两个库同出一源（MapLibre是2020年12月从Mapbox GL JS v1.13分支出来的项目），因此API基本一致。主要改动包括：替换依赖包、更换命名空间、移除Mapbox访问令牌，以及选择新的瓦片源（MapLibre不支持
mapbox://
样式）。
主要参考： MapLibre官方Mapbox迁移指南

When to Use This Skill

何时使用本指南

  • Migrating an existing Mapbox GL JS app to MapLibre
  • Evaluating MapLibre as an open-source alternative to Mapbox
  • Understanding API compatibility and what breaks
  • Choosing tile sources and services after moving off Mapbox
  • 将现有Mapbox GL JS应用迁移到MapLibre
  • 评估MapLibre作为Mapbox开源替代方案的可行性
  • 了解API兼容性及不兼容的内容
  • 脱离Mapbox后选择瓦片源和相关服务

Why Migrate to MapLibre?

为什么要迁移到MapLibre？

Common reasons teams switch from Mapbox to MapLibre:
  • Open-source license — MapLibre is BSD-3-Clause; no vendor lock-in or proprietary terms
  • No access token — The library does not require a Mapbox token; tile sources may have their own keys or none (e.g. OpenFreeMap)
  • Cost — Avoid Mapbox map-load and API pricing; use free or fixed-cost tile and geocoding providers
  • Self-hosting — Use your own tiles (PMTiles, tileserver-gl, martin) or any third-party source
  • Community — MapLibre is maintained by the MapLibre organization and community; style spec and APIs evolve in the open
  • Community-supported funding — MapLibre is funded by donations from many companies and individuals; there is no single commercial backer, so the project stays aligned with the community
  • Open vector tile format (MLT) — MapLibre offers MapLibre Tile (MLT), a modern alternative to Mapbox Vector Tiles (MVT) with better compression and support for 3D coordinates and elevation; supported in GL JS and Native, and generatable with Planetiler
What you give up: Mapbox Studio integration, Mapbox-hosted tiles and styles, Mapbox Search/Directions/Geocoding APIs, official Mapbox support. You replace these with open or third-party alternatives (see maplibre-tile-sources; maplibre-open-search-patterns and maplibre-geospatial-operations not yet in repo).
团队从Mapbox切换到MapLibre的常见原因：
  • 开源许可证 —— MapLibre采用BSD-3-Clause许可证，无厂商锁定或专有条款限制
  • 无需访问令牌 —— 库本身不需要Mapbox令牌，瓦片源可自行选择需要密钥或无需密钥的服务（例如OpenFreeMap）
  • 成本优势 —— 规避Mapbox的地图加载和API计费，可使用免费或固定成本的瓦片和地理编码服务商
  • 支持自托管 —— 可使用自有瓦片（PMTiles、tileserver-gl、martin）或任意第三方数据源
  • 社区驱动 —— MapLibre由MapLibre组织和社区共同维护，样式规范和API的演进完全公开
  • 社区资助模式 —— MapLibre由众多企业和个人捐赠资助，没有单一商业赞助商，项目始终与社区利益保持一致
  • 开源矢量瓦片格式（MLT） —— MapLibre推出了MapLibre Tile (MLT)，这是Mapbox矢量瓦片（MVT）的现代替代方案，压缩率更高，支持3D坐标和高程，已在GL JS和原生端支持，可通过Planetiler生成
迁移的取舍： 你将失去Mapbox Studio集成、Mapbox托管的瓦片和样式、Mapbox搜索/路线规划/地理编码API、官方Mapbox支持。你可以用开源或第三方替代方案替换这些能力（参考maplibre-tile-sources；maplibre-open-search-patterns和maplibre-geospatial-operations暂未收录到仓库）。

Understanding the Fork

了解分支背景

  • Dec 2020: Mapbox GL JS v2.0 switched to a proprietary license. The community forked v1.13 as MapLibre GL JS. MapLibre organization and GL JS repo are the canonical homes.
  • API: MapLibre GL JS v1.x is largely backward compatible with Mapbox GL JS v1.x. Most map code (methods, events, layers, sources) works with minimal changes.
  • Releases since the fork: MapLibre has moved ahead with its own version line. v2/v3 brought WebGL2, a modern renderer, and features like hillshade and terrain; v4 introduced Promises in public APIs (replacing many callbacks); v5 added globe view and the Adaptive Composite Map Projection. See releases and CHANGELOG.
  • Style spec: MapLibre maintains its own MapLibre Style Specification (forked from the Mapbox spec). It is compatible for most styles but has added and diverged in places; check the style spec site when using newer or MapLibre-specific features.
  • Ecosystem: Besides GL JS, the MapLibre org hosts MapLibre Native (iOS, Android, desktop), Martin (vector tile server from PostGIS/PMTiles/MBTiles), and the MapLibre Tile (MLT) format. Roadmaps and news: maplibre.org/roadmap, maplibre.org/news.
  • 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/v3引入了WebGL2、现代渲染器，以及山体阴影、地形等特性；v4在公共API中引入了Promises（替换了大量回调）；v5新增了地球视图和自适应复合地图投影。可查看版本发布和更新日志。
  • 样式规范： MapLibre维护了独立的MapLibre样式规范（从Mapbox规范分支而来），大多数样式都兼容，但也新增了部分特性并存在差异，使用新特性或MapLibre专属特性时可查阅样式规范官网。
  • 生态： 除了GL JS，MapLibre组织还托管了MapLibre Native（支持iOS、Android、桌面端）、Martin（支持PostGIS/PMTiles/MBTiles的矢量瓦片服务），以及MapLibre Tile (MLT)格式。路线图和动态可查看：maplibre.org/roadmap、maplibre.org/news

Step-by-Step Migration

分步迁移指南

1. Swap the Package

1. 替换依赖包

bash
npm uninstall mapbox-gl
npm install maplibre-gl
bash
npm uninstall mapbox-gl
npm install maplibre-gl

2. Update Imports and CSS

2. 更新导入和CSS

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

// After (MapLibre)
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
CDN: Replace Mapbox script/link with MapLibre:
  • Script: 
    https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.js
    → 
    https://unpkg.com/maplibre-gl@*.*.*/dist/maplibre-gl.js
  • CSS: same pattern (mapbox-gl.css → maplibre-gl.css).
javascript
// 迁移前（Mapbox）
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

// 迁移后（MapLibre）
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
CDN引入： 将Mapbox的脚本/链接替换为MapLibre对应资源：
  • 脚本：
    https://api.mapbox.com/mapbox-gl-js/v*.*.*/mapbox-gl.js
    → 
    https://unpkg.com/maplibre-gl@*.*.*/dist/maplibre-gl.js
  • CSS：遵循相同规则替换（mapbox-gl.css → maplibre-gl.css）

3. Replace the Namespace

3. 替换命名空间

Replace all 
mapboxgl
with 
maplibregl
(and 
mapbox-gl
with 
maplibre-gl
in package names or paths). Examples:
javascript
// 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 class names: If you style controls or UI by class, rename 
mapboxgl-ctrl
to 
maplibregl-ctrl
(and similar prefixes).
将所有
mapboxgl
替换为
maplibregl
（包名或路径中的
mapbox-gl
替换为
maplibre-gl
）。示例：
javascript
// 迁移前（Mapbox）
const map = new mapboxgl.Map({ ... });
new mapboxgl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new mapboxgl.NavigationControl());

// 迁移后（MapLibre）
const map = new maplibregl.Map({ ... });
new maplibregl.Marker().setLngLat([lng, lat]).addTo(map);
map.addControl(new maplibregl.NavigationControl());
CSS类名： 如果你通过类名自定义控件或UI样式，将
mapboxgl-ctrl
重命名为
maplibregl-ctrl
（以及其他类似前缀）。

4. Remove the Access Token

4. 移除访问令牌

MapLibre does not use 
mapboxgl.accessToken
. Remove any line that sets it:
javascript
// Remove this
mapboxgl.accessToken = process.env.MAPBOX_TOKEN;
Tile and API keys (e.g. for MapTiler or geocoding) are configured per service, not on the map instance. See maplibre-tile-sources for providers that need a key.
MapLibre不使用
mapboxgl.accessToken
，删除所有设置该属性的代码行：
javascript
// 删除此行
mapboxgl.accessToken = process.env.MAPBOX_TOKEN;
瓦片和API密钥（例如MapTiler或地理编码服务的密钥）需要针对每个服务单独配置，而非在地图实例上设置。需要密钥的服务商可参考maplibre-tile-sources。

5. Replace the Style URL (Critical)

5. 替换样式URL（关键步骤）

Mapbox styles (
mapbox://styles/...
) will not work in MapLibre. You must point the map to a style that uses non-Mapbox tile sources.
Options:
  • OpenFreeMap (no key): 
    style: 'https://tiles.openfreemap.org/styles/liberty'
    or 
    'https://tiles.openfreemap.org/styles/positron'
  • MapTiler (key required): Use a MapTiler style URL (see maplibre-tile-sources)
  • Your own style: A style JSON that references vector/raster tile URLs, plus glyphs and sprite (see maplibre-tile-sources; maplibre-style-patterns not yet in repo)
  • PMTiles: Use the pmtiles protocol and a .pmtiles URL in your style (see maplibre-pmtiles-patterns)
Example:
javascript
// 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
});
Custom Mapbox styles: If you designed a style in Mapbox Studio, you cannot load it directly in MapLibre. Export the style JSON if possible and replace Mapbox source URLs with a MapLibre-compatible tile source (e.g. OpenMapTiles schema from MapTiler or self-hosted). Layer and paint configuration often stays the same; source and source-layer names may need adjustment (e.g. OpenMapTiles uses 
transportation
instead of 
road
in some cases).
Mapbox样式（
mapbox://styles/...
）无法在MapLibre中运行，你必须将地图指向使用非Mapbox瓦片源的样式。
可选方案：
  • OpenFreeMap（无需密钥）： 
    style: 'https://tiles.openfreemap.org/styles/liberty'
    或 
    'https://tiles.openfreemap.org/styles/positron'
  • MapTiler（需要密钥）： 使用MapTiler样式URL（参考maplibre-tile-sources）
  • 自定义样式： 引用矢量/栅格瓦片URL、字形和精灵图的样式JSON（参考maplibre-tile-sources；maplibre-style-patterns暂未收录到仓库）
  • PMTiles： 在样式中使用pmtiles协议和.pmtiles URL（参考maplibre-pmtiles-patterns）
示例：
javascript
// 迁移前（Mapbox）
const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-122.42, 37.78],
  zoom: 12
});

// 迁移后（MapLibre）
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://tiles.openfreemap.org/styles/liberty', // 或你选择的其他样式
  center: [-122.42, 37.78],
  zoom: 12
});
自定义Mapbox样式： 如果你在Mapbox Studio中设计了样式，无法直接在MapLibre中加载。如果可以导出样式JSON，将Mapbox数据源URL替换为兼容MapLibre的瓦片源（例如来自MapTiler或自托管的OpenMapTiles schema）。图层和渲染配置通常可以保留，数据源和数据源图层名称可能需要调整（例如OpenMapTiles中部分场景使用
transportation
而非
road
）。

6. Update Plugins (If Used)

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

If you use Mapbox-specific plugins, switch to MapLibre or open alternatives. Common equivalents:
Mapbox PluginMapLibre / Alternative
@mapbox/mapbox-gl-geocoder
@maplibre/maplibre-gl-geocoder
 or Nominatim/Photon (see maplibre-open-search-patterns, not yet in repo)
@mapbox/mapbox-gl-draw
@maplibre/maplibre-gl-draw
mapbox-gl-compare
maplibre-gl-compare
mapboxgl-minimap
maplibregl-minimap
 or community alternatives
Mapbox Directions API + UI
maplibre-gl-directions
 (client-side routing with OSRM etc.) or custom + OSRM/OpenRouteService
Full lists: MapLibre GL JS – Plugins (official docs) and Made with MapLibre – Plugins (community directory). Many Mapbox plugins work with MapLibre by passing 
maplibregl
instead of 
mapboxgl
; for long-term maintenance, prefer plugins that officially support MapLibre.
Install the MapLibre variant and replace the import and constructor (e.g. 
mapboxgl
→ 
maplibregl
where the plugin expects the library reference).
如果你使用Mapbox专属插件，切换为MapLibre或开源替代方案。常见等效插件：
Mapbox插件MapLibre/替代方案
@mapbox/mapbox-gl-geocoder
@maplibre/maplibre-gl-geocoder
 或 Nominatim/Photon（参考maplibre-open-search-patterns，暂未收录到仓库）
@mapbox/mapbox-gl-draw
@maplibre/maplibre-gl-draw
mapbox-gl-compare
maplibre-gl-compare
mapboxgl-minimap
maplibregl-minimap
 或社区替代方案
Mapbox路线规划API + UI
maplibre-gl-directions
（配合OSRM等实现客户端路由）或自定义实现 + OSRM/OpenRouteService
完整列表： MapLibre GL JS – 插件（官方文档）和Made with MapLibre – 插件（社区目录）。很多Mapbox插件可以通过传入
maplibregl
而非
mapboxgl
在MapLibre中运行；长期维护的话，优先选择官方支持MapLibre的插件。
安装MapLibre版本的插件，替换导入语句和构造函数（例如插件需要传入库引用的地方，将
mapboxgl
替换为
maplibregl
）。

7. Replace Mapbox APIs (Search, Directions, etc.)

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

If your app calls Mapbox Geocoding, Directions, or other REST APIs, replace them with open or third-party services:
  • Geocoding / search: Nominatim, Photon, Pelias, or MapTiler Geocoding (see maplibre-open-search-patterns, not yet in repo)
  • Directions / routing: OSRM, OpenRouteService, Valhalla (see maplibre-geospatial-operations, not yet in repo)
Update your code to use the new endpoints and response formats; the map layer and interaction code (e.g. adding a route line) stays the same with MapLibre.
如果你的应用调用了Mapbox地理编码、路线规划或其他REST API，替换为开源或第三方服务：
  • 地理编码/搜索： Nominatim、Photon、Pelias或MapTiler地理编码（参考maplibre-open-search-patterns，暂未收录到仓库）
  • 路线规划/导航： OSRM、OpenRouteService、Valhalla（参考maplibre-geospatial-operations，暂未收录到仓库）
更新代码适配新的接口和响应格式；地图图层和交互代码（例如添加路线线图层）在MapLibre中可以保持不变。

8. What Stays the Same

8. 无需改动的内容

Most of your map code does not change:
  • Map methods: 
    setCenter
    , 
    setZoom
    , 
    fitBounds
    , 
    flyTo
    , 
    getBounds
    , etc.
  • Events: 
    map.on('load')
    , 
    map.on('click', layerId, callback)
    , etc.
  • Markers, popups, controls (Navigation, Geolocate, Fullscreen, Scale)
  • Sources and layers: 
    addSource
    , 
    addLayer
    , 
    setPaintProperty
    , 
    setFilter
  • GeoJSON and expressions in the style spec
So after swapping the package, namespace, token, and style (and any plugins/APIs), the rest of your logic can stay as is.
大多数地图代码不需要修改：
  • 地图方法：
    setCenter
    、
    setZoom
    、
    fitBounds
    、
    flyTo
    、
    getBounds
    等
  • 事件：
    map.on('load')
    、
    map.on('click', layerId, callback)
    等
  • 标记、弹窗、控件（导航、定位、全屏、比例尺）
  • 数据源和图层：
    addSource
    、
    addLayer
    、
    setPaintProperty
    、
    setFilter
  • 样式规范中的GeoJSON和表达式
因此替换完依赖包、命名空间、令牌、样式（以及相关插件/API）后，其余逻辑可以保持原样。

Checklist

检查清单

  • Uninstall 
    mapbox-gl
    , install 
    maplibre-gl
  • Replace imports and CSS (mapbox-gl → maplibre-gl)
  • Replace all 
    mapboxgl
    with 
    maplibregl
    (and CSS classes 
    mapboxgl-
    → 
    maplibregl-
    )
  • Remove 
    mapboxgl.accessToken
  • Set 
    style
    to a non-Mapbox URL (OpenFreeMap, MapTiler, or your own style)
  • Replace Mapbox plugins with MapLibre or open alternatives
  • Replace Mapbox Geocoding/Directions with Nominatim, OSRM, or other (see other skills)
  • Test map load, controls, and any API-driven features
  • 卸载
    mapbox-gl
    ，安装
    maplibre-gl
  • 替换导入语句和CSS（mapbox-gl → maplibre-gl）
  • 将所有
    mapboxgl
    替换为
    maplibregl
    （CSS类
    mapboxgl-
    → 
    maplibregl-
    ）
  • 移除
    mapboxgl.accessToken
    相关代码
  • 将
    style
    设置为非Mapbox URL（OpenFreeMap、MapTiler或自定义样式）
  • 将Mapbox插件替换为MapLibre或开源替代方案
  • 将Mapbox地理编码/路线规划替换为Nominatim、OSRM或其他服务（参考其他指南）
  • 测试地图加载、控件以及所有API驱动的功能

Related Skills

相关指南

  • maplibre-tile-sources — Choosing and configuring tile sources (OpenFreeMap, MapTiler, PMTiles, self-hosted)
  • maplibre-pmtiles-patterns — Serverless tiles with PMTiles
  • maplibre-open-search-patterns — Geocoding and search (Nominatim, Photon, etc.). Not yet in repo.
  • maplibre-geospatial-operations — Routing and geometry (OSRM, OpenRouteService, Turf.js). Not yet in repo.
  • maplibre-web-integration-patterns — Framework integration (React, Vue, etc.) with MapLibre. Not yet in repo.
  • maplibre-tile-sources —— 选择和配置瓦片源（OpenFreeMap、MapTiler、PMTiles、自托管）
  • maplibre-pmtiles-patterns —— 基于PMTiles的无服务瓦片方案
  • maplibre-open-search-patterns —— 地理编码和搜索（Nominatim、Photon等），暂未收录到仓库
  • maplibre-geospatial-operations —— 路线规划和几何处理（OSRM、OpenRouteService、Turf.js），暂未收录到仓库
  • maplibre-web-integration-patterns —— MapLibre与框架集成（React、Vue等），暂未收录到仓库

Sources Used for This Skill

本指南参考来源

These sources were used when creating this skill. You may want to involve contributors who maintain or have contributed to them:
  1. MapLibre official migration guide — maplibre.org/maplibre-gl-js/docs/guides/mapbox-migration-guide/ — Primary step-by-step reference (package, namespace, CSS, CDN).
  2. MapLibre GL JS documentation — maplibre.org/maplibre-gl-js/docs/ — API and concepts.
  3. MapLibre GL JS GitHub — github.com/maplibre/maplibre-gl-js — README, releases, and fork history.
  4. mapbox-agent-skills — The 
    mapbox-maplibre-migration
    skill (Mapbox repo) covers the reverse direction (MapLibre → Mapbox). Topic structure and comparison elements were adapted for this Mapbox → MapLibre skill. Copyright (c) Mapbox, Inc. for adapted portions.
  5. This repo’s skills — maplibre-tile-sources, maplibre-pmtiles-patterns; maplibre-open-search-patterns and maplibre-geospatial-operations not yet in repo — for tile source and service alternatives after migration.
创建本指南时使用了以下来源，你可以联系维护或贡献过这些内容的开发者获取更多信息：
  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 GL JS GitHub仓库 —— github.com/maplibre/maplibre-gl-js —— README、版本发布和分支历史
  4. mapbox-agent-skills —— 
    mapbox-maplibre-migration
    指南（Mapbox仓库）覆盖了反向迁移（MapLibre → Mapbox）的内容，本指南的主题结构和对比内容改编自该项目，改编部分版权归Mapbox, Inc.所有
  5. 本仓库的其他指南 —— maplibre-tile-sources、maplibre-pmtiles-patterns；maplibre-open-search-patterns和maplibre-geospatial-operations暂未收录到仓库 —— 提供迁移后的瓦片源和服务替代方案参考