技能标识：mapbox-web-integration-patterns
Official integration patterns for Mapbox GL JS across popular web frameworks (React, Vue, Svelte, Angular). Covers setup, lifecycle management, token handling, search integration, and common pitfalls. Based on Mapbox's create-web-app scaffolding tool.
本技能提供了使用 React、Vue、Svelte、Angular 和原生 JavaScript 将 Mapbox GL JS 集成到 Web 应用程序中的官方模式。这些模式基于 Mapbox 的 create-web-app 脚手架工具，代表了生产环境就绪的最佳实践。
推荐版本： v3.x（最新版）
通过 npm 安装（推荐用于生产环境）：
bash
npm install mapbox-gl@^3.0.0 # 安装最新的 v3.x 版本
CDN（仅用于原型开发）：
html
React： GL JS 支持 React 16.8+（需要 hooks）。create-web-app 使用 React 19.x 进行脚手架搭建。
Vue： GL JS 支持 Vue 2.x+（推荐使用 Vue 3 组合式 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+。
bash
npm install @mapbox/search-js-react@^1.0.0 # React
npm install @mapbox/search-js-web@^1.0.0 # 其他框架
令牌模式（适用于 v2.x 和 v3.x）：
javascript
const token = import.meta.env.VITEMAPBOXACCESS_TOKEN; // 在生产环境中使用环境变量
// 全局令牌（自 v1.x 起可用）
mapboxgl.accessToken = token;
const map = new mapboxgl.Map({ container: ... });
// 每个地图的令牌（多地图设置时推荐）
const map = new mapboxgl.Map({
accessToken: token,
container: ...
});
每个 Mapbox GL JS 集成必须：
模式：useRef + useEffect 带清理
注意： 这些示例使用 Vite（create-web-app 中使用的打包工具）。如果使用 Create React App，请将 import.meta.env.VITEMAPBOXACCESSTOKEN 替换为 process.env.REACTAPPMAPBOXTOKEN。其他打包工具请参见令牌管理模式。
jsx
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.VITEMAPBOXACCESS_TOKEN;
mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
center: [-71.05953, 42.3629],
zoom: 13
});
// 关键：清理以防止内存泄漏
return () => {
mapRef.current.remove();
};
}, []); // 空依赖数组 = 挂载时运行一次
return
;关键点：
jsx
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.VITEMAPBOXACCESS_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 (
<>
margin: 10px 10px 0 0,
width: 300,
right: 0,
top: 0,
position: absolute,
zIndex: 10
}}
>
map={mapRef.current}
mapboxgl={mapboxgl}
value={inputValue}
proximity={center}
onChange={(d) => setInputValue(d)}
marker
/>
安装：
bash
npm install @mapbox/search-js-react # React
npm install @mapbox/search-js-web # 原生/Vue/Svelte
两个包都包含 @mapbox/search-js-core 作为依赖项。只有在构建自定义搜索 UI 时才直接安装 -core。
关键配置选项：
绝对定位（覆盖层）：
jsx
position: absolute,
top: 10,
right: 10,
zIndex: 10,
width: 300
}}
常见位置：
javascript
// 错误 - 内存泄漏！
useEffect(() => {
const map = new mapboxgl.Map({ ... })
// 没有清理函数
}, [])
// 正确 - 正确清理
useEffect(() => {
const map = new mapboxgl.Map({ ... })
return () => map.remove() // 清理
}, [])
原因： 每个 Map 实例都会创建 WebGL 上下文、事件监听器和 DOM 节点。没有清理，这些会累积并导致内存泄漏。
javascript
// 错误 - React 中无限循环！
function MapComponent() {
const map = new mapboxgl.Map({ ... }) // 每次渲染都运行
return
// 正确 - 在 effect 中初始化
function MapComponent() {
useEffect(() => {
const map = new mapboxgl.Map({ ... })
}, [])
return
原因： React 组件
以下为平台配置的接入选项，并非逐项实测通过。能否安装取决于客户端支持、技能来源和运行环境：
帮我安装 SkillHub 和 mapbox-web-integration-patterns-1775918951 技能
设置 SkillHub 为我的优先技能安装源，然后帮我安装 mapbox-web-integration-patterns-1775918951 技能
skillhub install mapbox-web-integration-patterns-1775918951
文件大小: 18.85 KB | 发布时间: 2026-4-12 10:31