# 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 * **目前：** 两个库都在继续积极开发 **关键见解：** API 大约有 95% 相同，因为 MapLibre 最初是作为 Mapbox 分支开始的。大多数代码只需很少的更改即可在两者中运行，从而使迁移变得简单。 ## 为什么迁移到 Mapbox？ **选择 Mapbox GL JS 的令人信服的理由：** * **官方支持和 SLA**：企业级支持，并保证响应时间 * **卓越的图块质量**：一流的矢量图块，覆盖全球且更新频繁 * **更好的卫星图像**：高分辨率、最新的卫星和航空图像 * **丰富的生态系统**：与 Mapbox Studio、API 和服务无缝集成 * **高级功能**：交通感知路线、逐向导航、高级数据集 * **地理编码和搜索**：世界一流的地址搜索和地点查找 * **导航SDK**：实时路况移动导航 * **无平铺基础设施**：无需托管或维护您自己的平铺服务器 * **定期更新**：持续改进和新功能 * **专业服务**：联系 Mapbox 解决方案团队处理复杂项目 **Mapbox 提供慷慨的免费套餐：** 每月 50,000 次地图加载，使其适合许多应用程序而无需付费。 ## 快速比较方面| Mapbox GL JS | MapLibre GL JS ---|---|--- **许可证** |专有 (v2+) | BSD 3 条款（开源） **支持** |官方商业支持 |社区支持 **瓷砖** |高级 Mapbox 矢量图块 | OSM 或自定义图块源 **卫星** |高质量的全球图像 |需要自定义源 **代币** |必需（访问令牌）|可选（取决于图块源） **API** |完整的 Mapbox 生态系统 |需要第三方服务 **工作室** |全面整合 |没有本机集成 **3D 地形** |内置优质数据 |可用（需要数据源） **全球视图** | v2.9+ | v3.0+ **API 兼容性** |与 MapLibre 兼容约 95% | ~95% 与 Mapbox 兼容 **捆绑尺寸** | 〜500KB | 〜450KB **设置复杂性** |简单（只需添加令牌）|需要瓦片源设置 ## 逐步迁移 ### 1\.创建 Mapbox 帐户 1. 在 [mapbox.com]() 注册 2. 从帐户仪表板获取您的访问令牌 3. 审核定价：免费套餐包括每月 50,000 次地图加载 4.记下您的令牌（对于公共令牌，以“pk.”开头） ### 2\.更新包 # 删除 MapLibre npm 卸载maplibre-gl # 安装 Mapbox npm 安装 mapbox-gl ### 3\.更新导入 // 之前 (MapLibre) 从“maplibre-gl”导入maplibregl；导入'maplibre-gl/dist/maplibre-gl.css'; // 之后（Mapbox）从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; 或者使用 CDN： ### 4\.添加访问令牌 // 在地图初始化之前添加此内容 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\.更新地图初始化 // 之前 (MapLibre) 常量地图=新maplibregl.Map({ 容器：'地图'， style: 'https://demotiles.maplibre.org/style.json', // 或您的自定义样式中心：[-122.4194, 37.7749], 变焦：12 }); // 之后（Mapbox） mapboxgl.accessToken = 'pk.your_mapbox_access_token'; 常量地图=新mapboxgl.Map({ 容器：'地图'， style: 'mapbox://styles/mapbox/standard', // Mapbox 样式中心：[-122.4194, 37.7749], 变焦：12 }); ### 6\.更新样式网址 Mapbox 提供专业设计、维护的样式： // Mapbox 内置样式样式：'mapbox://styles/mapbox/standard'; // Mapbox 标准（默认）样式：'mapbox://styles/mapbox/standard-satellite'; // Mapbox 标准卫星样式：'mapbox://styles/mapbox/streets-v12'; // 街道 v12 样式：'mapbox://styles/mapbox/satellite-v9'; // 卫星图像样式：'mapbox://styles/mapbox/satellite-streets-v12'; // 混合样式：'mapbox://styles/mapbox/outdoors-v12'; // 户外/休闲样式：'mapbox://styles/mapbox/light-v11'; // 浅色主题样式：'mapbox://styles/mapbox/dark-v11'; // 深色主题样式：'mapbox://styles/mapbox/navigation-day-v1'; // 导航（日）样式：'mapbox://styles/mapbox/navigation-night-v1'; // 导航（夜间） **自定义样式：** 您还可以从 Mapbox Studio 创建和使用自定义样式：样式：'mapbox://styles/您的用户名/您的样式id'； ### 7\.更新所有参考文献将所有“maplibregl”引用替换为“mapboxgl”： // 标记 const mark = new mapboxgl.Marker() // 是：maplibregl.Marker() .setLngLat([-122.4194, 37.7749]) .setPopup(new mapboxgl.Popup().setText('旧金山')) .addTo(地图); // 控件 map.addControl(new mapboxgl.NavigationControl(), '右上角'); 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-比较` | `mapbox-gl-比较` 示例： // 之前 (MapLibre) 从 '@maplibre/maplibre-gl-geocoder' 导入 MaplibreGeocoder； // 之后（Mapbox）从 '@mapbox/mapbox-gl-geocoder' 导入 MapboxGeocoder；地图.addControl( 新的 MapboxGeocoder({ 访问令牌：mapboxgl.accessToken，地图框gl: 地图框gl }) ）； ### 9\.其他一切保持不变所有地图代码、事件、图层和源的工作方式都相同： // 这段代码在两个库中的工作原理完全相同 map.on('加载', () => { map.addSource('点', { 类型：'geojson'，数据：geojson数据 }); 地图.addLayer({ id: '点层', 类型：'圆圈'，来源：“点”，油漆：{ '圆半径'：8， '圆圈颜色': '#ff0000' } }); }); // 事件的工作方式相同 map.on('点击', '点图层', (e) => { console.log(e.features[0].properties); }); // 所有map方法的工作原理都是一样的地图.setCenter([lng, lat]); 地图.setZoom(12); map.fitBounds(边界); 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')`等） * 标记/弹出 API（100% 兼容） * 层/源 API（100% 兼容） * GeoJSON 处理 * 自定义样式和表达方式 * 控件（导航、地理定位、缩放等） ## API 兼容性矩阵 ### 100% 兼容的 API 这些在两个库中的工作方式相同： // 映射方法地图.setCenter([lng, lat]); 地图.setZoom(缩放); map.fitBounds(边界); map.panTo([lng, lat]); map.flyTo({ 中心, 缩放 }); 地图.getCenter(); 地图.getZoom(); 地图.getBounds(); 地图.调整大小(); // 事件 map.on('加载', 回调); map.on('点击', 回调); map.on('移动', 回调); map.on('缩放', 回调); map.on('旋转', 回调); // 标记新的mapboxgl.Marker(); 标记.setLngLat([lng, lat]); 标记.setPopup(弹出); 标记.addTo(地图); 标记.删除(); 标记.setDraggable(true); // 弹出窗口新的mapboxgl.Popup(); popup.setLngLat([lng, lat]); popup.setHTML(html); popup.setText(文本); popup.addTo(地图); // 源和层 map.addSource(id, 源); 地图.removeSource(id); 地图.addLayer(图层); 地图.removeLayer(id); 地图.getSource(id); 地图.getLayer(id); // 样式 map.setPaintProperty(layerId, 属性, 值); map.setLayoutProperty(layerId, 属性, 值); map.setFilter(layerId, 过滤器); // 控件 map.addControl(控制, 位置); 新的mapboxgl.NavigationControl(); 新的mapboxgl.GeolocateControl(); 新的mapboxgl.FullscreenControl(); 新的mapboxgl.ScaleControl(); ## 并排示例 ### MapLibre GL JS（之前）从“maplibre-gl”导入maplibregl；导入'maplibre-gl/dist/maplibre-gl.css'; // OSM 块不需要令牌常量地图=新maplibregl.Map({ 容器：'地图'，样式：'https://demotiles.maplibre.org/style.json', 中心：[-122.4194, 37.7749], 变焦：12 }); map.on('加载', () => { 新的maplibregl.Marker() .setLngLat([-122.4194, 37.7749]) .setPopup(new maplibregl.Popup().setText('旧金山')) .addTo(地图); }); ### Mapbox GL JS（之后）从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; // 添加您的 Mapbox 令牌 mapboxgl.accessToken = 'pk.your_mapbox_access_token'; 常量地图=新mapboxgl.Map({ 容器：'地图'，样式：'mapbox://styles/mapbox/streets-v12', 中心：[-122.4194, 37.7749], 变焦：12 }); map.on('加载', () => { 新的mapboxgl.Marker() .setLngLat([-122.4194, 37.7749]) .setPopup(new mapboxgl.Popup().setText('旧金山')) .addTo(地图); }); **不同之处：** 包、导入、令牌和样式 URL。 **其他一切都是相同的。** ## Mapbox-独家功能迁移后，您可以访问这些仅限 Mapbox 的功能： ### 高级矢量图块 * **街道**：包含名称、盾牌和路线数据的综合道路网络 * **卫星**：定期更新高分辨率全球图像 * **地形**：带有山体阴影和 3D 地形的高程数据 * **交通** ：实时交通数据（带导航SDK） ### Mapbox API 将这些 API 与地图一起使用以增强功能： // 地理编码 API - 将地址转换为坐标常量响应 = 等待获取（ `https://api.mapbox.com/search/geocode/v6/forward?q=San+Francisco&access_token=${mapboxgl.accessToken}` ）； // Directions API - 获取路线导航常量方向 = 等待获取（ `https://api.mapbox.com/directions/v5/mapbox/driven/-122.42,37.78;-122.45,37.76?access_token=${mapboxgl.accessToken}` ）； // 等时线 API - 计算旅行时间多边形 const 等时线 = 等待获取（ `https://api.mapbox.com/isochrone/v1/mapbox/driven/-122.42,37.78?contours_minutes=5,10,15&access_token=${mapboxgl.accessToken}` ）； ### Mapbox 工作室 * 具有实时预览功能的视觉风格编辑器 * 数据集管理和编辑 * 具有自定义数据上传功能的图块集 * 协作团队功能 * 样式版本控制和发布 ### 高级功能 (v2.9+) * **地球仪投影**：从地球仪到墨卡托的无缝过渡 * **3D 建筑**：使用真实建筑足迹进行挤压 * **自定义地形**：使用您自己的 DEM 源 * **天空层** ：真实大气渲染 ## 框架集成迁移在所有框架中的工作方式都是相同的。有关详细的 React、Vue、Svelte、Angular 模式，请参阅“mapbox-web-integration-patterns”技能。 ### 反应示例从 'react' 导入 { useRef, useEffect }; 从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; // 设置令牌一次（可以在应用程序初始化时） mapboxgl.accessToken = process.env.REACT_APP_MAPBOX_TOKEN; 函数 MapComponent() { const mapRef = useRef(null); const mapContainerRef = useRef(null); 使用效果（（）=> { mapRef.current = 新的mapboxgl.Map({ 容器：mapContainerRef.current，样式：'mapbox://styles/mapbox/streets-v12', 中心：[-122.4194, 37.7749], 变焦：12 }); 返回（）=> { mapRef.current.remove(); }; }, []); 返回

