Mapbox Web集成模式：React/Vue/Angular/Svelte最佳实践与GL JS v3教程

mapbox-web-integration-patterns by mapbox/mapbox-agent-skills

413 周安装量

35 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mapbox/mapbox-agent-skills --skill mapbox-web-integration-patterns

数据可视化 JavaScript 框架 API

🇨🇳中文介绍

Mapbox 集成模式技能

本技能提供了使用 React、Vue、Svelte、Angular 和原生 JavaScript 将 Mapbox GL JS 集成到 Web 应用程序中的官方模式。这些模式基于 Mapbox 的 create-web-app 脚手架工具，代表了可用于生产环境的最佳实践。

版本要求

Mapbox GL JS

推荐版本： v3.x（最新版）

最低版本： v3.0.0
为什么选择 v3.x： 现代化的 API、改进的性能、积极开发中
v2.x： 旧版；不再积极开发（见下方迁移说明）

通过 npm 安装（推荐用于生产环境）：

npm install mapbox-gl@^3.0.0    # 安装最新的 v3.x 版本

CDN（仅用于原型开发）：

<!-- 将 VERSION 替换为 https://docs.mapbox.com/mapbox-gl-js/ 上的最新 v3.x 版本 -->
<script src="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.css" rel="stylesheet" />

⚠️ 生产环境应用应使用 npm，而非 CDN - 以确保版本一致性和离线构建。

框架要求

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

原生 JavaScript（使用 Vite）

模式：使用初始化函数的模块导入

import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
import './main.css';

// 设置访问令牌
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

let map;

/**
 * 初始化地图
 */
function initMap() {
  map = new mapboxgl.Map({
    container: 'map-container',
    center: [-71.05953, 42.3629],
    zoom: 13
  });

  map.on('load', () => {
    console.log('Map is loaded');
  });
}

// 在脚本运行时初始化
initMap();

<div id="map-container" style="height: 100vh;"></div>

将地图存储在模块作用域变量中
立即或在 DOMContentLoaded 时初始化
监听 'load' 事件以执行初始化后的操作

原生 JavaScript（无打包工具 - CDN）

模式：带有内联初始化的脚本标签

⚠️ 注意： 此模式仅用于原型开发。生产环境应用应使用 npm/打包工具进行版本控制和离线构建。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Mapbox GL JS - No Bundler</title>

    <!-- Mapbox GL JS CSS -->
    <!-- 将 3.x.x 替换为 https://docs.mapbox.com/mapbox-gl-js/ 上的最新版本 -->
    <link href="https://api.mapbox.com/mapbox-gl-js/v3.x.x/mapbox-gl.css" rel="stylesheet" />

    <style>
      body {
        position: absolute;
        top: 0;
        right: 0;
        bottom: 0;
        left: 0;
        margin: 0;
        padding: 0;
      }
      #map-container {
        height: 100%;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map-container"></div>

    <!-- Mapbox GL JS -->
    <!-- 将 3.x.x 替换为 https://docs.mapbox.com/mapbox-gl-js/ 上的最新版本 -->
    <script src="https://api.mapbox.com/mapbox-gl-js/v3.x.x/mapbox-gl.js"></script>

    <script>
      // 设置访问令牌
      mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN_HERE';

      let map;

      function initMap() {
        map = new mapboxgl.Map({
          container: 'map-container',
          center: [-71.05953, 42.3629],
          zoom: 13
        });

        map.on('load', () => {
          console.log('Map is loaded');
        });
      }

      // 在页面加载时初始化
      initMap();
    </script>
  </body>
</html>

⚠️ 仅用于原型开发 - 不推荐用于生产环境
将 3.x.x 替换为特定版本（例如 3.7.0），来自 Mapbox 文档
不要使用 /latest/ - 始终固定到特定版本以确保一致性
在脚本加载后初始化（body 底部）
对于生产环境：请使用 npm + 打包工具

为什么生产环境不要使用 CDN？

❌ 网络依赖（离线时失效）
❌ 没有版本锁定（CDN 可能更改）
❌ 速度较慢（没有打包工具优化）
❌ 无法 tree-shaking
✅ 生产环境使用 npm：npm install mapbox-gl@^3.0.0

Web 组件（框架无关）

Web 组件是 W3C 标准，用于创建可重用的自定义元素，可在任何框架或无框架环境中工作。

何时使用 Web 组件：

✅ 原生 JavaScript 应用 - 没有框架？Web 组件是一个很好的选择
✅ 设计系统 - 构建跨多个框架使用的组件库
✅ 微前端 - 应用在不同部分使用不同的框架
✅ 多框架组织 - 使用 React、Vue、Svelte 等框架的团队需要共享组件
✅ 框架迁移 - 逐步从一个框架迁移到另一个框架
✅ 长期稳定性 - W3C 标准，无框架锁定

实际示例： 一家拥有 React（主应用）、Vue（管理面板）和 Svelte（营销网站）的公司可以构建一个随处可用的 <mapbox-map> 组件。

何时改用特定框架模式：

🔧 已经在使用某个框架 - 如果你正在使用 React 构建，请使用 React 模式（更简单，集成更好）
🔧 需要框架特性 - 与 React hooks、Vue Composition API、状态管理、路由的深度集成
🔧 团队熟悉度 - 团队精通框架模式

💡 提示： 如果你正在使用 React、Vue、Svelte 或 Angular，请从上面的特定框架模式开始。它们更简单且集成更好。当你需要跨框架兼容性或正在构建原生 JavaScript 应用时，请使用 Web 组件。

模式：具有生命周期回调的标准自定义元素

Web 组件提供了一种使用 W3C Web 组件标准封装 Mapbox 地图的框架无关方式。

基础 Web 组件：

import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

class MapboxMap extends HTMLElement {
  constructor() {
    super();
    this.map = null;
  }

