Mapbox Google Maps Migration Skill

Comprehensive guidance for migrating from Google Maps Platform to Mapbox GL JS. Provides API equivalents, pattern translations, and strategies for successful migration.

Core Philosophy Differences

Google Maps: Imperative & Object-Oriented

- Create objects (Marker, Polygon, etc.)
Add to map with INLINECODE0
Update properties with setters
Heavy reliance on object instances

Mapbox GL JS: Declarative & Data-Driven

- Add data sources
Define layers (visual representation)
Style with JSON
Update data, not object properties

Key Insight: Mapbox treats everything as data + styling, not individual objects.

Map Initialization

Google Maps

CODEBLOCK0

Mapbox GL JS

CODEBLOCK1

Key Differences:

- Coordinate order: Google uses {lat, lng}, Mapbox uses INLINECODE2
Authentication: Google uses API key in script tag, Mapbox uses access token in code
Styling: Google uses map types, Mapbox uses full style URLs

API Equivalents Reference

Map Methods

Google Maps	Mapbox GL JS	Notes
INLINECODE3	INLINECODE4	Coordinate order reversed
INLINECODE5

Map Events

Google Maps	Mapbox GL JS	Notes
INLINECODE19	INLINECODE20	Simpler syntax
INLINECODE21

Markers and Points

Simple Marker

Google Maps:

CODEBLOCK2

Mapbox GL JS:

CODEBLOCK3

Multiple Markers

Google Maps:

CODEBLOCK4

Mapbox GL JS (Equivalent Approach):

CODEBLOCK5

Mapbox GL JS (Data-Driven Approach - Recommended for 100+ points):

CODEBLOCK6

Performance Advantage: Google Maps renders all markers as DOM elements (even when using the Data Layer), which becomes slow with 500+ markers. Mapbox's circle and symbol layers are rendered by WebGL, making them much faster for large datasets (1,000-10,000+ points). This is a significant advantage when building applications with many points.

Info Windows / Popups

Google Maps

CODEBLOCK7

Mapbox GL JS

CODEBLOCK8

Migration Strategy

Step 1: Audit Current Implementation

Identify all Google Maps features you use:

- [ ] Basic map with markers
[ ] Info windows/popups
[ ] Polygons/polylines
[ ] Geocoding
[ ] Directions
[ ] Clustering
[ ] Custom styling
[ ] Drawing tools
[ ] Street View (no Mapbox equivalent)
[ ] Other advanced features

Step 2: Set Up Mapbox

CODEBLOCK9

Step 3: Convert Core Map

Start with basic map initialization:

1. Replace new google.maps.Map() with INLINECODE36
Fix coordinate order (lat,lng -> lng,lat)
Update zoom/center

Step 4: Convert Features One by One

Prioritize by complexity:

1. Easy: Map controls, basic markers
Medium: Popups, polygons, lines
Complex: Clustering, custom styling, data updates

Step 5: Update Event Handlers

Change event syntax:

- google.maps.event.addListener() -> INLINECODE38
Update event property names (latLng -> lngLat)

Step 6: Optimize for Mapbox

Take advantage of Mapbox features:

- Convert multiple markers to data-driven layers
Use clustering (built-in)
Leverage vector tiles for custom styling
Use expressions for dynamic styling

Step 7: Test Thoroughly

- Cross-browser testing
Mobile responsiveness
Performance with real data volumes
Touch/gesture interactions

Gotchas and Common Issues

Coordinate Order

CODEBLOCK10

Always double-check coordinate order!

Event Properties

CODEBLOCK11

Timing Issues

CODEBLOCK12

Removing Features

CODEBLOCK13

Updating Data Without Flash

Never remove and re-add layers to update data — this reinitializes WebGL resources and causes a visible flash. Instead:

CODEBLOCK14

When NOT to Migrate

Consider staying with Google Maps if:

- Street View is critical - Mapbox doesn't have equivalent
Tight Google Workspace integration - Places API deeply integrated
Already heavily optimized - Migration cost > benefits
Team expertise - Retraining costs too high
Short-term project - Not worth migration effort

Quick Reference: Side-by-Side Comparison

CODEBLOCK15

Remember: lng, lat order in Mapbox!

Additional Resources

Integration with Other Skills

Works with:

- mapbox-web-integration-patterns: Framework-specific migration guidance
mapbox-web-performance-patterns: Optimize after migration
mapbox-token-security: Secure your Mapbox tokens properly
mapbox-geospatial-operations: Use Mapbox's geospatial tools effectively
mapbox-search-patterns: Migrate geocoding/search functionality

Reference Files

The following reference files contain detailed migration guides for specific topics. Load them when working on those areas:

- references/shapes-geocoding.md — Polygons, Polylines, Custom Icons, Geocoding
references/directions-controls.md — Directions/Routing, Controls
references/clustering-styling.md — Clustering, Styling/Appearance
references/data-performance.md — Data Updates, Performance, Common Migration Patterns (Store Locator, Drawing Tools, Heatmaps)
references/api-services.md — API Services Comparison, Pricing, Plugins, Framework Integration, Testing, Migration Checklist

