Mapbox GL JS 入门与基本用法

编程与开发
Dr.GIS
wowwwai GIS研习社 · 工具流程与项目排障

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 的选择。

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 快速起项目。

  1. 在 head 引入 CSS 与 JS(或 npm 安装后 import)。
  2. 页面放一个带宽高的 <div id=”map”></div>。
  3. 写初始化代码并传入 accessToken。

初始化第一张地图的步骤与常用参数

核心就是 new mapboxgl.Map(options)。容器有尺寸、Token 正确、style 有效,地图就会出来。下面按执行顺序操作:

  1. 确认 Token 可用:浏览器访问带 access_token 的样式测试页,能打开说明 Token 正常。
  2. 写容器样式,例如 width:100%; height:400px;。
  3. 执行初始化:const map = new mapboxgl.Map({ accessToken: ‘你的pk.token’, container: ‘map’, style: ‘mapbox://styles/mapbox/standard’, center: [116.39, 39.90], zoom: 10 });
  4. 监听 load 或 style.load 事件后再 addSource / addLayer,避免异步未就绪报错。
  5. 需要地球投影时加 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 对比?大屏展示该选哪个?再决定是否组合使用。

GitHub Releases 页面上的最新版本标签列表
GitHub Releases 页面上的最新版本标签列表(截图来源:github.com)

验收标准与性能注意点

验收很简单:页面打开后地图瓦片正常出现、能拖动缩放、控制台无 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;需要性能调优时直接参考本站对应优化文并实测验收。