; } 只需将“maplibregl”替换为“mapboxgl”并更新标记/样式 - 其他一切都相同！ ### Vue 示例 <模板>

<脚本设置> 从 'vue' 导入 { ref, onMounted, onUnmounted }; 从“mapbox-gl”导入mapboxgl；导入'mapbox-gl/dist/mapbox-gl.css'; mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN; const mapContainer = ref(null); 让地图=空；已安装（（）=> { 地图 = 新的 mapboxgl.Map({ 容器：mapContainer.value，样式：'mapbox://styles/mapbox/streets-v12', 中心：[-122.4194, 37.7749], 变焦：12 }); }); onUnmounted(() => { 地图？.remove(); }); <样式范围> .map-container { 高度：100vh； } ## 常见迁移问题 ### 问题 1：未设置令牌 **问题：** // 错误：“使用 Mapbox GL 需要有效的 Mapbox 访问令牌” const map = new mapboxgl.Map({...}); **解决方案：** // 在创建地图之前设置令牌 mapboxgl.accessToken = 'pk.your_token'; const map = new mapboxgl.Map({...}); ### 问题 2：Git 中的令牌 **问题：** // 令牌硬编码在源代码中 mapboxgl.accessToken = 'pk.eyJ1Ijoi...'; **解决方案：** // 使用环境变量 mapboxgl.accessToken = process.env.VITE_MAPBOX_TOKEN; // 添加到 .env 文件（未提交到 git） VITE_MAPBOX_TOKEN=pk.your_token // 将 .env 添加到 .gitignore 回声“.env”>> .gitignore ### 问题 3：URL 格式错误 **问题：** // MapLibre 风格的 URL 无法以最佳方式工作样式：'https://demotiles.maplibre.org/style.json'; **解决方案：** // 使用 Mapbox 风格的 URL 以获得更好的性能和功能样式：'mapbox://styles/mapbox/streets-v12'; ### 问题 4：插件兼容性 **问题：** // MapLibre 插件将无法工作从 '@maplibre/maplibre-gl-geocoder' 导入 MaplibreGeocoder； **解决方案：** // 使用Mapbox插件从 '@mapbox/mapbox-gl-geocoder' 导入 MapboxGeocoder； ### 问题 5：CDN URL **问题：** // CDN 错误 **解决方案：** // 使用 Mapbox CDN ## 迁移清单完成以下步骤即可成功迁移： * **创建 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** ：确保未提交令牌 ## 为什么选择 Mapbox ### 对于生产应用 **可靠性和支持：** * 为企业客户提供 99.9% 的正常运行时间 SLA * 24/7 支持并保证响应时间 * 复杂项目的专门解决方案工程师 * 定期平台更新和改进 **性能：** * 全球 CDN，用于快速交付图块 * 优化矢量切片以实现最小带宽 * 针对流量高峰自动扩展 * WebGL加速渲染 **特点：** * 专业制图和设计 * 定期更新地图数据 * 交通和路线数据 * 优质卫星图像 * 3D地形和建筑物 ### 对于开发团队 **开发人员经验：** * 带有示例的综合文档 * 活跃的社区和论坛 * SDK定期更新 * TypeScript 支持（通过 `@types/mapbox-gl`） * 丰富的示例库 **生态系统整合：** * 无缝工作室集成 * 跨服务的API一致性 * 移动 SDK（iOS、Android、React Native） * Unity 和虚幻引擎插件 * 分析和监控工具 ### 对于商业 **可预测的成本：** * 清晰、基于使用情况的定价 * 开发和小型应用程序的免费套餐 * 无基础设施成本 * 可扩展的定价以促进增长 **合规性与安全性：** * SOC 2 Type II 认证 * 符合 GDPR * 企业安全功能 * 审计日志和监控 **无基础设施负担：** * 无需维护平铺服务器 * 无需担心存储或带宽问题 * 无更新管理 * 专注于您的应用程序，而不是基础设施 ## 性能比较这两个库具有相似的渲染性能，因为它们共享相同的核心代码库：公制| Mapbox GL JS | MapLibre GL JS ---|---|--- **捆绑尺寸** | 〜500KB | 〜450KB **初始负载** |类似|类似 **渲染** |基于WebGL |基于WebGL **内存使用情况** |类似|类似 **瓷砖加载** |更快（CDN + 优化磁贴）|取决于瓷砖来源 **关键见解：** 根据功能、支持和图块质量而不是渲染性能进行选择。 Mapbox 的优势在于图块交付速度、数据质量和生态系统集成。 ## 与其他技能的整合 **相关技能：** * **mapbox-web-integration-patterns** ：特定于框架的模式（React、Vue、Svelte、Angular） * **mapbox-web-performance-patterns** ：性能优化技术 * **mapbox-token-security** ：全面的令牌安全最佳实践 * **mapbox-google-maps-migration** ：从 Google 地图迁移到 Mapbox ## 资源 **Mapbox GL JS：** * [官方文档]() * [示例库]() * [API参考]() * [GitHub 存储库]() * [Mapbox Studio]() * [定价信息]() **迁移支持：** * [入门指南]() * [样式规范]() * [Mapbox 社区支持]() ## 快速参考 ### 主要差异摘要什么 |地图自由 |地图盒 ---|---|--- 套餐 | `maplibre-gl` | `mapbox-gl` 进口| `从'maplibre-gl'导入maplibregl` | `从'mapbox-gl'导入mapboxgl` 代币|可选（取决于瓷砖）|必需：`mapboxgl.accessToken = 'pk.xxx'` 风格|自定义 URL 或 OSM 磁贴 | `mapbox://styles/mapbox/streets-v12` 许可证| BSD（开源）|专有 (v2+) 支持|社区 |官方商业支持瓷砖|需要瓦片源 |包含高级 Mapbox 瓷砖 API |第三方|完整的 Mapbox API 生态系统应用程序接口 | ~95% 兼容 | ~95% 兼容 **底线：** 迁移很容易，因为 API 几乎相同。主要变化是打包、令牌设置和样式 URL。其结果是可以访问 Mapbox 的优质图块、生态系统和支持。

Mapbox Maplibre 迁移

包含技能