Mapbox GL JS 入门与基本用法
Mapbox GL JS 是客户端 JavaScript 库,用 WebGL 在浏览器里渲染交互式矢量地图,支持自定义样式、用户交互、数据可视化和 3D 效果。入门很直接:注册 Mapbox 账号拿到以 pk. 开头的公共 Access Token,用 CDN 或 npm 引入库与 CSS,再在有明确宽高的容器里用 mapboxgl.Map 初始化即可。截至 2026 年 11 月,稳定版已到 v3.34.2,默认使用 Mapbox Standard 样式,并要求 WebGL 2。想先搞清它和 Leaflet 的取舍,可先看本站WebGIS 开发入门:前端三大件与 Leaflet/Mapbox GL JS 的选择。

准备工作:账号、Token 与容器
没有有效 Token,地图就会空白。去 Mapbox 账户控制台创建公共 Token(scopes 至少包含 STYLES:READ),可按域名做 URL 限制。Token 会把请求和你的账户关联起来,超额或停用也会导致加载失败。
- 容器元素(比如 id 为 map 的 div)必须用 CSS 或内联样式写死宽高,否则看不见地图。
- 隐藏后再显示时,记得调用 map.resize()。
- 用 mapboxgl.supported() 先检测浏览器是否支持 WebGL 2。
Secret Token 留给服务端写操作,前端只用公共 Token。
CDN 与 npm 两种引入方式怎么选
简单 HTML 页面用 CDN 最快;工程化项目用 npm,还能走 ESM 按需加载减小体积。
| 方式 | 适用场景 | 引入要点 | 注意 |
|---|---|---|---|
| CDN | 原型、静态页 | head 里同时引 CSS 和 JS,版本号写成当前稳定版如 v3.34.2 | CSS 必需,否则控件样式丢失 |
| npm | React/Vue/工程 | npm install mapbox-gl;推荐 import * as mapboxgl from ‘mapbox-gl/esm’ 并单独引 CSS | v3.25+ 支持模块化渲染,bundle 可减约 27% |
CDN 示例链接形式:https://api.mapbox.com/mapbox-gl-js/v3.34.2/mapbox-gl.css 与对应 .js。最新标签和发布说明见 Mapbox GL JS GitHub Releases。也可用官方脚手架 npm create @mapbox/web-app 快速起项目。
- 在 head 引入 CSS 与 JS(或 npm 安装后 import)。
- 页面放一个带宽高的 <div id=”map”></div>。
- 写初始化代码并传入 accessToken。
初始化第一张地图的步骤与常用参数
核心就是 new mapboxgl.Map(options)。容器有尺寸、Token 正确、style 有效,地图就会出来。下面按执行顺序操作:
- 确认 Token 可用:浏览器访问带 access_token 的样式测试页,能打开说明 Token 正常。
- 写容器样式,例如 width:100%; height:400px;。
- 执行初始化:const map = new mapboxgl.Map({ accessToken: ‘你的pk.token’, container: ‘map’, style: ‘mapbox://styles/mapbox/standard’, center: [116.39, 39.90], zoom: 10 });
- 监听 load 或 style.load 事件后再 addSource / addLayer,避免异步未就绪报错。
- 需要地球投影时加 projection: ‘globe’;需要控件时 map.addControl(new mapboxgl.NavigationControl())。
常用参数简表:
| 参数 | 含义 | 示例/默认 |
|---|---|---|
| accessToken | 公共 Token | 必填,pk. 开头 |
| container | 容器 id 或元素 | ‘map’ |
| style | 样式 URL | 默认 mapbox://styles/mapbox/standard;也可用 streets-v12 等 |
| center | 中心点 [经度, 纬度] | [-74.5, 40] |
| zoom | 缩放级别 | 0–22 左右 |
| projection | 投影 | ‘mercator’ 或 ‘globe’ |
v3 起强制 WebGL 2,并内置 3D 灯光、模型、阴影和配置化样式。RTL 文本(阿拉伯/希伯来)从 v3.33.0 起开箱即用。做大屏可视化时,若还要叠加大量点线面动画,可对比本站Deck.gl 和 Mapbox GL 对比?大屏展示该选哪个?再决定是否组合使用。

验收标准与性能注意点
验收很简单:页面打开后地图瓦片正常出现、能拖动缩放、控制台无 401/403、容器尺寸变化后调用 resize 仍正常。若觉得卡顿,优先换 ESM 入口、减少同时显示的图层、按需加载模块。更细的优化步骤和源码示例见本站Mapbox GL JS 地图加载慢或卡顿?性能优化方案及源码示例。
- 不要过度 transpile 官方 bundle,尤其是 Worker 部分。
- CSP 环境需允许 blob: worker、指定 connect-src(*.tiles.mapbox.com、api.mapbox.com 等),3D/Standard 时还可能要 wasm-unsafe-eval。
- Referrer Policy 要能发出 Referer,否则带 URL 限制的 Token 会失败。
- 运行时 loadImage 只支持 png/jpg/webp,不支持 svg。
常见问题
地图一片空白,控制台报 401 或 403?
最常见是 Token 写错、过期、缺少 STYLES:READ,或 URL 限制不匹配当前域名。换新公共 Token 测试,并检查 Referer 是否被 CSP/代理去掉。账户超额未付也会停服。
为什么初始化后还是看不见地图?
容器没有明确宽高,或当时处于 display:none。给容器写死尺寸,显示后立刻 map.resize()。也可用 mapboxgl.supported() 排除 WebGL 2 不支持的情况。
addLayer 时报错说 source 不存在?
style 和 source 是异步加载的。务必在 map.on(‘load’) 或 style.load 回调里再 addSource/addLayer。Standard 样式还要注意图层 slots 顺序。
该用哪个版本号?文档和 npm 不一致怎么办?
以 GitHub 最新稳定 Release 为准。截至 2026 年 11 月 7 日,稳定版为 v3.34.2(11 月 3 日发布)。CDN 把版本号改成对应数字即可;不确定时到 Mapbox GL JS 标签页核对。
总结:拿到 Token、保证容器有尺寸、用 CDN 或 ESM 引入正确版本、在 load 后再操作图层,就能稳定跑通第一张 Mapbox GL JS 地图。建议先用 CDN 做最小可运行示例验证 Token 与浏览器兼容性,再迁到工程里用 npm + ESM;需要性能调优时直接参考本站对应优化文并实测验收。