Mapbox Performance Patterns Skill

This skill provides performance optimization guidance for building fast, efficient Mapbox applications. Patterns are prioritized by impact on user experience, starting with the most critical improvements.

Performance philosophy: These aren't micro-optimizations. They show up as waiting time, jank, and repeat costs that hit every user session.

Priority Levels

Performance issues are prioritized by their impact on user experience:

- 🔴 Critical (Fix First): Directly causes slow initial load or visible jank
🟡 High Impact: Noticeable delays or increased resource usage
🟢 Optimization: Incremental improvements for polish

🔴 Critical: Eliminate Initialization Waterfalls

Problem: Sequential loading creates cascading delays where each resource waits for the previous one.

Note: Modern bundlers (Vite, Webpack, etc.) and ESM dynamic imports automatically handle code splitting and library loading. The primary waterfall to eliminate is data loading - fetching map data sequentially instead of in parallel with map initialization.

Anti-Pattern: Sequential Data Loading

CODEBLOCK0

Timeline: Map init (0.5s) → Data fetch (1s) = 1.5s total

Solution: Parallel Data Loading

CODEBLOCK1

Timeline: Max(map init, data fetch) = ~1s total

Set Precise Initial Viewport

CODEBLOCK2

If you know the exact area users will see first, setting center and zoom upfront avoids the map starting at a default view and then panning/zooming to the target, which wastes tile fetches.

Defer Non-Critical Features

CODEBLOCK3

Impact: Significant reduction in time-to-interactive, especially when deferring terrain and 3D layers

🔴 Critical: Optimize Initial Bundle Size

Problem: Large bundles delay time-to-interactive on slow networks.

Note: Modern bundlers (Vite, Webpack, etc.) automatically handle code splitting for framework-based applications. The guidance below is most relevant for optimizing what gets bundled and when.

Style JSON Bundle Impact

CODEBLOCK4

Impact: Reduces initial bundle by 30-50% when moving from inlined to hosted styles

🟡 High Impact: Optimize Marker Count

Problem: Too many markers causes slow rendering and interaction lag.

Performance Thresholds

- < 100 markers: HTML markers OK (Marker class)
100-10,000 markers: Use symbol layers (GPU-accelerated)
10,000+ markers: Clustering recommended
100,000+ markers: Vector tiles with server-side clustering

Anti-Pattern: Thousands of HTML Markers

CODEBLOCK5

Result: 5,000 DOM elements, slow interactions, high memory

Solution: Use Symbol Layers (GeoJSON)

CODEBLOCK6

Performance: 10,000 features render in <100ms

Solution: Clustering for High Density

CODEBLOCK7

Impact: 50,000 markers at 60 FPS with smooth interaction

Summary: Performance Checklist

When building a Mapbox application, verify these optimizations in order:

🔴 Critical (Do First)

- [ ] Load map library and data in parallel (eliminate waterfalls)
[ ] Use dynamic imports for map code (reduce initial bundle)
[ ] Defer non-critical features (terrain, custom 3D layers, analytics)
[ ] Use symbol layers for > 100 markers (not HTML markers)
[ ] Implement viewport-based data loading for large datasets

🟡 High Impact

