mapbox-maplibre-migration

MapLibre 到 Mapbox 的迁移技能

从 MapLibre GL JS 迁移到 Mapbox GL JS 的专家指南。涵盖共同的历史、API 兼容性、迁移步骤，以及 Mapbox 平台的优势。

了解分支

历史

MapLibre GL JS 是 Mapbox GL JS v1.13.0 的开源分支，创建于 2020 年 12 月，当时 Mapbox 从 v2.0 开始更改了许可证。

时间线：

• 2020 年前： Mapbox GL JS 为开源软件（BSD 许可证）
• 2020 年 12 月： Mapbox GL JS v2.0 引入专有许可证
• 2020 年 12 月： 社区将 v1.13 分叉为 MapLibre GL JS
• 目前： 两个库都在持续积极开发

关键要点： 由于 MapLibre 起源于 Mapbox 的分支，两者的 API 有约 95% 相同。大多数代码都能在两者中运行，只需进行少量更改，因此迁移很简单。

为什么迁移到 Mapbox？

选择 Mapbox GL JS 的充分理由：

• 官方支持和 SLA： 企业级支持，保证响应时间
• 更出色的瓦片质量： 一流的矢量瓦片，覆盖全球且频繁更新
• 更优质的卫星图像： 高分辨率、及时更新的卫星和航拍图像
• 丰富的生态系统： 与 Mapbox Studio、API 和服务无缝集成
• 高级功能： 考虑交通状况的路线规划、逐向导航、高级数据集
• 地理编码和搜索： 世界一流的地址搜索和地点查找
• 导航 SDK： 支持实时交通状况的移动导航
• 无需瓦片基础设施： 无需托管或维护自己的瓦片服务
• 定期更新： 持续改进并推出新功能
• 专业服务： 复杂项目可获得 Mapbox 解决方案团队的支持

Mapbox 提供了慷慨的免费层级： 每月 50,000 次地图加载，许多应用无需付费即可使用。

快速对比

方面	Mapbox GL JS	MapLibre GL JS
许可证	专有（v2+）	BSD 3-Clause（开源）
支持	官方商业支持	社区支持
瓦片	高级 Mapbox 矢量瓦片	OSM 或自定义瓦片源
卫星图像	高质量全球图像	需要自定义数据源
令牌	必需（访问令牌）	可选（取决于瓦片源）
API	完整的 Mapbox 生态系统	需要第三方服务
Studio	完全集成	无原生集成
3D 地形	内置高级数据	可用（需要数据源）
地球视图	v2.9+	v3.0+
API 兼容性	与 MapLibre 约 95% 兼容	与 Mapbox 约 95% 兼容
打包体积	约 500KB	约 450KB
设置复杂度	简单（只需添加令牌）	需要设置瓦片源

逐步迁移

1. 创建 Mapbox 账户

1. 在 mapbox.com 注册
2. 从账户控制面板获取访问令牌
3. 查看定价：免费层级每月包含 50,000 次地图加载
4. 记下令牌（公开令牌以 pk. 开头）

2. 更新软件包

# Remove MapLibre
npm uninstall maplibre-gl

# Install Mapbox
npm install mapbox-gl

3. 更新导入语句

// Before (MapLibre)
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

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

或使用 CDN：

<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>
<link href="https://unpkg.com/[email protected]/dist/maplibre-gl.css" rel="stylesheet" />


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

4. 添加访问令牌

// Add this before map initialization
mapboxgl.accessToken = 'pk.your_mapbox_access_token';

令牌最佳实践：

• 使用环境变量：process.env.VITE_MAPBOX_TOKEN 或 process.env.NEXT_PUBLIC_MAPBOX_TOKEN
• 在 Mapbox 控制面板中添加 URL 限制以增强安全性
• 客户端代码使用公开令牌（pk.*）
• 切勿将令牌提交到 git（将令牌添加到 .env 和 .gitignore）
• 如果令牌泄露，请轮换令牌

如需全面了解令牌安全，请参阅 mapbox-token-security 技能。

5. 更新地图初始化

// Before (MapLibre)
const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json', // or your custom style
  center: [-122.4194, 37.7749],
  zoom: 12
});

// After (Mapbox)
mapboxgl.accessToken = 'pk.your_mapbox_access_token';

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/standard', // Mapbox style
  center: [-122.4194, 37.7749],
  zoom: 12
});

6. 更新样式 URL