  connectedCallback() {
    // 从属性获取配置
    const token = this.getAttribute('access-token') || import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
    const mapStyle = this.getAttribute('map-style') || 'mapbox://styles/mapbox/standard';
    const center = this.getAttribute('center')?.split(',').map(Number) || [-71.05953, 42.3629];
    const zoom = parseFloat(this.getAttribute('zoom')) || 13;

    // 初始化地图
    mapboxgl.accessToken = token;

    this.map = new mapboxgl.Map({
      container: this,
      style: mapStyle,
      center: center,
      zoom: zoom
    });

    // 地图加载时派发自定义事件
    this.map.on('load', () => {
      this.dispatchEvent(
        new CustomEvent('mapload', {
          detail: { map: this.map }
        })
      );
    });
  }

  // 关键：在元素被移除时清理
  disconnectedCallback() {
    if (this.map) {
      this.map.remove();
      this.map = null;
    }
  }

  // 向 JavaScript 暴露地图实例
  getMap() {
    return this.map;
  }
}

// 注册自定义元素
customElements.define('mapbox-map', MapboxMap);

在 HTML 中使用：

<!-- 基础用法 -->
<mapbox-map
  access-token="pk.YOUR_TOKEN"
  map-style="mapbox://styles/mapbox/dark-v11"
  center="-122.4194,37.7749"
  zoom="12"
></mapbox-map>

<style>
  mapbox-map {
    display: block;
    height: 100vh;
    width: 100%;
  }
</style>

在 React 中使用：

import './mapbox-map-component'; // 导入以注册元素

function App() {
  const mapRef = useRef(null);

  useEffect(() => {
    const handleMapLoad = (e) => {
      const map = e.detail.map;
      // 添加标记、图层等
      new mapboxgl.Marker().setLngLat([-122.4194, 37.7749]).addTo(map);
    };

    mapRef.current?.addEventListener('mapload', handleMapLoad);

    return () => {
      mapRef.current?.removeEventListener('mapload', handleMapLoad);
    };
  }, []);

  return (
    <mapbox-map
      ref={mapRef}
      access-token={import.meta.env.VITE_MAPBOX_ACCESS_TOKEN}
      map-style="mapbox://styles/mapbox/standard"
      center="-122.4194,37.7749"
      zoom="12"
    />
  );
}

在 Vue 中使用：

<template>
  <mapbox-map
    ref="map"
    :access-token="token"
    map-style="mapbox://styles/mapbox/streets-v12"
    center="-71.05953,42.3629"
    zoom="13"
    @mapload="handleMapLoad"
  />
</template>

<script>
import './mapbox-map-component';

export default {
  data() {
    return {
      token: import.meta.env.VITE_MAPBOX_ACCESS_TOKEN
    };
  },
  methods: {
    handleMapLoad(event) {
      const map = event.detail.map;
      // 与地图交互
    }
  }
};
</script>

在 Svelte 中使用：

<script>
  import './mapbox-map-component';

  let mapElement;

  function handleMapLoad(event) {
    const map = event.detail.map;
    // 与地图交互
  }
</script>

<mapbox-map
  bind:this={mapElement}
  access-token={import.meta.env.VITE_MAPBOX_ACCESS_TOKEN}
  map-style="mapbox://styles/mapbox/standard"
  center="-71.05953,42.3629"
  zoom="13"
  on:mapload={handleMapLoad}
/>

高级：响应式属性模式：

class MapboxMapReactive extends HTMLElement {
  static get observedAttributes() {
    return ['center', 'zoom', 'map-style'];
  }

  constructor() {
    super();
    this.map = null;
  }

  connectedCallback() {
    mapboxgl.accessToken = this.getAttribute('access-token');

    this.map = new mapboxgl.Map({
      container: this,
      style: this.getAttribute('map-style') || 'mapbox://styles/mapbox/standard',
      center: this.getAttribute('center')?.split(',').map(Number) || [0, 0],
      zoom: parseFloat(this.getAttribute('zoom')) || 9
    });
  }

  disconnectedCallback() {
    if (this.map) {
      this.map.remove();
      this.map = null;
    }
  }

  // 响应属性变化
  attributeChangedCallback(name, oldValue, newValue) {
    if (!this.map || oldValue === newValue) return;

    switch (name) {
      case 'center':
        const center = newValue.split(',').map(Number);
        this.map.setCenter(center);
        break;
      case 'zoom':
        this.map.setZoom(parseFloat(newValue));
        break;
      case 'map-style':
        this.map.setStyle(newValue);
        break;
    }
  }
}

customElements.define('mapbox-map-reactive', MapboxMapReactive);

关键实现要点：

使用 connectedCallback() 进行初始化（相当于 mount/ngOnInit）
始终实现 disconnectedCallback() 来调用 map.remove()（防止内存泄漏）
从 HTML 属性读取配置
为地图交互派发自定义事件（mapload 等）
使用 observedAttributes + attributeChangedCallback 实现响应式更新
无需修改即可在任何框架中工作

环境变量（推荐）

不同的框架对客户端环境变量使用不同的前缀：

框架/打包工具	环境变量	访问模式
Vite	`VITE_MAPBOX_ACCESS_TOKEN`	`import.meta.env.VITE_MAPBOX_ACCESS_TOKEN`
Next.js	`NEXT_PUBLIC_MAPBOX_TOKEN`	`process.env.NEXT_PUBLIC_MAPBOX_TOKEN`
Create React App	`REACT_APP_MAPBOX_TOKEN`	`process.env.REACT_APP_MAPBOX_TOKEN`
Angular	`environment.mapboxAccessToken`	环境文件（`environment.ts`）

Vite .env 文件：

VITE_MAPBOX_ACCESS_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE

Next.js .env.local 文件：

NEXT_PUBLIC_MAPBOX_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE

✅ 始终使用环境变量存储令牌
✅ 切勿将 .env 文件提交到版本控制
✅ 客户端应用使用公共令牌（pk.*）
✅ 将 .env 添加到 .gitignore
✅ 为团队提供 .env.example 模板

.env
.env.local
.env.*.local

VITE_MAPBOX_ACCESS_TOKEN=your_token_here

Mapbox Search JS 集成

搜索框组件模式

npm install @mapbox/search-js-react      # React
npm install @mapbox/search-js-web        # 原生/Vue/Svelte

注意： 两个包都包含 @mapbox/search-js-core 作为依赖项。只有在构建自定义搜索 UI 时才需要直接安装 -core。

React 搜索模式：

import { SearchBox } from '@mapbox/search-js-react';

// 在组件内部：
<SearchBox
  accessToken={accessToken}
  map={mapRef.current} // 传递地图实例
  mapboxgl={mapboxgl} // 传递 mapboxgl 库
  value={inputValue}
  onChange={(value) => setInputValue(value)}
  proximity={centerCoordinates} // 根据中心位置偏好搜索结果
  marker // 为选中的结果显示标记
/>;

关键配置选项：

accessToken：你的 Mapbox 公共令牌
map：地图实例（必须先初始化）
mapboxgl：mapboxgl 库引用
proximity：[lng, lat] 用于地理偏好搜索结果
marker：布尔值，显示/隐藏结果标记
placeholder：搜索框占位符文本

绝对定位（覆盖层）：

<div
  style={{
    position: 'absolute',
    top: 10,
    right: 10,
    zIndex: 10,
    width: 300
  }}
>
  <SearchBox {...props} />
</div>

右上角：top: 10px, right: 10px
左上角：top: 10px, left: 10px
左下角：bottom: 10px, left: 10px

常见错误及避免方法

❌ 错误 1：忘记调用 map.remove()

// 错误 - 内存泄漏！
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  // 没有清理函数
}, [])



// 正确 - 正确清理
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  return () => map.remove()  // ✅ 清理
}, [])

原因： 每个 Map 实例都会创建 WebGL 上下文、事件监听器和 DOM 节点。如果不清理，这些会累积并导致内存泄漏。

❌ 错误 2：在渲染函数中初始化地图

// 错误 - React 中的无限循环！
function MapComponent() {
  const map = new mapboxgl.Map({ ... })  // 每次渲染都运行
  return <div />
}



// 正确 - 在 effect 中初始化
function MapComponent() {
  useEffect(() => {
    const map = new mapboxgl.Map({ ... })
  }, [])
  return <div />
}

原因： React 组件会频繁重新渲染。每次渲染都创建新地图会导致无限循环和崩溃。

❌ 错误 3：未正确存储地图实例

// 错误 - map 变量在渲染之间丢失
function MapComponent() {
  useEffect(() => {
    let map = new mapboxgl.Map({ ... })
    // map 变量之后无法访问
  }, [])
}



// 正确 - 存储在 useRef 中
function MapComponent() {
  const mapRef = useRef()
  useEffect(() => {
    mapRef.current = new mapboxgl.Map({ ... })
    // mapRef.current 在整个组件中都可访问
  }, [])
}

原因： 你需要访问地图实例来执行添加图层、标记或调用 remove() 等操作。

❌ 错误 4：useEffect 中的依赖数组错误

// 错误 - 每次渲染都重新创建地图
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  return () => map.remove()
})  // 没有依赖数组

// 错误 - props 改变时重新创建地图
useEffect(() => {
  const map = new mapboxgl.Map({ center: props.center, ... })
  return () => map.remove()
}, [props.center])



// 正确 - 初始化一次
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  return () => map.remove()
}, [])  // 空数组 = 运行一次

// 正确 - 改为更新地图属性
useEffect(() => {
  if (mapRef.current) {
    mapRef.current.setCenter(props.center)
  }
}, [props.center])

原因： 地图初始化开销很大。初始化一次，然后使用地图方法来更新属性。

❌ 错误 5：在源代码中硬编码令牌

// 错误 - 令牌在源代码中暴露
mapboxgl.accessToken = 'pk.YOUR_MAPBOX_TOKEN_HERE';



// 正确 - 使用环境变量
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

原因： 源代码中的令牌会被提交到版本控制并公开暴露。始终使用环境变量。

❌ 错误 6：未处理 Angular SSR

// 错误 - 在服务器端渲染期间崩溃
ngOnInit() {
  import('mapbox-gl').then(mapboxgl => {
    this.map = new mapboxgl.Map({ ... })
  })
}



// 正确 - 先检查平台
ngOnInit() {
  if (!isPlatformBrowser(this.platformId)) {
    return  // 在 SSR 期间跳过地图初始化
  }

  import('mapbox-gl').then(mapboxgl => {
    this.map = new mapboxgl.Map({ ... })
  })
}

原因： Mapbox GL JS 需要浏览器 API（WebGL、Canvas）。没有平台检查，Angular Universal（SSR）会崩溃。

❌ 错误 7：缺少 CSS 导入

// 错误 - 地图渲染但样式损坏
import mapboxgl from 'mapbox-gl';
// 缺少 CSS 导入



// 正确 - 导入 CSS 以获得正确样式
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

原因： CSS 文件包含地图控件、弹出窗口和标记的关键样式。没有它，地图会显示异常。

Next.js 特定模式

App Router（推荐）

'use client'  // 标记为客户端组件

import { useRef, useEffect } from 'react'
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

export default function Map() {
  const mapRef = useRef<mapboxgl.Map>()
  const mapContainerRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (!mapContainerRef.current) return

    mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN!

    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      center: [-71.05953, 42.36290],
      zoom: 13
    })

    return () => mapRef.current?.remove()
  }, [])

  return <div ref={mapContainerRef} style={{ height: '100vh' }} />
}

必须使用 'use client' 指令（地图需要浏览器 API）
使用 process.env.NEXT_PUBLIC_* 访问环境变量
使用 TypeScript 正确键入 mapRef

Pages Router（旧版）

import dynamic from 'next/dynamic'

// 动态导入以禁用地图组件的 SSR
const Map = dynamic(() => import('../components/Map'), {
  ssr: false,
  loading: () => <p>Loading map...</p>
})

export default function HomePage() {
  return <Map />
}

使用 dynamic 导入并设置 ssr: false
提供加载状态
地图组件本身遵循标准 React 模式

默认中心点和缩放级别指南

示例默认值（在 create-web-app 演示中使用）：

中心点：[-71.05953, 42.36290]（波士顿，马萨诸塞州）
缩放级别：13 用于城市级别视图

注意： 如果未指定，GL JS 默认为 center: [0, 0] 和 zoom: 0。请始终明确设置这些值。

缩放级别指南：

0-2：世界视图
3-5：大陆/国家
6-9：区域/州
10-12：城市视图
13-15：街区
16-18：街道级别
19-22：建筑级别

为用户位置自定义：

// 使用浏览器地理位置
if (navigator.geolocation) {
  navigator.geolocation.getCurrentPosition((position) => {
    map.setCenter([position.coords.longitude, position.coords.latitude]);
    map.setZoom(13);
  });
}

模拟 mapbox-gl：

// vitest.config.js 或 jest.config.js
export default {
  setupFiles: ['./test/setup.js']
};



// test/setup.js
vi.mock('mapbox-gl', () => ({
  default: {
    Map: vi.fn(() => ({
      on: vi.fn(),
      remove: vi.fn(),
      setCenter: vi.fn(),
      setZoom: vi.fn()
    })),
    accessToken: ''
  }
}));

原因： Mapbox GL JS 需要测试环境中不存在的 WebGL 和浏览器 API。模拟该库以测试组件逻辑。

何时使用此技能

在以下情况下调用此技能：

在新项目中设置 Mapbox GL JS
将 Mapbox 集成到特定框架（React、Vue、Svelte、Angular、Next.js）中
构建框架无关的 Web 组件
为组件库创建可重用的地图组件

🇺🇸English

Mapbox Integration Patterns Skill

This skill provides official patterns for integrating Mapbox GL JS into web applications using React, Vue, Svelte, Angular, and vanilla JavaScript. These patterns are based on Mapbox's create-web-app scaffolding tool and represent production-ready best practices.

Version Requirements

Mapbox GL JS

Recommended: v3.x (latest)

Minimum: v3.0.0
Why v3.x: Modern API, improved performance, active development
v2.x: Legacy; no longer actively developed (see migration notes below)

Installing via npm (recommended for production):

npm install mapbox-gl@^3.0.0    # Installs latest v3.x

CDN (for prototyping only):

<!-- Replace VERSION with latest v3.x from https://docs.mapbox.com/mapbox-gl-js/ -->
<script src="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.css" rel="stylesheet" />

⚠️ Production apps should use npm, not CDN - ensures consistent versions and offline builds.

Framework Requirements

React:

GL JS works with React 16.8+ (requires hooks)
create-web-app scaffolds with React 19.x

Vue:

GL JS works with Vue 2.x+ (Vue 3 Composition API recommended)
Vue 2.x: Use Options API pattern (mounted/unmounted hooks)

Svelte:

GL JS works with any Svelte version
create-web-app scaffolds with Svelte 5.x

Angular:

GL JS works with Angular 2+ (any version with lifecycle hooks)
create-web-app scaffolds with Angular 19.x

Next.js:

Minimum: 13.x (App Router)
Pages Router: 12.x+

Mapbox Search JS

Required for search integration:

npm install @mapbox/search-js-react@^1.0.0      # React
npm install @mapbox/search-js-web@^1.0.0        # Other frameworks

Version Migration Notes

Migrating from v2.x to v3.x:

WebGL 2 now required
optimizeForTerrain option removed
Improved TypeScript types
Better tree-shaking support
No breaking changes to core initialization patterns

Token patterns (work in v2.x and v3.x):

const token = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; // Use env vars in production

// Global token (works since v1.x)
mapboxgl.accessToken = token;
const map = new mapboxgl.Map({ container: '...' });

// Per-map token (preferred for multi-map setups)
const map = new mapboxgl.Map({
  accessToken: token,
  container: '...'
});

Core Principles

Every Mapbox GL JS integration must:

Initialize the map in the correct lifecycle hook
Store map instance in component state (not recreate on every render)
Always callmap.remove() on cleanup to prevent memory leaks
Handle token management securely (environment variables)
Import CSS: import 'mapbox-gl/dist/mapbox-gl.css'

Framework-Specific Patterns

React Integration

Pattern: useRef + useEffect with cleanup

Note: These examples use Vite (the bundler used in create-web-app). If using Create React App, replace import.meta.env.VITE_MAPBOX_ACCESS_TOKEN with process.env.REACT_APP_MAPBOX_TOKEN. See the Token Management Patterns section for other bundlers.

import { useRef, useEffect } from 'react';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

function MapComponent() {
  const mapRef = useRef(null); // Store map instance
  const mapContainerRef = useRef(null); // Store DOM reference

  useEffect(() => {
    mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      center: [-71.05953, 42.3629],
      zoom: 13
    });

    // CRITICAL: Cleanup to prevent memory leaks
    return () => {
      mapRef.current.remove();
    };
  }, []); // Empty dependency array = run once on mount

  return <div ref={mapContainerRef} style={{ height: '100vh' }} />;
}

Key points:

Use useRef for both map instance and container
Initialize in useEffect with empty deps []
Always return cleanup function that calls map.remove()
Never initialize map in render (causes infinite loops)

React + Search JS:

import { useRef, useEffect, useState } from 'react';
import mapboxgl from 'mapbox-gl';
import { SearchBox } from '@mapbox/search-js-react';
import 'mapbox-gl/dist/mapbox-gl.css';

const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
const center = [-71.05953, 42.3629];

function MapWithSearch() {
  const mapRef = useRef(null);
  const mapContainerRef = useRef(null);
  const [inputValue, setInputValue] = useState('');

  useEffect(() => {
    mapboxgl.accessToken = accessToken;

    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      center: center,
      zoom: 13
    });

    return () => {
      mapRef.current.remove();
    };
  }, []);

  return (
    <>
      <div
        style={{
          margin: '10px 10px 0 0',
          width: 300,
          right: 0,
          top: 0,
          position: 'absolute',
          zIndex: 10
        }}
      >
        <SearchBox
          accessToken={accessToken}
          map={mapRef.current}
          mapboxgl={mapboxgl}
          value={inputValue}
          proximity={center}
          onChange={(d) => setInputValue(d)}
          marker
        />
      </div>
      <div ref={mapContainerRef} style={{ height: '100vh' }} />
    </>
  );
}

Vue Integration

Pattern: mounted + unmounted lifecycle hooks

<template>
  <div ref="mapContainer" class="map-container"></div>
</template>

<script>
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

export default {
  mounted() {
    const map = new mapboxgl.Map({
      container: this.$refs.mapContainer,
      style: 'mapbox://styles/mapbox/standard',
      center: [-71.05953, 42.3629],
      zoom: 13
    });

    // Assign map instance to component property
    this.map = map;
  },

  // CRITICAL: Clean up when component is unmounted
  unmounted() {
    this.map.remove();
    this.map = null;
  }
};
</script>

<style>
.map-container {
  width: 100%;
  height: 100%;
}
</style>

Key points:

Initialize in mounted() hook
Access container via this.$refs.mapContainer
Store map as this.map
Always implementunmounted() hook to call map.remove()

Svelte Integration

Pattern: onMount + onDestroy

<script>
  import mapboxgl from 'mapbox-gl'
  import 'mapbox-gl/dist/mapbox-gl.css'
  import { onMount, onDestroy } from 'svelte'

  let map
  let mapContainer

  onMount(() => {
    map = new mapboxgl.Map({
      container: mapContainer,
      accessToken: import.meta.env.VITE_MAPBOX_ACCESS_TOKEN,
      center: [-71.05953, 42.36290],
      zoom: 13
    })
  })

  // CRITICAL: Clean up on component destroy
  onDestroy(() => {
    map.remove()
  })
</script>

<div class="map" bind:this={mapContainer}></div>

<style>
  .map {
    position: absolute;
    width: 100%;
    height: 100%;
  }
</style>

Key points:

Use onMount for initialization
Bind container with bind:this={mapContainer}
Always implementonDestroy to call map.remove()
Can pass accessToken directly to Map constructor in Svelte

Angular Integration

Pattern: ngOnInit + ngOnDestroy with SSR handling

import { Component, ElementRef, OnDestroy, OnInit, ViewChild, inject } from '@angular/core';
import { isPlatformBrowser, CommonModule } from '@angular/common';
import { PLATFORM_ID } from '@angular/core';
import { environment } from '../../environments/environment';

@Component({
  selector: 'app-map',
  standalone: true,
  imports: [CommonModule],
  templateUrl: './map.component.html',
  styleUrls: ['./map.component.scss']
})
export class MapComponent implements OnInit, OnDestroy {
  @ViewChild('mapContainer', { static: false })
  mapContainer!: ElementRef<HTMLDivElement>;

  private map: any;
  private readonly platformId = inject(PLATFORM_ID);

  async ngOnInit(): Promise<void> {
    // IMPORTANT: Check if running in browser (not SSR)
    if (!isPlatformBrowser(this.platformId)) {
      return;
    }

    try {
      await this.initializeMap();
    } catch (error) {
      console.error('Failed to initialize map:', error);
    }
  }

  private async initializeMap(): Promise<void> {
    // Dynamically import to avoid SSR issues
    const mapboxgl = (await import('mapbox-gl')).default;

    this.map = new mapboxgl.Map({
      accessToken: environment.mapboxAccessToken,
      container: this.mapContainer.nativeElement,
      center: [-71.05953, 42.3629],
      zoom: 13
    });

    // Handle map errors
    this.map.on('error', (e: any) => console.error('Map error:', e.error));
  }

  // CRITICAL: Clean up on component destroy
  ngOnDestroy(): void {
    if (this.map) {
      this.map.remove();
    }
  }
}

Template (map.component.html):

<div #mapContainer style="height: 100vh; width: 100%"></div>

Key points:

Use @ViewChild to reference map container
CheckisPlatformBrowser before initializing (SSR support)
Dynamically importmapbox-gl to avoid SSR issues
Initialize in ngOnInit() lifecycle hook
Always implementngOnDestroy() to call map.remove()
Handle errors with map.on('error', ...)

Vanilla JavaScript (with Vite)

Pattern: Module imports with initialization function

import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
import './main.css';

// Set access token
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

let map;

/**
 * Initialize the map
 */
function initMap() {
  map = new mapboxgl.Map({
    container: 'map-container',
    center: [-71.05953, 42.3629],
    zoom: 13
  });

  map.on('load', () => {
    console.log('Map is loaded');
  });
}

// Initialize when script runs
initMap();

HTML:

<div id="map-container" style="height: 100vh;"></div>

Key points:

Store map in module-scoped variable
Initialize immediately or on DOMContentLoaded
Listen for 'load' event for post-initialization actions

Vanilla JavaScript (No Bundler - CDN)

Pattern: Script tag with inline initialization

⚠️ Note: This pattern is for prototyping only. Production apps should use npm/bundler for version control and offline builds.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Mapbox GL JS - No Bundler</title>

    <!-- Mapbox GL JS CSS -->
    <!-- Replace 3.x.x with latest version from https://docs.mapbox.com/mapbox-gl-js/ -->
    <link href="https://api.mapbox.com/mapbox-gl-js/v3.x.x/mapbox-gl.css" rel="stylesheet" />

    <style>
      body {
        position: absolute;
        top: 0;
        right: 0;
        bottom: 0;
        left: 0;
        margin: 0;
        padding: 0;
      }
      #map-container {
        height: 100%;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map-container"></div>

    <!-- Mapbox GL JS -->
    <!-- Replace 3.x.x with latest version from https://docs.mapbox.com/mapbox-gl-js/ -->
    <script src="https://api.mapbox.com/mapbox-gl-js/v3.x.x/mapbox-gl.js"></script>

    <script>
      // Set access token
      mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN_HERE';

      let map;

      function initMap() {
        map = new mapboxgl.Map({
          container: 'map-container',
          center: [-71.05953, 42.3629],
          zoom: 13
        });

        map.on('load', () => {
          console.log('Map is loaded');
        });
      }

      // Initialize when page loads
      initMap();
    </script>
  </body>
</html>

Key points:

⚠️ Prototyping only - not recommended for production
Replace 3.x.x with specific version (e.g., 3.7.0) from Mapbox docs
Don't use/latest/ - always pin to specific version for consistency
Initialize after script loads (bottom of body)
For production: Use npm + bundler instead

Why not CDN for production?

❌ Network dependency (breaks offline)
❌ No version locking (CDN could change)
❌ Slower (no bundler optimization)
❌ No tree-shaking
✅ Use npm for production: npm install mapbox-gl@^3.0.0

Advanced Patterns

Web Components (Framework-Agnostic)

Web Components are a W3C standard for creating reusable custom elements that work in any framework or no framework at all.

When to use Web Components:

✅ Vanilla JavaScript apps - No framework? Web Components are a great choice
✅ Design systems - Building component libraries used across multiple frameworks
✅ Micro-frontends - Application uses different frameworks in different parts
✅ Multi-framework organizations - Teams working with React, Vue, Svelte, etc. need shared components
✅ Framework migration - Transitioning from one framework to another incrementally
✅ Long-term stability - W3C standard, no framework lock-in

Real-world example: A company with React (main app), Vue (admin panel), and Svelte (marketing site) can build one <mapbox-map> component that works everywhere.

When to use framework-specific patterns instead:

🔧 Already using a framework - If you're building in React, use React patterns (simpler, better integration)
🔧 Need framework features - Deep integration with React hooks, Vue Composition API, state management, routing
🔧 Team familiarity - Team is proficient with framework patterns

💡 Tip: If you're using React, Vue, Svelte, or Angular, start with the framework-specific patterns above. They're simpler and better integrated. Use Web Components when you need cross-framework compatibility or are building vanilla JavaScript apps.

Pattern: Standard Custom Element with lifecycle callbacks

Web Components provide a framework-agnostic way to encapsulate Mapbox maps using the W3C Web Components standard.

Basic Web Component:

import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

class MapboxMap extends HTMLElement {
  constructor() {
    super();
    this.map = null;
  }

  connectedCallback() {
    // Get configuration from attributes
    const token = this.getAttribute('access-token') || import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
    const mapStyle = this.getAttribute('map-style') || 'mapbox://styles/mapbox/standard';
    const center = this.getAttribute('center')?.split(',').map(Number) || [-71.05953, 42.3629];
    const zoom = parseFloat(this.getAttribute('zoom')) || 13;

    // Initialize map
    mapboxgl.accessToken = token;

    this.map = new mapboxgl.Map({
      container: this,
      style: mapStyle,
      center: center,
      zoom: zoom
    });

    // Dispatch custom event when map loads
    this.map.on('load', () => {
      this.dispatchEvent(
        new CustomEvent('mapload', {
          detail: { map: this.map }
        })
      );
    });
  }

  // CRITICAL: Clean up when element is removed
  disconnectedCallback() {
    if (this.map) {
      this.map.remove();
      this.map = null;
    }
  }

  // Expose map instance to JavaScript
  getMap() {
    return this.map;
  }
}

// Register the custom element
customElements.define('mapbox-map', MapboxMap);

Usage in HTML:

<!-- Basic usage -->
<mapbox-map
  access-token="pk.YOUR_TOKEN"
  map-style="mapbox://styles/mapbox/dark-v11"
  center="-122.4194,37.7749"
  zoom="12"
></mapbox-map>

<style>
  mapbox-map {
    display: block;
    height: 100vh;
    width: 100%;
  }
</style>

Usage in React:

import './mapbox-map-component'; // Import to register element

function App() {
  const mapRef = useRef(null);

  useEffect(() => {
    const handleMapLoad = (e) => {
      const map = e.detail.map;
      // Add markers, layers, etc.
      new mapboxgl.Marker().setLngLat([-122.4194, 37.7749]).addTo(map);
    };

    mapRef.current?.addEventListener('mapload', handleMapLoad);

    return () => {
      mapRef.current?.removeEventListener('mapload', handleMapLoad);
    };
  }, []);

  return (
    <mapbox-map
      ref={mapRef}
      access-token={import.meta.env.VITE_MAPBOX_ACCESS_TOKEN}
      map-style="mapbox://styles/mapbox/standard"
      center="-122.4194,37.7749"
      zoom="12"
    />
  );
}

Usage in Vue:

<template>
  <mapbox-map
    ref="map"
    :access-token="token"
    map-style="mapbox://styles/mapbox/streets-v12"
    center="-71.05953,42.3629"
    zoom="13"
    @mapload="handleMapLoad"
  />
</template>

<script>
import './mapbox-map-component';

export default {
  data() {
    return {
      token: import.meta.env.VITE_MAPBOX_ACCESS_TOKEN
    };
  },
  methods: {
    handleMapLoad(event) {
      const map = event.detail.map;
      // Interact with map
    }
  }
};
</script>

Usage in Svelte:

<script>
  import './mapbox-map-component';

  let mapElement;

  function handleMapLoad(event) {
    const map = event.detail.map;
    // Interact with map
  }
</script>

<mapbox-map
  bind:this={mapElement}
  access-token={import.meta.env.VITE_MAPBOX_ACCESS_TOKEN}
  map-style="mapbox://styles/mapbox/standard"
  center="-71.05953,42.3629"
  zoom="13"
  on:mapload={handleMapLoad}
/>

Advanced: Reactive Attributes Pattern:

class MapboxMapReactive extends HTMLElement {
  static get observedAttributes() {
    return ['center', 'zoom', 'map-style'];
  }

  constructor() {
    super();
    this.map = null;
  }

  connectedCallback() {
    mapboxgl.accessToken = this.getAttribute('access-token');

    this.map = new mapboxgl.Map({
      container: this,
      style: this.getAttribute('map-style') || 'mapbox://styles/mapbox/standard',
      center: this.getAttribute('center')?.split(',').map(Number) || [0, 0],
      zoom: parseFloat(this.getAttribute('zoom')) || 9
    });
  }

  disconnectedCallback() {
    if (this.map) {
      this.map.remove();
      this.map = null;
    }
  }

  // React to attribute changes
  attributeChangedCallback(name, oldValue, newValue) {
    if (!this.map || oldValue === newValue) return;

    switch (name) {
      case 'center':
        const center = newValue.split(',').map(Number);
        this.map.setCenter(center);
        break;
      case 'zoom':
        this.map.setZoom(parseFloat(newValue));
        break;
      case 'map-style':
        this.map.setStyle(newValue);
        break;
    }
  }
}

