用途：为在 Web 应用（React、Vue、Svelte、Angular、Next.js 及原生 JS）中集成 Mapbox GL JS 提供官方模式，基于 Mapbox 的 create-web-app 脚手架，属于生产级实践。
版本与安装：推荐 GL JS v3.x（最低 v3.0.0），v2.x 为旧版不再活跃开发。npm 安装：npm install mapbox-gl@^3.0.0；CDN 仅用于原型：引入 api.mapbox.com 的 mapbox-gl.js 与 mapbox-gl.css。框架要求：React 16.8+（需 hooks），Vue 2.x+（推荐 Composition API），Svelte 任意版本，Angular 2+，Next.js 最低 13.x App Router。搜索：npm install @mapbox/search-js-react@^1.0.0（React）或 @mapbox/search-js-web@^1.0.0（其他框架）。
核心原则：在地图正确生命周期钩子中初始化；将实例存入组件状态而非每次渲染重建；清理时必须 map.remove() 防止内存泄漏；用环境变量安全管理令牌；导入 mapbox-gl/dist/mapbox-gl.css。令牌可全局设置 mapboxgl.accessToken 或按地图传入 accessToken。
主要模式：React 用 useRef + useEffect 空依赖初始化并返回清理函数。Vue 需注意不要把 map 放进 data()（响应式 Proxy 会破坏 GL 内部），应直接在 mounted 中赋值 this.map 并在 unmounted 中 remove。搜索框支持 accessToken、map、mapboxgl、proximity、marker、placeholder 等配置，可用绝对定位覆盖在地图上。
常见错误：忘记 map.remove()、在 render 中初始化地图（无限循环）、未正确保存实例、Vue data() 存 map、无 error 事件处理、deck.gl 用 jsDelivr +esm 失败、mapbox-gl-draw 未监听 draw.create、setStyle 后未在 style.load 重新绑定图层。
技能包含 references 目录，覆盖 Vue、Svelte、Angular、原生 JS、Web Components、Next.js、常见错误与令牌管理等框架专属细节。适用于新项目搭建、特定框架集成、可复用地图组件、调试初始化问题、添加搜索功能与跨框架迁移。