Mapbox 提供专业设计并持续维护的样式：

// Mapbox built-in styles
style: 'mapbox://styles/mapbox/standard'; // Mapbox Standard (default)
style: 'mapbox://styles/mapbox/standard-satellite'; // Mapbox Standard Satellite
style: 'mapbox://styles/mapbox/streets-v12'; // Streets v12
style: 'mapbox://styles/mapbox/satellite-v9'; // Satellite imagery
style: 'mapbox://styles/mapbox/satellite-streets-v12'; // Hybrid
style: 'mapbox://styles/mapbox/outdoors-v12'; // Outdoor/recreation
style: 'mapbox://styles/mapbox/light-v11'; // Light theme
style: 'mapbox://styles/mapbox/dark-v11'; // Dark theme
style: 'mapbox://styles/mapbox/navigation-day-v1'; // Navigation (day)
style: 'mapbox://styles/mapbox/navigation-night-v1'; // Navigation (night)

自定义样式： 你也可以在 Mapbox Studio 中创建并使用自定义样式：

style: 'mapbox://styles/your-username/your-style-id';

7. 更新所有引用

将所有 maplibregl 引用替换为 mapboxgl：

// Markers
const marker = new mapboxgl.Marker() // was: maplibregl.Marker()
  .setLngLat([-122.4194, 37.7749])
  .setPopup(new mapboxgl.Popup().setText('San Francisco'))
  .addTo(map);

// Controls
map.addControl(new mapboxgl.NavigationControl(), 'top-right');
map.addControl(new mapboxgl.GeolocateControl());
map.addControl(new mapboxgl.FullscreenControl());
map.addControl(new mapboxgl.ScaleControl());

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

部分 MapLibre 插件应替换为 Mapbox 版本：

MapLibre 插件	Mapbox 替代项
@maplibre/maplibre-gl-geocoder	@mapbox/mapbox-gl-geocoder
@maplibre/maplibre-gl-draw	@mapbox/mapbox-gl-draw
maplibre-gl-compare	mapbox-gl-compare

示例：

// Before (MapLibre)
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

// After (Mapbox)
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

map.addControl(
  new MapboxGeocoder({
    accessToken: mapboxgl.accessToken,
    mapboxgl: mapboxgl,
    countries: 'us', // ISO 3166-1 alpha-2 code(s), comma-separated; hard filter, not a soft bias
    language: 'en' // Also affects which result ranks first, not just the UI/response text
  })
);

注意： countries 和 language 会改变返回的结果，而不只是改变筛选或显示方式。language 会影响结果评分（同一个查询可能会因语言不同而将不同地点排在首位），而 countries 会排除不在所列代码中的所有结果。请保留原 MapLibre 地理编码器中的任何区域设置或地区限制。

9. 其他内容保持不变

所有地图代码、事件、图层和数据源的工作方式都完全相同：

// This code works EXACTLY THE SAME in both libraries
map.on('load', () => {
  map.addSource('points', {
    type: 'geojson',
    data: geojsonData
  });

  map.addLayer({
    id: 'points-layer',
    type: 'circle',
    source: 'points',
    paint: {
      'circle-radius': 8,
      'circle-color': '#ff0000'
    }
  });
});

// Events work identically
map.on('click', 'points-layer', (e) => {
  console.log(e.features[0].properties);
});

// All map methods work the same
map.setCenter([lng, lat]);
map.setZoom(12);
map.fitBounds(bounds);
map.flyTo({ center: [lng, lat], zoom: 14 });

变更内容：总结

必须变更：

• 包名称（maplibre-gl -> mapbox-gl）
• 导入语句
• 添加 mapboxgl.accessToken 配置
• 样式 URL（切换为 mapbox:// 样式）
• 插件包（如果使用）

保持完全不变：

• 所有地图方法（setCenter、setZoom、fitBounds、flyTo 等）
• 所有事件处理（map.on('click')、map.on('load') 等）
• Marker/Popup API（100% 兼容）
• 图层/数据源 API（100% 兼容）
• GeoJSON 处理
• 自定义样式和表达式
• 控件（Navigation、Geolocate、Scale 等）

常见迁移问题

问题 1：未设置令牌

问题：

// Error: "A valid Mapbox access token is required to use Mapbox GL"
const map = new mapboxgl.Map({...});

解决方案：

// Set token BEFORE creating map
mapboxgl.accessToken = 'pk.your_token';
const map = new mapboxgl.Map({...});

