在 Mapbox 中加载瓦片服务

使用 Mapbox GL JS 加载矢量瓦片、XYZ 栅格瓦片和 WMS,并处理 source-layer、层级、插槽与跨域问题。

🎯 引言

学完本文,你能把 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 的数据层绘制紫色等高线:

紫色线来自矢量 Tileset 中的 contour 数据层

这里有三种容易混淆的名称:

配置表示什么示例值
Source ID当前地图中注册的数据源名称terrain
Tileset URLMapbox 托管资源的地址mapbox://mapbox.mapbox-terrain-v2
source-layerTileset 内部要绘制的数据层名称contour

source-layer 写错时,Source 请求可能成功,但地图仍然没有对象可画。自有 Tileset 的 ID 和内部 Layer 名称可以在 Mapbox Studio 的 Tilesets 页面查看。

Mapbox Studio 页面会不定期更新,入口和字段名称可能与你看到的略有不同。操作时以平台最新页面为准。

🌐 加载自建 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 提供:

卫星影像由 Raster Source 加载并通过 Raster Layer 显示

📡 把 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 提供的占位符一致;换成其他版本或坐标系时,要先确认服务的轴顺序和支持范围。


🪤 请求成功但地图不显示

可以按下面的顺序排查:

  1. 在浏览器网络面板检查瓦片请求是否为 200。
  2. 矢量瓦片检查 source-layer 是否与服务内部名称一致。
  3. 检查地图 Zoom 是否位于 Source 和 Layer 的层级范围内。
  4. 检查服务的坐标参考系统、XYZ/TMS 方向和 tileSize 是否匹配。
  5. 检查业务 Layer 是否被底图遮住,Standard Style 可设置合适的 slot。
  6. 出现跨域错误时,应检查瓦片服务器是否允许当前网站读取资源。

**CORS(跨域资源共享)**是服务器允许哪些网站读取资源的浏览器规则。瓦片服务器需要在响应头中允许当前网站的域名,否则请求即使到达服务器,浏览器也不会把结果交给 Mapbox。

地图初始化时可以监听资源错误,先取得失败请求的线索:

map.on('error', (event) => {
    console.error('地图资源加载失败', event.error)
})

🧾 小节总结

  • Mapbox 托管 Tileset 使用 mapbox:// URL,自建服务可以使用瓦片 URL 模板。
  • 矢量瓦片 Layer 必须配置正确的 source-layer。
  • XYZ 图片使用 raster Source,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 也无法读取,需要在服务端允许网站域名访问。


🧪 小练习

  1. 把一个 XYZ 图片服务添加为 raster Source,并设置正确的 tileSize。
  2. 为一个 MVT 服务添加 Line Layer,填写它真实的 source-layer。
// 请在这里编写代码

🎉 恭喜你已经掌握在 Mapbox 中接入常用瓦片服务的方法啦!