Mapbox GL JS 入门与开发准备

认识 Mapbox 产品之间的关系,配置 Access Token,并创建第一张可交互地图。

🎯 引言

学完本文,你能在普通网页中创建第一张 Mapbox 地图,并能排查 Token、容器尺寸和 WebGL 导致的初始化失败。


🧱 Mapbox GL JS 解决什么问题

Mapbox GL JS 是在浏览器中使用 WebGL 绘制交互地图的 JavaScript 库。它适合显示底图、叠加点线面数据、切换视角,并响应点击和缩放等操作。

Mapbox 的几个常见名称分工如下:

名称作用
Mapbox GL JS在网页中加载、绘制和操作地图
Mapbox Studio在线制作地图样式和管理数据资源
Style描述底图、字体、颜色和图层的 JSON 配置
Tileset按瓦片组织的数据,地图可按当前范围加载

地图实例是总入口;Style 决定整张地图的显示规则;Source 提供数据;Layer 把数据画成圆、线、填充或文字;Control 是缩放、比例尺等界面控件。


🔐 配置 Access Token

Access Token 是 Mapbox 识别项目并判断资源访问权限的凭证。Mapbox GL JS 在浏览器中加载样式、瓦片和字体,因此公开 Token 会随网络请求发送,这和服务端密钥的用法不同。

创建地图前,把项目配置中读取到的公开 Token 赋给 mapboxgl.accessToken。本课程用 Vite 的环境变量演示配置方式;如果项目使用其他构建工具,只需替换读取 Token 的代码。

.env.local
VITE_MAPBOX_TOKEN=你的公开Token
main.js
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN

.env.local 应加入 .gitignore,避免把本地配置提交到仓库。环境变量不会让公开 Token 在浏览器中变成秘密,它的作用是避免在源码中硬编码并区分开发、测试和生产环境;还要在 Mapbox 的 Access Tokens 页面限制 Token 允许访问的 URL 和权限。

Mapbox 控制台会不定期更新,按钮名称和入口位置可能与你看到的略有不同。流程仅供参考,操作时以平台最新页面为准。

📦 安装并创建地图

本课程示例基于 Node.js 22.9.0 和 mapbox-gl@3.14.0。新项目可以执行:

pnpm add mapbox-gl@3.14.0
index.html
<div id="map"></div>
style.css
#map {
    width: 100%;
    height: 280px;
}
main.js
import mapboxgl from 'mapbox-gl'
import 'mapbox-gl/dist/mapbox-gl.css'

mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN

const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/light-v11',
    center: [116.397, 39.909],
    zoom: 10,
})

container 可以接收 DOM 元素。地图会把 Canvas 放进容器,如果容器高度为 0,实例可能已创建,但页面仍然看不到地图。CSS 也必须引入,否则控件和 Popup 的样式会异常。

下面是这段初始化逻辑的真实渲染效果:


⚠️ 初始化失败怎么排查

  • 控制台出现 401 或 403:检查 Token、权限和 URL 限制。
  • 页面只有空白区域:检查容器是否具有明确宽高。
  • 样式或瓦片请求失败:检查网络、Style URL 和 Token 权限。
  • 提示无法创建 WebGL 上下文:更新浏览器和显卡驱动,并检查浏览器是否禁用了硬件加速。
  • 使用服务端渲染框架时报 window is not defined:只在代码进入浏览器后创建地图实例。

🧾 小节总结

  • Mapbox GL JS 负责在浏览器中绘制和操作交互地图。
  • Style、Source、Layer 和 Control 分别负责地图规则、数据、显示方式和控件。
  • 浏览器加载 Mapbox 资源需要公开 Access Token。
  • 地图容器必须具有明确宽高,实例应在浏览器中创建。
  • Token、WebGL、网络和容器尺寸是初始化失败的常见原因。

❓ 知识问答

Q1:为什么公开 Token 不能真正隐藏在前端?

地图 SDK 需要从浏览器请求样式和瓦片,公开 Token 会随请求发送。环境变量用于避免在源码中硬编码并区分运行环境,访问控制仍要依靠 Token 的 URL 和权限限制。

Q2:Mapbox Studio 和 Mapbox GL JS 是同一个工具吗?

不是。Studio 用来制作和管理资源,Mapbox GL JS 用来在网页中加载并操作这些资源。

Q3:只引入 JS,不引入 CSS 可以吗?

底图可能仍会出现,但控件、Marker 和 Popup 会缺少必要样式,因此 JS 与 CSS 都要引入。


🧪 小练习

  1. 把中心点改为你熟悉的城市,保持经度在前、纬度在后。
  2. 暂时去掉容器高度,观察页面表现和控制台信息,再恢复高度。
// 请在这里编写代码

🎉 恭喜你已经掌握 Mapbox GL JS 的初始化技能啦!