问题 2：令牌提交到了 Git

问题：

// Token hardcoded in source
mapboxgl.accessToken = 'pk.eyJ1Ijoi...';

解决方案：

// Use environment variables
mapboxgl.accessToken = process.env.VITE_MAPBOX_TOKEN;

// Add to .env file (not committed to git)
VITE_MAPBOX_TOKEN=pk.your_token

// Add .env to .gitignore
echo ".env" >> .gitignore

问题 3：样式 URL 格式错误

问题：

// MapLibre-style URL won't work optimally
style: 'https://demotiles.maplibre.org/style.json';

解决方案：

// Use Mapbox style URL for better performance and features
style: 'mapbox://styles/mapbox/streets-v12';

问题 4：插件兼容性

问题：

// MapLibre plugin won't work
import MaplibreGeocoder from '@maplibre/maplibre-gl-geocoder';

解决方案：

// Use Mapbox plugin
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';

重要： 这适用于所有 MapLibre 插件，而不只是地理编码器。任何 @maplibre/* 或 maplibre-gl-* 插件都必须替换为对应的 Mapbox 插件。请在 Mapbox 生态系统中查找你所用每个插件的 Mapbox 专用版本（完整映射表见上文步骤 8）。

问题 5：CDN URL

问题：

// Wrong CDN
<script src="https://unpkg.com/[email protected]/dist/maplibre-gl.js"></script>

解决方案：

// Use Mapbox CDN
<script src='https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.0.0/mapbox-gl.css' rel='stylesheet' />

迁移检查清单

• 创建 Mapbox 账户并获取访问令牌
• 更新包：npm install mapbox-gl（移除 maplibre-gl）
• 更新导入：maplibre-gl -> mapbox-gl
• 更新 CSS 导入：maplibre-gl.css -> mapbox-gl.css
• 添加令牌：设置 mapboxgl.accessToken = 'pk.xxx'
• 使用环境变量：将令牌存储在 .env 中
• 更新样式 URL：改为 mapbox://styles/mapbox/streets-v12
• 更新所有引用：将 maplibregl. 替换为 mapboxgl.
• 更新插件：安装插件的 Mapbox 版本（如果使用）
• 配置令牌安全性：在控制面板中添加 URL 限制
• 测试所有功能：确认地图能加载且交互正常
• 设置账单提醒：在 Mapbox 控制面板中监控用量
• 更新文档：为团队说明令牌设置方法
• 将 .env 添加到 .gitignore：确保令牌不会被提交

快速参考

主要差异概览

内容	MapLibre	Mapbox
包	maplibre-gl	mapbox-gl
导入	import maplibregl from 'maplibre-gl'	import mapboxgl from 'mapbox-gl'
令牌	可选（取决于瓦片）	必需：mapboxgl.accessToken = 'pk.xxx'
样式	自定义 URL 或 OSM 瓦片	mapbox://styles/mapbox/streets-v12
许可证	BSD（开源）	专有（v2+）
支持	社区支持	官方商业支持
瓦片	需要瓦片来源	包含 Mapbox 高级瓦片
API	第三方	完整的 Mapbox API 生态系统
API	约 95% 兼容	约 95% 兼容

总之： 由于 API 几乎相同，迁移很容易。主要变化在于打包方式、令牌设置和样式 URL。迁移后即可使用 Mapbox 的高级瓦片、生态系统和支持。

与其他技能集成

相关技能：

• mapbox-web-integration-patterns：特定框架的模式（React、Vue、Svelte、Angular）
• mapbox-web-performance-patterns：性能优化技巧
• mapbox-token-security：全面的令牌安全最佳实践
• mapbox-google-maps-migration：从 Google Maps 迁移到 Mapbox

资源

Mapbox GL JS：

• 官方文档
• 示例库
• API 参考
• GitHub 仓库
• Mapbox Studio
• 定价信息

迁移支持：

• 入门指南
• 样式规范
• Mapbox 社区支持

参考文件

如需了解特定主题的详细信息，请加载以下参考文件：

• references/api-compatibility.md —— 100% 兼容的 API 完整列表及并列迁移示例
• references/exclusive-features.md —— Mapbox 独有功能（API、Studio、高级功能）及 React/Vue 框架示例
• references/why-mapbox.md —— 选择 Mapbox 的理由（生产环境、开发团队、业务）及性能对比