Mapbox GL JS 网页地图性能优化：消除加载瀑布…

在构建 Mapbox GL JS 地图应用时，按优先级优化初始化加载、包体积、渲染性能与内存管理。

适用场景

解决思路

1. 并行加载地图库与数据：先发起 fetch 数据请求（保存 Promise），再初始化 map，在 map.on('load') 中 await 该 Promise 并添加 source/layer，避免数据在地图初始化后才开始加载的串行瀑布。
2. 设置精确的初始视口：在 Map 构造函数中直接指定 center 和 zoom，避免地图先加载默认视图再平移/缩放到目标区域而浪费瓦片请求；用 map.once('idle') 判断初始视口完全渲染完成。
3. 延迟非关键功能：在 map.on('load') 中先添加关键图层，再用 requestIdleCallback（timeout 2000）延迟加载地形和自定义 3D 图层，用 setTimeout（3000）延迟初始化分析等非视觉功能；标准样式的 3D 建筑可通过 map.setConfigProperty('basemap', 'show3dObjects', false) 关闭。
4. 优化初始包体积：不要内联庞大的 style JSON（可能 500+ KB），改用 Mapbox 托管样式（如 mapbox://styles/mapbox/streets-v12）或外部样式文件（如 /styles/custom-style.json）按需加载。
5. 按数量选择标记方案：<100 个用 HTML Marker；100–10,000 个用 symbol 图层（GPU 加速）；10,000+ 用聚合（clustering）；100,000+ 用矢量瓦片加服务端聚合。
6. 用 GeoJSON symbol 图层替代大量 HTML Marker：将数据转为 FeatureCollection 添加为 source，添加 symbol 图层，并只注册一个 map.on('click', 'restaurants', ...) 监听器处理所有要素点击。
7. 高密度数据启用聚合：source 设置 cluster: true、clusterMaxZoom: 14、clusterRadius: 50，并分别添加聚合圆图层（circle）、聚合数量标签图层（symbol）和未聚合点图层（circle），用 filter 区分。
8. 对地图事件处理器做防抖/节流：如地理编码输入、moveend 等事件。
9. 优化 queryRenderedFeatures：使用 layers 过滤和 bounding box 限定查询范围。
10. 按数据量选择数据格式：小于 5 MB 用 GeoJSON，大于 20 MB 用矢量瓦片。
11. 在 SPA 或页面销毁时始终调用 map.remove() 清理。
12. 注册 map.on('error', …) 或提供可见的错误 UI，避免样式/瓦片/token 失败被静默忽略。
13. 复用 Popup 实例，不要每次交互都新建。
14. 用 feature state 实现 hover/选中效果，而不是动态增删图层。
15. 聚合演示要生成足够多的点（数千个）来真正压测聚合逻辑，而不是几百个。
16. 合并多个图层，使用数据驱动样式（data-driven styling）。
17. 添加移动端专属优化：使用 circle 图层、禁用旋转。
18. 为图层设置 minzoom/maxzoom，避免在无关缩放级别渲染。
19. 除非必要，不要开启 preserveDrawingBuffer 或 antialias。
20. 测量性能：用 console.time/console.timeEnd 包裹 map.on('load') 测初始加载时间，用 map.isStyleLoaded() 确认样式加载完成；监听 map.on('render') 统计 FPS；用 Chrome DevTools Performance → Memory 检查内存。
21. 对照目标指标：3G 下 Time to Interactive < 2 秒、平移缩放 60 FPS、内存增长 < 10 MB/小时、初始包 < 500 KB（地图懒加载）。

适用边界 · 注意事项

• 不使用 Mapbox GL JS 或不需要网页地图渲染的场景。
• 项目规模极小、标记数量远低于 100 且无性能压力时，无需引入聚合、矢量瓦片等复杂方案。
• 无法使用 Mapbox 托管样式或访问令牌、必须完全离线自托管样式的场景，部分样式优化建议不适用。