从 Google Maps 迁移到 Mapbox GL…

需要把基于 Google Maps Platform 的前端地图功能迁移到 Mapbox GL JS 时使用。

适用场景

解决思路

1. 理解核心哲学差异：Google Maps 是命令式、面向对象，创建 Marker、Polygon 等对象并用 .setMap(map) 添加、用 setter 更新属性；Mapbox GL JS 是声明式、数据驱动，添加数据源、定义图层、用 JSON 样式，更新数据而非对象属性。
2. 初始化 Mapbox 地图：设置 mapboxgl.accessToken = 'YOUR_MAPBOX_TOKEN'；使用 new mapboxgl.Map({ container: 'map', style: 'mapbox://styles/mapbox/streets-v12', center: [-122.4194, 37.7749], zoom: 12 })；container 传元素 id，style 使用完整样式 URL，center 使用 [lng, lat] 顺序。
3. 替换 Google 地图初始化：将 new google.maps.Map(document.getElementById('map'), { center: { lat, lng }, zoom, mapTypeId }) 替换为 new mapboxgl.Map()，并更新 center、zoom、style。
4. 注意坐标顺序：Google 使用 {lat, lng}，Mapbox 使用 [lng, lat]；center、marker、fitBounds、事件坐标等全部需要反转。
5. 注意认证方式：Google 在 script 标签中使用 API key，Mapbox 在代码中设置 access token。
6. 注意样式方式：Google 使用 mapTypeId（如 roadmap、satellite、hybrid、terrain），Mapbox 使用完整 style URL（如 streets-v12、satellite-v9、outdoors-v12），并用 map.setStyle(styleUrl) 替代 map.setMapTypeId(type)。
7. 地图方法替换 map.setCenter(latLng)：使用 map.setCenter([lng, lat])，坐标顺序反转。
8. 地图方法替换 map.getCenter()：使用 map.getCenter()，返回 LngLat 对象。
9. 地图方法替换 map.setZoom(zoom)：使用 map.setZoom(zoom)，行为相同。
10. 地图方法替换 map.getZoom()：使用 map.getZoom()，行为相同。
11. 地图方法替换 map.panTo(latLng)：使用 map.panTo([lng, lat])，带平移动画。
12. 地图方法替换 map.fitBounds(bounds)：使用 map.fitBounds([[lng,lat],[lng,lat]])，边界格式不同。
13. 地图方法替换 map.setMapTypeId(type)：使用 map.setStyle(styleUrl)，方式完全不同。
14. 地图方法替换 map.getBounds()：使用 map.getBounds()，行为类似。
15. 地图事件绑定替换：将 google.maps.event.addListener(map, 'click', fn) 改为 map.on('click', fn)。
16. 地图事件属性替换：将 event.latLng 改为 event.lngLat。
17. 地图事件名替换：将 'center_changed' 改为 'move' 或 'moveend'。
18. 地图事件名替换：将 'zoom_changed' 改为 'zoom' 或 'zoomend'。
19. 地图事件名替换：将 'bounds_changed' 改为 'moveend'，没有直接等价事件。
20. 地图事件名替换：'mousemove' 保持一致。
21. 地图事件名替换：将 'mouseout' 改为 'mouseleave'。
22. 创建简单 Marker：使用 new mapboxgl.Marker().setLngLat([-122.4194, 37.7749]).setPopup(new mapboxgl.Popup().setText('San Francisco')).addTo(map)。
23. 移除简单 Marker：使用 marker.remove()，替代 Google 的 marker.setMap(null)。
24. 多标记的等价面向对象写法：使用 locations.map(loc => new mapboxgl.Marker().setLngLat([loc.lng, loc.lat]).addTo(map))。
25. 100+ 点多标记推荐数据驱动写法：添加 GeoJSON source 和 layer，使用 map.addSource('points', { type: 'geojson', data: { type: 'FeatureCollection', features: locations.map(loc => ({ type: 'Feature', geometry: { type: 'Point', coordinates: [loc.lng, loc.lat] }, properties: { name: loc.name } })) } })；再使用 map.addLayer({ id: 'points-layer', type: 'circle' 或 'symbol', source: 'points', paint: { 'circle-radius': 8, 'circle-color': '#ff0000' } })。
26. 利用性能优势：Google Maps 即使使用 Data Layer 也把 marker 渲染为 DOM 元素，500+ 标记会变慢；Mapbox 的 circle 和 symbol 图层由 WebGL 渲染，1,000-10,000+ 点更快。
27. 创建 InfoWindow/Popup 并附着到 Marker：使用 new mapboxgl.Marker().setLngLat([-122.4194, 37.7749]).setPopup(new mapboxgl.Popup().setHTML('<h3>Title</h3><p>Content</p>')).addTo(map)。
28. 在数据驱动图层点击时显示 Popup：使用 map.on('click', 'points-layer', e => { const coordinates = e.features[0].geometry.coordinates.slice(); const description = e.features[0].properties.description; new mapboxgl.Popup().setLngLat(coordinates).setHTML(description).addTo(map); })。
29. 迁移 Step 1 审计当前实现：列出所有使用的 Google Maps 功能，包括基础地图与标记、InfoWindow/Popup、多边形/折线、地理编码、路线、聚类、自定义样式、绘图工具、Street View、其他高级功能。
30. 迁移 Step 2 设置 Mapbox：替换 Google Maps script，引入 https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.js 和 https://api.mapbox.com/mapbox-gl-js/v3.18.1/mapbox-gl.css。
31. 迁移 Step 3 转换核心地图：将 new google.maps.Map() 替换为 new mapboxgl.Map()；修正坐标顺序 lat,lng 为 lng,lat；更新 zoom 和 center。
32. 迁移 Step 4 逐个转换功能：按复杂度优先，简单功能包括地图控件、基础标记；中等功能包括 Popup、多边形、线；复杂功能包括聚类、自定义样式、数据更新。
33. 迁移 Step 5 更新事件处理器：将 google.maps.event.addListener() 改为 map.on()；更新事件属性名 latLng 为 lngLat。
34. 迁移 Step 6 为 Mapbox 优化：将多个标记转换为数据驱动图层；使用内置聚类；利用 vector tiles 做自定义样式；使用 expressions 做动态样式。
35. 迁移 Step 7 充分测试：跨浏览器测试、移动端响应性、真实数据量下的性能、触摸/手势交互。
36. 处理坐标顺序常见问题：Google 使用 { lat: 37.7749, lng: -122.4194 }，Mapbox 使用 [-122.4194, 37.7749]，始终双重检查坐标顺序。
37. 处理事件属性常见问题：Google 中用 e.latLng.lat() 和 e.latLng.lng()，Mapbox 中用 e.lngLat.lat 和 e.lngLat.lng。
38. 处理时序问题：Google Maps 可立即创建 marker；Mapbox 需要等待 map.on('load', () => { map.addSource(...); map.addLayer(...); })。
39. 处理移除要素：Google 用 marker.setMap(null)；Mapbox 必须同时使用 map.removeLayer('layer-id') 和 map.removeSource('source-id')。
40. 更新数据时避免闪烁：不要 remove 再 re-add layer 和 source；使用 map.getSource('stores').setData(newGeoJSON) 原地更新；使用 map.setFilter('stores-layer', ['==', ['get', 'category'], 'coffee']) 在 GPU 侧过滤；避免 map.removeLayer、map.removeSource、map.addSource、map.addLayer 导致闪烁。
41. 按需加载参考文件：references/shapes-geocoding.md 处理多边形、折线、自定义图标、地理编码；references/directions-controls.md 处理路线/路由、控件；references/clustering-styling.md 处理聚类、样式/外观；references/data-performance.md 处理数据更新、性能、常见迁移模式（Store Locator、Drawing Tools、Heatmaps）；references/api-services.md 处理 API 服务对比、定价、插件、框架集成、测试、迁移清单；读取方式如 Load references/shapes-geocoding.md。
42. 结合其他技能：mapbox-web-integration-patterns 提供框架特定迁移；mapbox-web-performance-patterns 迁移后优化；mapbox-token-security 保护 Mapbox token；mapbox-geospatial-operations 使用地理空间工具；mapbox-search-patterns 迁移地理编码/搜索功能。
43. 查阅额外资源：Mapbox GL JS Documentation、Official Google Maps to Mapbox Migration Guide、Mapbox Examples、Style Specification。

适用边界 · 注意事项

• Street View 是关键功能：Mapbox 没有等价物。
• 与 Google Workspace/Places API 深度集成。
• 迁移成本大于收益：已高度优化、团队专长再培训成本过高、短期项目不值得迁移。