- [ ] Debounce/throttle map event handlers
[ ] Optimize queryRenderedFeatures with layers filter and bounding box
[ ] Use GeoJSON for < 5 MB, vector tiles for > 20 MB
[ ] Always call map.remove() on cleanup in SPAs
[ ] Reuse popup instances (don't create on every interaction)
[ ] Use feature state instead of dynamic layers for hover/selection

🟢 Optimization

- [ ] Consolidate multiple layers with data-driven styling
[ ] Add mobile-specific optimizations (circle layers, disabled rotation)
[ ] Set minzoom/maxzoom on layers to avoid rendering at irrelevant zoom levels
[ ] Avoid enabling preserveDrawingBuffer or antialias unless needed

Measurement

CODEBLOCK8

Target metrics:

- Time to Interactive: < 2 seconds on 3G
Frame Rate: 60 FPS during pan/zoom
Memory Growth: < 10 MB per hour of usage
Bundle Size: < 500 KB initial (map lazy-loaded)

Reference Files

For detailed patterns on specific topics, load the corresponding reference file:

- references/data-loading.md — GeoJSON vs Vector Tiles decision matrix, viewport-based loading, progressive loading, vector tiles for large datasets
references/interactions.md — Debounce/throttle events, optimize feature queries, batch DOM updates
references/memory.md — Map cleanup patterns, popup/marker reuse, feature state vs dynamic layers
references/mobile.md — Device detection, mobile-optimized layers, touch interaction, constructor options
references/layers-styles.md — Consolidate layers with data-driven styling, simplify expressions, zoom-based visibility

Mapbox 性能模式技能

本技能为构建快速、高效的Mapbox应用提供性能优化指导。模式按对用户体验的影响程度排序，从最关键改进开始。

性能理念： 这些并非微优化。它们会表现为等待时间、卡顿和重复开销，影响每一次用户会话。

优先级级别

性能问题按对用户体验的影响程度排序：

- 🔴 关键（优先修复）：直接导致初始加载缓慢或明显卡顿
🟡 高影响：明显延迟或资源使用增加
🟢 优化：渐进式改进以提升品质

🔴 关键：消除初始化瀑布流

问题： 顺序加载会造成级联延迟，每个资源都需等待前一个资源完成。

注意： 现代打包工具（Vite、Webpack等）和ESM动态导入会自动处理代码分割和库加载。需要消除的主要瀑布流是数据加载——顺序获取地图数据而非与地图初始化并行加载。

反模式：顺序数据加载

javascript
// ❌ 错误：数据在地图初始化后加载
async function initMap() {
const map = new mapboxgl.Map({
container: map,
accessToken: MAPBOX_TOKEN,
style: mapbox://styles/mapbox/streets-v12
});

// 等待地图加载完成，然后获取数据
map.on(load, async () => {
const data = await fetch(/api/data); // 瀑布流！
map.addSource(data, { type: geojson, data: await data.json() });
});
}

时间线： 地图初始化（0.5秒）→ 数据获取（1秒）= 总计1.5秒

解决方案：并行数据加载

javascript
// ✅ 正确：立即开始数据获取
async function initMap() {
// 立即开始数据获取（不等待地图）
const dataPromise = fetch(/api/data).then((r) => r.json());

const map = new mapboxgl.Map({
container: map,
accessToken: MAPBOX_TOKEN,
style: mapbox://styles/mapbox/streets-v12
});

// 地图加载完成时数据已就绪
map.on(load, async () => {
const data = await dataPromise;
map.addSource(data, { type: geojson, data });
map.addLayer({
id: data-layer,
type: circle,
source: data
});
});
}

时间线： 最大值（地图初始化，数据获取）= 总计约1秒

设置精确的初始视口

javascript
// ✅ 设置精确的中心点/缩放级别，使地图立即获取正确的瓦片
const map = new mapboxgl.Map({
container: map,
style: mapbox://styles/mapbox/streets-v12,
center: [-122.4194, 37.7749],
zoom: 13
});

// 使用idle事件了解初始视口何时完全渲染
//（所有瓦片、精灵和其他资源已加载；无进行中的过渡）
map.once(idle, () => {
console.log(初始视口已完全渲染);
});

如果知道用户首先看到的精确区域，预先设置center和zoom可避免地图从默认视口开始然后平移/缩放到目标位置，从而浪费瓦片获取。

延迟非关键功能

javascript
// ✅ 先加载关键功能，延迟其他功能
const map = new mapboxgl.Map({
/ 配置 /
});

map.on(load, () => {
// 1. 立即添加关键图层
addCriticalLayers(map);

// 2. 延迟次要功能
// 注意：标准样式的3D建筑可通过配置切换：
// map.setConfigProperty(basemap, show3dObjects, false);
requestIdleCallback(
() => {
addTerrain(map);
addCustom3DLayers(map); // 适用于带有自定义fill-extrusion图层的经典样式
},
{ timeout: 2000 }
);

// 3. 延迟分析和非视觉功能
setTimeout(() => {
initializeAnalytics(map);
}, 3000);
});

影响： 显著减少交互可用时间，尤其是在延迟地形和3D图层时

🔴 关键：优化初始包大小

问题： 大包在慢速网络上延迟交互可用时间。

注意： 现代打包工具（Vite、Webpack等）会自动处理基于框架应用的代码分割。以下指南最适用于优化打包内容和时机。

样式JSON包影响

javascript
// ❌ 错误：内联大型样式JSON（可能超过500KB）
const style = {
version: 8,
sources: {
/ 数百行 /
},
layers: [
/ 数百个图层 /
]
};

// ✅ 正确：引用Mapbox托管的样式
const map = new mapboxgl.Map({
style: mapbox://styles/mapbox/streets-v12 // 按需获取
});

// ✅ 或者：将大型自定义样式存储在外部
const map = new mapboxgl.Map({
style: /styles/custom-style.json // 单独加载
});

影响： 从内联样式迁移到托管样式时，初始包减少30-50%

🟡 高影响：优化标记数量

问题： 标记过多导致渲染缓慢和交互延迟。

性能阈值

- < 100个标记：HTML标记可用（Marker类）
100-10,000个标记：使用符号图层（GPU加速）
10,000+个标记：建议聚类
100,000+个标记：使用服务端聚类的矢量瓦片

反模式：数千个HTML标记

javascript
// ❌ 错误：5,000个HTML标记 = 5秒以上渲染，平移/缩放卡顿
restaurants.forEach((restaurant) => {
const marker = new mapboxgl.Marker()
.setLngLat([restaurant.lng, restaurant.lat])
.setPopup(new mapboxgl.Popup().setHTML(restaurant.name))
.addTo(map);
});

结果： 5,000个DOM元素，交互缓慢，高内存占用

解决方案：使用符号图层（GeoJSON）

javascript
// ✅ 正确：GPU加速渲染，10,000+个要素流畅运行
map.addSource(restaurants, {
type: geojson,
data: {
type: FeatureCollection,
features: restaurants.map((r) => ({
type: Feature,
geometry: { type: Point, coordinates: [r.lng, r.lat] },
properties: { name: r.name, type: r.type }
}))
}
});

map.addLayer({
id: restaurants,
type: symbol,
source: restaurants,
layout: {
icon-image: restaurant,
icon-size: 0.8,
text-field: [get, name],
text-size: 12,
text-offset: [0, 1.5],
text-anchor: top
}
});

// 点击处理程序（一个监听器处理所有要素）
map.on(click, restaurants, (e) => {
const feature = e.features[0];
new mapboxgl.Popup().setLngLat(feature.geometry.coordinates).setHTML(feature.properties.name).addTo(map);
});

性能： 10,000个要素在<100毫秒内渲染

解决方案：高密度聚类

javascript
// ✅ 正确：50,000个标记 → 低缩放级别约500个聚类
map.addSource(restaurants, {
type: geojson,
data: restaurantsGeoJSON,
cluster: true,
clusterMaxZoom: 14, // 在缩放级别15停止聚类
clusterRadius: 50 // 相对于瓦片尺寸的半径（512 = 完整瓦片宽度）
});

// 聚类圆形图层
map.addLayer({
id: clusters,
type: circle,
source: restaurants,
filter: [has, point_count],
paint: {
circle-color: [step, [get, point_count], #51bbd6, 100, #f1f075, 750, #f28cb1],
circle-radius: [step, [get, point_count], 20, 100, 30, 750, 40]
}
});

// 聚类计数标签
map.addLayer({
id: cluster-count,
type: symbol,
source: restaurants,
filter: [has, point_count],
layout: {
text-field: {pointcountabbreviated},
text-size: 12
}
});

mapbox-web-performance-patternsMapbox性能优化

mapbox-web-performance-patterns

Mapbox Performance Patterns Skill

Priority Levels

🔴 Critical: Eliminate Initialization Waterfalls

Anti-Pattern: Sequential Data Loading

Solution: Parallel Data Loading

Set Precise Initial Viewport

Defer Non-Critical Features

🔴 Critical: Optimize Initial Bundle Size

Style JSON Bundle Impact

🟡 High Impact: Optimize Marker Count

Performance Thresholds

Anti-Pattern: Thousands of HTML Markers

Solution: Use Symbol Layers (GeoJSON)

Solution: Clustering for High Density

Summary: Performance Checklist

🔴 Critical (Do First)

🟡 High Impact

🟢 Optimization

Measurement

Reference Files

Mapbox 性能模式技能

优先级级别

🔴 关键：消除初始化瀑布流

反模式：顺序数据加载

解决方案：并行数据加载

设置精确的初始视口

延迟非关键功能

🔴 关键：优化初始包大小

样式JSON包影响

🟡 高影响：优化标记数量

性能阈值

反模式：数千个HTML标记

解决方案：使用符号图层（GeoJSON）

解决方案：高密度聚类

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement