Mapbox 集成模式技能

该技能提供在 React、Vue、Svelte、Angular 和原生 JavaScript Web 应用中集成 Mapbox GL JS 的官方模式。这些模式基于 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 方式（仅限原型开发）：

框架要求

React：GL JS 兼容 React 16.8+（需支持 Hooks）。create-web-app 默认使用 React 19.x 进行脚手架搭建。
Vue：GL JS 兼容 Vue 2.x+（推荐使用 Vue 3 Composition API）。
Svelte：GL JS 兼容所有 Svelte 版本。create-web-app 默认使用 Svelte 5.x 进行脚手架搭建。
Angular：GL JS 兼容 Angular 2+。create-web-app 默认使用 Angular 19.x 进行脚手架搭建。
Next.js：最低要求为 13.x（App Router），Pages Router 要求 12.x+。

Mapbox Search JS

npm install @mapbox/search-js-react@^1.0.0      # React
npm install @mapbox/search-js-web@^1.0.0        # 其他框架

版本迁移说明（v2.x → v3.x）

• 现需 WebGL 2 支持
• 移除 optimizeForTerrain 配置项
• TypeScript 类型定义增强，支持更优的 Tree-shaking
• 核心初始化模式无破坏性变更

Token 使用模式（v2.x 与 v3.x 均兼容）：

const token = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; // 生产环境中建议使用环境变量

// 全局 Token（自 v1.x 起即支持）
mapboxgl.accessToken = token;
const map = new mapboxgl.Map({ container: '...' });

// 按地图实例指定 Token（多地图场景下推荐）
const map = new mapboxgl.Map({
  accessToken: token,
  container: '...'
});

核心原则

所有 Mapbox GL JS 集成方案必须满足以下要求：

1. 在正确的生命周期钩子中初始化地图
2. 将地图实例存储于组件状态中（避免每次渲染都重建）
3. 清理阶段务必调用 map.remove()，防止内存泄漏
4. 安全地管理 Token（推荐使用环境变量）
5. 导入 CSS 样式文件：import 'mapbox-gl/dist/mapbox-gl.css'

React 集成（主推模式）

模式：useRef + useEffect（含清理逻辑）

注意：以下示例基于 Vite（即 create-web-app 所用打包器）。若使用 Create React App，请将 import.meta.env.VITE_MAPBOX_ACCESS_TOKEN 替换为 process.env.REACT_APP_MAPBOX_TOKEN。其他打包器的 Token 管理方式请参阅《Token 管理模式》文档。

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

function MapComponent() {
  const mapRef = useRef(null); // 存储地图实例
  const mapContainerRef = useRef(null); // 存储 DOM 引用

  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
    });

    // 关键：执行清理以防止内存泄漏
    return () => {
      mapRef.current.remove();
    };
  }, []); // 空依赖数组表示仅在挂载时执行一次

  return 
;
}

关键要点：

• 对地图实例和容器均使用 useRef
• 在 useEffect 中初始化，并使用空依赖数组 []
• 必须返回清理函数，且其中需调用 map.remove()
• 切勿在 render 函数中初始化地图（否则引发无限循环）

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 (
    <>
      

         setInputValue(d)}
          marker
        />
      
      

    
  );
}

Search JS 集成概要

安装命令：

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

两个包均将 @mapbox/search-js-core 作为依赖引入。仅当构建自定义搜索 UI 时，才需直接安装 -core 包。

关键配置项：

• accessToken：您的 Mapbox 公开 Token
• map：地图实例（必须先完成初始化）
• mapboxgl：mapboxgl 库引用
• proximity：地理偏置结果的坐标 [lng, lat]
• marker：布尔值，控制是否显示搜索结果标记
• placeholder：搜索框占位符文本

搜索框定位方式

绝对定位（叠加层）：

常见定位位置：

• 右上角：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：在 render 函数中初始化地图

// 错误 —— React 中将触发无限循环！
function MapComponent() {
  const map = new mapboxgl.Map({ ... })  // 每次渲染均执行
  return 

}

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

}

原因：React 组件会频繁重渲染。若每次渲染都新建地图实例，将导致无限循环乃至崩溃。

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

// 错误 —— 变量在渲染之间丢失
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：在 Vue 的 data() 中存储地图实例（Vue 特有）

// 错误 —— Vue 的响应式系统会将 data() 对象包装为 Proxy，从而破坏 mapbox-gl 内部逻辑！
export default {
  data() {
    return {
      map: null  // 将被 Proxy 包装
    }
  },
  mounted() {
    this.map = new mapboxgl.Map({ ... })  // Proxy 会破坏 GL 内部机制
  }
}

// 正确 —— 将地图作为普通实例属性赋值，不放入 data()
export default {
  mounted() {
    this.map = new mapboxgl.Map({
      container: this.$refs.mapContainer,
      center: [-71.05953, 42.3629],
      zoom: 13
    })
  },
  unmounted() {
    this.map?.remove()
  }
}

原因：在 Vue（尤其是 Vue 3）中，data() 属性会被 Proxy 包裹以实现响应式。Mapbox GL JS 内部依赖对象身份校验及特定属性访问，而这些特性在 Proxy 包裹后无法正常工作。将地图实例存入 data() 将导致难以调试的隐性故障。应改为在 mounted() 中直接以 this.map 形式赋值 —— 此类非 data() 属性不会被设为响应式。

参考文件

如需查看各框架专属集成模式及更多细节，请加载以下文件：

• references/vue.md — Vue 集成（mounted/unmounted 生命周期）
• references/svelte.md — Svelte 集成（onMount/onDestroy）
• references/angular.md — Angular 集成（含 SSR 处理）
• references/vanilla.md — 原生 JS（Vite）与原生 JS（CDN）
• references/web-components.md — Web Components（基础版 + 响应式版 + 在 React/Vue/Svelte 中的使用）
• references/nextjs.md — Next.js App Router 与 Pages Router
• references/common-mistakes.md — 常见错误 4–7 及测试模式
• references/token-management.md — 各打包器下的 Token 管理与样式配置

何时使用本技能

当出现以下情形时，请调用本技能：

• 在新项目中配置 Mapbox GL JS
• 将 Mapbox 集成至特定框架（React、Vue、Svelte、Angular、Next.js）
• 构建与框架无关的 Web Components
• 为组件库创建可复用的地图组件
• 调试地图初始化相关问题
• 添加 Mapbox Search 功能
• 实现规范的清理与生命周期管理
• 跨框架迁移（例如从 React 迁移至 Vue）
• 审查代码是否符合 Mapbox 集成最佳实践

关联技能

• mapbox-cartography：地图设计原则与样式规范
• mapbox-token-security：Token 管理与安全性
• mapbox-style-patterns：常用地图样式模式

参考资料

• Mapbox GL JS 文档
• Mapbox Search JS 文档
• create-web-app GitHub 仓库