Mapbox GL JS 入门与开发准备
🎯 引言
学完本文,你能在普通网页中创建第一张 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 的代码。
VITE_MAPBOX_TOKEN=你的公开Token
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_TOKEN
.env.local 应加入 .gitignore,避免把本地配置提交到仓库。环境变量不会让公开 Token 在浏览器中变成秘密,它的作用是避免在源码中硬编码并区分开发、测试和生产环境;还要在 Mapbox 的 Access Tokens 页面限制 Token 允许访问的 URL 和权限。
📦 安装并创建地图
本课程示例基于 Node.js 22.9.0 和 mapbox-gl@3.14.0。新项目可以执行:
pnpm add mapbox-gl@3.14.0
<div id="map"></div>
#map {
width: 100%;
height: 280px;
}
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 都要引入。
🧪 小练习
- 把中心点改为你熟悉的城市,保持经度在前、纬度在后。
- 暂时去掉容器高度,观察页面表现和控制台信息,再恢复高度。
// 请在这里编写代码
🎉 恭喜你已经掌握 Mapbox GL JS 的初始化技能啦!