customElements.define('mapbox-map-reactive', MapboxMapReactive);

Key Implementation Points:

Use connectedCallback() for initialization (equivalent to mount/ngOnInit)
Always implementdisconnectedCallback() to call map.remove() (prevents memory leaks)
Read configuration from HTML attributes
Dispatch custom events for map interactions (mapload, etc.)
Use observedAttributes + attributeChangedCallback for reactive updates
Works in any framework without modification

Token Management Patterns

Environment Variables (Recommended)

Different frameworks use different prefixes for client-side environment variables:

Framework/Bundler	Environment Variable	Access Pattern
Vite	`VITE_MAPBOX_ACCESS_TOKEN`	`import.meta.env.VITE_MAPBOX_ACCESS_TOKEN`
Next.js	`NEXT_PUBLIC_MAPBOX_TOKEN`	`process.env.NEXT_PUBLIC_MAPBOX_TOKEN`
Create React App	`REACT_APP_MAPBOX_TOKEN`	`process.env.REACT_APP_MAPBOX_TOKEN`

Vite .env file:

VITE_MAPBOX_ACCESS_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE

Next.js .env.local file:

NEXT_PUBLIC_MAPBOX_TOKEN=pk.YOUR_MAPBOX_TOKEN_HERE

Important:

✅ Always use environment variables for tokens
✅ Never commit .env files to version control
✅ Use public tokens (pk.*) for client-side apps
✅ Add .env to .gitignore
✅ Provide .env.example template for team

.gitignore:

.env
.env.local
.env.*.local

.env.example:

VITE_MAPBOX_ACCESS_TOKEN=your_token_here

Mapbox Search JS Integration

Search Box Component Pattern

Install dependency:

npm install @mapbox/search-js-react      # React
npm install @mapbox/search-js-web        # Vanilla/Vue/Svelte

Note: Both packages include @mapbox/search-js-core as a dependency. You only need to install -core directly if building a custom search UI.

React Search Pattern:

import { SearchBox } from '@mapbox/search-js-react';

// Inside component:
<SearchBox
  accessToken={accessToken}
  map={mapRef.current} // Pass map instance
  mapboxgl={mapboxgl} // Pass mapboxgl library
  value={inputValue}
  onChange={(value) => setInputValue(value)}
  proximity={centerCoordinates} // Bias results near center
  marker // Show marker for selected result
/>;

Key configuration options:

accessToken: Your Mapbox public token
map: Map instance (must be initialized first)
mapboxgl: The mapboxgl library reference
proximity: [lng, lat] to bias results geographically
marker: Boolean to show/hide result marker
placeholder: Search box placeholder text

Positioning Search Box

Absolute positioning (overlay):

<div
  style={{
    position: 'absolute',
    top: 10,
    right: 10,
    zIndex: 10,
    width: 300
  }}
>
  <SearchBox {...props} />
</div>

Common positions:

Top-right: top: 10px, right: 10px
Top-left: top: 10px, left: 10px
Bottom-left: bottom: 10px, left: 10px

Common Mistakes to Avoid

❌ Mistake 1: Forgetting to call map.remove()

// BAD - Memory leak!
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  // No cleanup function
}, [])



// GOOD - Proper cleanup
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  return () => map.remove()  // ✅ Cleanup
}, [])

Why: Every Map instance creates WebGL contexts, event listeners, and DOM nodes. Without cleanup, these accumulate and cause memory leaks.

❌ Mistake 2: Initializing map in render

// BAD - Infinite loop in React!
function MapComponent() {
  const map = new mapboxgl.Map({ ... })  // Runs on every render
  return <div />
}



// GOOD - Initialize in effect
function MapComponent() {
  useEffect(() => {
    const map = new mapboxgl.Map({ ... })
  }, [])
  return <div />
}

Why: React components re-render frequently. Creating a new map on every render causes infinite loops and crashes.

❌ Mistake 3: Not storing map instance properly

// BAD - map variable lost between renders
function MapComponent() {
  useEffect(() => {
    let map = new mapboxgl.Map({ ... })
    // map variable is not accessible later
  }, [])
}



// GOOD - Store in useRef
function MapComponent() {
  const mapRef = useRef()
  useEffect(() => {
    mapRef.current = new mapboxgl.Map({ ... })
    // mapRef.current accessible throughout component
  }, [])
}

Why: You need to access the map instance for operations like adding layers, markers, or calling remove().

❌ Mistake 4: Wrong dependency array in useEffect

// BAD - Re-creates map on every render
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  return () => map.remove()
})  // No dependency array

// BAD - Re-creates map when props change
useEffect(() => {
  const map = new mapboxgl.Map({ center: props.center, ... })
  return () => map.remove()
}, [props.center])



// GOOD - Initialize once
useEffect(() => {
  const map = new mapboxgl.Map({ ... })
  return () => map.remove()
}, [])  // Empty array = run once

// GOOD - Update map property instead
useEffect(() => {
  if (mapRef.current) {
    mapRef.current.setCenter(props.center)
  }
}, [props.center])

Why: Map initialization is expensive. Initialize once, then use map methods to update properties.

❌ Mistake 5: Hardcoding token in source code

// BAD - Token exposed in source code
mapboxgl.accessToken = 'pk.YOUR_MAPBOX_TOKEN_HERE';



// GOOD - Use environment variable
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

Why: Tokens in source code get committed to version control and exposed publicly. Always use environment variables.

❌ Mistake 6: Not handling Angular SSR

// BAD - Crashes during server-side rendering
ngOnInit() {
  import('mapbox-gl').then(mapboxgl => {
    this.map = new mapboxgl.Map({ ... })
  })
}



// GOOD - Check platform first
ngOnInit() {
  if (!isPlatformBrowser(this.platformId)) {
    return  // Skip map init during SSR
  }

  import('mapbox-gl').then(mapboxgl => {
    this.map = new mapboxgl.Map({ ... })
  })
}