To load a reference, read the file relative to this skill directory, e.g.:

CODEBLOCK16

Mapbox Google Maps 迁移技能

从 Google Maps Platform 迁移到 Mapbox GL JS 的全面指南。提供 API 等效项、模式转换和成功迁移策略。

核心理念差异

Google Maps：命令式与面向对象

- 创建对象（标记、多边形等）
使用 .setMap(map) 添加到地图
使用 setter 更新属性
高度依赖对象实例

Mapbox GL JS：声明式与数据驱动

- 添加数据源
定义图层（视觉表现）
使用 JSON 设置样式
更新数据，而非对象属性

关键洞察： Mapbox 将所有内容视为数据 + 样式，而非独立对象。

地图初始化

Google Maps

javascript
const map = new google.maps.Map(document.getElementById(map), {
center: { lat: 37.7749, lng: -122.4194 },
zoom: 12,
mapTypeId: roadmap // 或 satellite, hybrid, terrain
});

Mapbox GL JS

javascript
mapboxgl.accessToken = YOURMAPBOXTOKEN;
const map = new mapboxgl.Map({
container: map,
style: mapbox://styles/mapbox/streets-v12, // 或 satellite-v9, outdoors-v12
center: [-122.4194, 37.7749], // [lng, lat] - 注意顺序！
zoom: 12
});

关键差异：

- 坐标顺序： Google 使用 {lat, lng}，Mapbox 使用 [lng, lat]
认证方式： Google 在 script 标签中使用 API 密钥，Mapbox 在代码中使用访问令牌
样式设置： Google 使用地图类型，Mapbox 使用完整样式 URL

API 等效项参考

地图方法

Google Maps	Mapbox GL JS	备注
map.setCenter(latLng)	map.setCenter([lng, lat])	坐标顺序反转
map.getCenter()

地图事件

Google Maps	Mapbox GL JS	备注
google.maps.event.addListener(map, click, fn)	map.on(click, fn)	更简洁的语法
event.latLng

标记和点

简单标记

Google Maps：

javascript
const marker = new google.maps.Marker({
position: { lat: 37.7749, lng: -122.4194 },
map: map,
title: San Francisco,
icon: custom-icon.png
});

// 移除标记
marker.setMap(null);

Mapbox GL JS：

javascript
// 创建标记
const marker = new mapboxgl.Marker()
.setLngLat([-122.4194, 37.7749])
.setPopup(new mapboxgl.Popup().setText(San Francisco))
.addTo(map);

// 移除标记
marker.remove();

多个标记

Google Maps：

javascript
const markers = locations.map(
(loc) =>
new google.maps.Marker({
position: { lat: loc.lat, lng: loc.lng },
map: map
})
);

Mapbox GL JS（等效方法）：

javascript
// 相同的面向对象方法
const markers = locations.map((loc) => new mapboxgl.Marker().setLngLat([loc.lng, loc.lat]).addTo(map));

Mapbox GL JS（数据驱动方法 - 推荐用于 100+ 个点）：

javascript
// 添加为 GeoJSON 源 + 图层（使用 WebGL，而非 DOM）
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
}
});

性能优势： Google Maps 将所有标记渲染为 DOM 元素（即使使用数据层），当标记超过 500 个时会变慢。Mapbox 的圆形和符号图层由 WebGL 渲染，因此对于大数据集（1,000-10,000+ 个点）速度更快。这在构建具有大量点的应用程序时是一个显著优势。

信息窗口 / 弹出窗口

Google Maps

javascript
const infowindow = new google.maps.InfoWindow({
content:

Title

Content

});

marker.addListener(click, () => {
infowindow.open(map, marker);
});

Mapbox GL JS

javascript
// 选项 1：附加到标记
const marker = new mapboxgl.Marker()
.setLngLat([-122.4194, 37.7749])
.setPopup(new mapboxgl.Popup().setHTML(

Title

Content

))
.addTo(map);

// 选项 2：点击图层时（用于数据驱动标记）
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);
});

迁移策略

第 1 步：审计当前实现

识别您使用的所有 Google Maps 功能：

- [ ] 带标记的基本地图
[ ] 信息窗口/弹出窗口
[ ] 多边形/折线
[ ] 地理编码
[ ] 路线导航
[ ] 聚类
[ ] 自定义样式
[ ] 绘图工具
[ ] 街景（无 Mapbox 等效项）
[ ] 其他高级功能

第 2 步：设置 Mapbox

html

第 3 步：转换核心地图

从基本地图初始化开始：

1. 将 new google.maps.Map() 替换为 new mapboxgl.Map()
修正坐标顺序（lat,lng -> lng,lat）
更新缩放/中心点

第 4 步：逐个转换功能

按复杂度排序：

1. 简单： 地图控件、基本标记
中等： 弹出窗口、多边形、线条
复杂： 聚类、自定义样式、数据更新

第 5 步：更新事件处理器

更改事件语法：

- google.maps.event.addListener() -> map.on()
更新事件属性名称（

mapbox-google-maps-migrationMapbox迁移指南