在 Mapbox 中加载瓦片服务
🎯 引言
学完本文,你能把 Mapbox 瓦片集、第三方图片瓦片和在线地图图片服务接入地图,并根据服务类型正确配置 Source 与 Layer。
WebGIS 课程已经介绍了瓦片、坐标系和地图服务的通用原理。本文只在需要时简短回顾,并重点讲它们在 Mapbox GL JS 中如何调用。
🧩 加载 Mapbox 矢量 Tileset
**Tileset(瓦片集)**是按缩放级别和地理范围切分好的一组地图数据。它的作用是让地图只请求当前画面需要的小块数据,不必一次下载完整数据。
Mapbox 托管的矢量 Tileset 保存点、线、面及其属性,可以通过 mapbox:// 地址注册为 vector Source。一个 Tileset 内部还能包含道路、建筑、等高线等多个数据层,因此 Layer 必须通过 source-layer 指定这次要画哪一层:
map.addSource('terrain', {
type: 'vector',
url: 'mapbox://mapbox.mapbox-terrain-v2',
})
map.addLayer({
id: 'terrain-contours',
type: 'line',
source: 'terrain',
'source-layer': 'contour',
slot: 'middle',
paint: {
'line-color': '#7c3aed',
'line-width': 1,
},
})
下面是这段代码的真实渲染效果。地图加载 mapbox.mapbox-terrain-v2 矢量 Tileset,再从其中名为 contour 的数据层绘制紫色等高线:
这里有三种容易混淆的名称:
| 配置 | 表示什么 | 示例值 |
|---|---|---|
| Source ID | 当前地图中注册的数据源名称 | terrain |
| Tileset URL | Mapbox 托管资源的地址 | mapbox://mapbox.mapbox-terrain-v2 |
source-layer | Tileset 内部要绘制的数据层名称 | contour |
source-layer 写错时,Source 请求可能成功,但地图仍然没有对象可画。自有 Tileset 的 ID 和内部 Layer 名称可以在 Mapbox Studio 的 Tilesets 页面查看。
🌐 加载自建 MVT 服务
**MVT(Mapbox Vector Tile)**是一种常用的矢量瓦片格式,规定一块瓦片怎样保存点、线、面和属性。**PBF(Protocol Buffers)**是它常用的二进制编码,作用是用较紧凑的文件传输这些数据,因此地址经常以 .pbf 结尾。
自建 MVT 服务可以向 Mapbox 提供 URL 模板,也就是含有占位符的瓦片地址。{z} 表示缩放级别,{x} 和 {y} 表示该级别中的列号与行号,Mapbox 会根据当前视口自动替换它们。
minzoom 表示服务开始提供瓦片的最小缩放级别,maxzoom 表示服务实际拥有数据的最大级别。它们的作用是阻止 Mapbox 请求服务并不存在的层级:
map.addSource('roads', {
type: 'vector',
tiles: ['https://example.com/tiles/roads/{z}/{x}/{y}.pbf'],
minzoom: 6,
maxzoom: 14,
})
map.addLayer({
id: 'road-lines',
type: 'line',
source: 'roads',
'source-layer': 'roads',
slot: 'middle',
paint: {
'line-color': '#2563eb',
'line-width': 2,
},
})
示例中的 6 表示从第 6 级开始加载,14 表示放得更近时继续使用第 14 级瓦片,不会凭空得到更精细的数据。Layer 也能设置同名字段,用来控制它在哪些级别显示。
🖼 加载 XYZ 栅格瓦片
栅格瓦片是已经绘制好的小图片,常见格式有 PNG、JPEG 和 WebP。XYZ 表示瓦片地址用 {z}/{x}/{y} 组织,其中 z 是缩放级别,x 是列号,y 是行号。在 Mapbox 中,它需要使用 raster Source 和 raster Layer。
tileSize 表示每块瓦片图片的设计尺寸,单位是像素;attribution 表示地图上必须保留的数据来源说明:
map.addSource('raster-basemap', {
type: 'raster',
tiles: ['https://tile.example.com/{z}/{x}/{y}.png'],
tileSize: 256,
minzoom: 0,
maxzoom: 18,
attribution: '地图数据来源',
})
map.addLayer({
id: 'raster-basemap-layer',
type: 'raster',
source: 'raster-basemap',
slot: 'bottom',
paint: {
'raster-opacity': 0.8,
},
})
tileSize 必须和服务保持一致,常见示例值是 256 或 512。TMS 是另一种瓦片编号方式,它的 y 轴方向与 XYZ 相反;如果服务使用 TMS,需要在 Source 中增加 scheme: 'tms'。
瓦片服务还可能限制并发量、缓存方式和允许访问的域名,接入前应查看服务条款,不要删除 attribution 中必须展示的来源信息。
下面使用 Mapbox 托管的卫星影像作为栅格 Source。它和上面的 XYZ 服务使用相同的 raster Layer,区别只是数据地址由 mapbox://mapbox.satellite 提供:
📡 把 WMS 作为栅格图层
**WMS(Web Map Service)**是由服务器根据范围、图层和图片格式生成地图图片的服务。GetMap 是它的取图请求,作用是告诉服务器“请返回这个范围内的这几个图层”。
Mapbox GL JS 没有独立的 WMS Source 类型,但可以把 GetMap 地址配置成 raster Source。{bbox-epsg-3857} 是 Mapbox 支持的范围占位符,会被替换为每块瓦片在 Web Mercator 投影中的坐标范围:
const wmsUrl = [
'https://example.com/geoserver/wms',
'?service=WMS',
'&version=1.1.1',
'&request=GetMap',
'&layers=workspace:areas',
'&styles=',
'&format=image/png',
'&transparent=true',
'&srs=EPSG:3857',
'&bbox={bbox-epsg-3857}',
'&width=256',
'&height=256',
].join('')
map.addSource('area-wms', {
type: 'raster',
tiles: [wmsUrl],
tileSize: 256,
})
map.addLayer({
id: 'area-wms-layer',
type: 'raster',
source: 'area-wms',
slot: 'middle',
})
srs 用来声明请求坐标采用哪套规则。EPSG:3857 是 Web Mercator 投影的登记编号,也是网页地图常用的投影。示例使用 WMS 1.1.1,是为了让范围参数顺序与 Mapbox 提供的占位符一致;换成其他版本或坐标系时,要先确认服务的轴顺序和支持范围。
🪤 请求成功但地图不显示
可以按下面的顺序排查:
- 在浏览器网络面板检查瓦片请求是否为
200。 - 矢量瓦片检查
source-layer是否与服务内部名称一致。 - 检查地图 Zoom 是否位于 Source 和 Layer 的层级范围内。
- 检查服务的坐标参考系统、XYZ/TMS 方向和
tileSize是否匹配。 - 检查业务 Layer 是否被底图遮住,Standard Style 可设置合适的
slot。 - 出现跨域错误时,应检查瓦片服务器是否允许当前网站读取资源。
**CORS(跨域资源共享)**是服务器允许哪些网站读取资源的浏览器规则。瓦片服务器需要在响应头中允许当前网站的域名,否则请求即使到达服务器,浏览器也不会把结果交给 Mapbox。
地图初始化时可以监听资源错误,先取得失败请求的线索:
map.on('error', (event) => {
console.error('地图资源加载失败', event.error)
})
🧾 小节总结
- Mapbox 托管 Tileset 使用
mapbox://URL,自建服务可以使用瓦片 URL 模板。 - 矢量瓦片 Layer 必须配置正确的
source-layer。 - XYZ 图片使用
rasterSource,TMS 服务还要配置scheme: 'tms'。 - WMS 可以通过带
{bbox-epsg-3857}的GetMap请求接入。 minzoom、maxzoom、tileSize、CORS 和图层位置是常见排查点。
❓ 知识问答
Q1:为什么 Source 已经加载成功,矢量图层仍然是空的?
优先检查 source-layer。它必须等于矢量瓦片内部的数据层名称,不是 Source ID,也不是页面上的 Layer ID。
Q2:WMTS 能不能直接加载?
**WMTS(Web Map Tile Service)**是直接提供预先切好瓦片的服务。它能提供与 Mapbox 匹配的 Web Mercator XYZ 地址时,可以按栅格或矢量瓦片 Source 接入;如果地址使用参数形式,则要根据服务的瓦片矩阵规则拼出正确模板。
Q3:为什么跨域错误不能在 Mapbox 配置里解决?
CORS 响应头由瓦片服务器返回。浏览器拒绝响应后,Mapbox 也无法读取,需要在服务端允许网站域名访问。
🧪 小练习
- 把一个 XYZ 图片服务添加为
rasterSource,并设置正确的tileSize。 - 为一个 MVT 服务添加 Line Layer,填写它真实的
source-layer。
// 请在这里编写代码
🎉 恭喜你已经掌握在 Mapbox 中接入常用瓦片服务的方法啦!