Why: Mapbox GL JS requires browser APIs (WebGL, Canvas). Angular Universal (SSR) will crash without platform check.

❌ Mistake 7: Missing CSS import

// BAD - Map renders but looks broken
import mapboxgl from 'mapbox-gl';
// Missing CSS import



// GOOD - Import CSS for proper styling
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';

Why: The CSS file contains critical styles for map controls, popups, and markers. Without it, the map appears broken.

Next.js Specific Patterns

App Router (Recommended)

'use client'  // Mark as client component

import { useRef, useEffect } from 'react'
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

export default function Map() {
  const mapRef = useRef<mapboxgl.Map>()
  const mapContainerRef = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (!mapContainerRef.current) return

    mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN!

    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      center: [-71.05953, 42.36290],
      zoom: 13
    })

    return () => mapRef.current?.remove()
  }, [])

  return <div ref={mapContainerRef} style={{ height: '100vh' }} />
}

Key points:

Must use'use client' directive (maps require browser APIs)
Use process.env.NEXT_PUBLIC_* for environment variables
Type mapRef properly with TypeScript

Pages Router (Legacy)

import dynamic from 'next/dynamic'

// Dynamically import to disable SSR for map component
const Map = dynamic(() => import('../components/Map'), {
  ssr: false,
  loading: () => <p>Loading map...</p>
})

export default function HomePage() {
  return <Map />
}

Key points:

Use dynamic import with ssr: false
Provide loading state
Map component itself follows standard React pattern

Style Configuration

Default Center and Zoom Guidelines

Example defaults (used in create-web-app demos):

Center : [-71.05953, 42.36290] (Boston, MA)
Zoom : 13 for city-level view

Note: GL JS defaults to center: [0, 0] and zoom: 0 if not specified. Always set these explicitly.

Zoom level guide:

0-2: World view
3-5: Continent/country
6-9: Region/state
10-12: City view
13-15: Neighborhood
16-18: Street level
19-22: Building level

Customizing for user location:

// Use browser geolocation
if (navigator.geolocation) {
  navigator.geolocation.getCurrentPosition((position) => {
    map.setCenter([position.coords.longitude, position.coords.latitude]);
    map.setZoom(13);
  });
}

Testing Patterns

Unit Testing Maps

Mock mapbox-gl:

// vitest.config.js or jest.config.js
export default {
  setupFiles: ['./test/setup.js']
};



// test/setup.js
vi.mock('mapbox-gl', () => ({
  default: {
    Map: vi.fn(() => ({
      on: vi.fn(),
      remove: vi.fn(),
      setCenter: vi.fn(),
      setZoom: vi.fn()
    })),
    accessToken: ''
  }
}));

Why: Mapbox GL JS requires WebGL and browser APIs that don't exist in test environments. Mock the library to test component logic.

When to Use This Skill

Invoke this skill when:

Setting up Mapbox GL JS in a new project
Integrating Mapbox into a specific framework (React, Vue, Svelte, Angular, Next.js)
Building framework-agnostic Web Components
Creating reusable map components for component libraries
Debugging map initialization issues
Adding Mapbox Search functionality
Implementing proper cleanup and lifecycle management
Converting between frameworks (e.g., React to Vue)
Reviewing code for Mapbox integration best practices

Related Skills

mapbox-cartography : Map design principles and styling
mapbox-token-security : Token management and security
mapbox-style-patterns : Common map style patterns

Resources

Weekly Installs

400

Repository

mapbox/mapbox-a…t-skills

GitHub Stars

First Seen

Jan 31, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex364

opencode349

gemini-cli346

github-copilot340

amp324

kimi-cli324

Vue.js测试最佳实践：Vue 3组件、组合式函数、Pinia与异步测试完整指南

3,700 周安装

Mapbox Web集成模式：React/Vue/Angular/Svelte最佳实践与GL JS v3教程

🇨🇳中文介绍

Mapbox 集成模式技能

版本要求

Mapbox GL JS

框架要求

相关 Skills

Mapbox Search JS

版本迁移说明

核心原则

特定框架模式

React 集成

Vue 集成

Svelte 集成

Angular 集成

原生 JavaScript（使用 Vite）

原生 JavaScript（无打包工具 - CDN）

高级模式

Web 组件（框架无关）

令牌管理模式

环境变量（推荐）

Mapbox Search JS 集成

搜索框组件模式

搜索框定位

常见错误及避免方法

❌ 错误 1：忘记调用 map.remove()

❌ 错误 2：在渲染函数中初始化地图

❌ 错误 3：未正确存储地图实例

❌ 错误 4：useEffect 中的依赖数组错误

❌ 错误 5：在源代码中硬编码令牌

❌ 错误 6：未处理 Angular SSR

❌ 错误 7：缺少 CSS 导入

Next.js 特定模式

App Router（推荐）

Pages Router（旧版）

样式配置

默认中心点和缩放级别指南

测试模式

单元测试地图

何时使用此技能

🇺🇸English

Mapbox Integration Patterns Skill

Version Requirements

Mapbox GL JS

Framework Requirements

Mapbox Search JS

Version Migration Notes

Core Principles

Framework-Specific Patterns

React Integration

Vue Integration

Svelte Integration

Angular Integration

Vanilla JavaScript (with Vite)

Vanilla JavaScript (No Bundler - CDN)

Advanced Patterns

Web Components (Framework-Agnostic)

Token Management Patterns

Environment Variables (Recommended)

Mapbox Search JS Integration

Search Box Component Pattern

Positioning Search Box

Common Mistakes to Avoid

❌ Mistake 1: Forgetting to call map.remove()

❌ Mistake 2: Initializing map in render

❌ Mistake 3: Not storing map instance properly

❌ Mistake 4: Wrong dependency array in useEffect

❌ Mistake 5: Hardcoding token in source code

❌ Mistake 6: Not handling Angular SSR

❌ Mistake 7: Missing CSS import

Next.js Specific Patterns

App Router (Recommended)

Pages Router (Legacy)

Style Configuration

Default Center and Zoom Guidelines

Testing Patterns

Unit Testing Maps

When to Use This Skill

Related Skills

Resources