使用Mapbox调用GeoServer的WMTS服务时出现TileOutOfRange错误

问题根源 #

Mapbox GL默认采用EPSG:3857（Web墨卡托）的瓦片编码规则，而你请求的是GeoServer的EPSG:4326 WMTS服务，两者的缩放级、行列号（x/y）定义完全不匹配：

• EPSG:4326的WMTS瓦片矩阵，z级总行数为2^(z-1)，行号原点在左上角；
• Mapbox的EPSG:3857瓦片，z级总行数为2^z，行号原点在左下角；
• 你的图层缓存仅覆盖日本区域，Mapbox请求了缓存范围外的行列号，触发TileOutOfRange错误。

具体解决步骤 #

1. 动态转换瓦片行列号（核心修复） #

使用Mapbox的tileUrlFunction替代静态URL模板，将Mapbox的x/y/z转换为符合EPSG:4326 WMTS规则的参数：

map.on("load", () => {
  map.addSource("test", {
    type: "vector",
    tileUrlFunction: (tileCoord) => {
      const z = tileCoord.z;
      const x = tileCoord.x;
      // 将Mapbox的y值转换为EPSG:4326 WMTS的行号：反转原点+适配行数范围
      const y = (Math.pow(2, z - 1) - 1) - Math.floor(tileCoord.y / 2);
      return `http://<my_server>:8080/geoserver/gwc/service/wmts?REQUEST=GetTile&SERVICE=WMTS&VERSION=1.0.0&LAYER=myspace:japan&STYLE=&TILEMATRIX=EPSG:4326:${z}&TILEMATRIXSET=EPSG:4326&FORMAT=application/vnd.mapbox-vector-tile&TILECOL=${x}&TILEROW=${y}`;
    },
    generateId: true,
    minZoom: 0,
    maxZoom: 14,
  });

  map.addLayer({
    "id": "test",
    "type": "fill",
    "source": "test",
    "source-layer": "japan",
    "layout": { "visibility": "visible" },
    "paint": {}
  });
});

2. 开启GeoServer动态瓦片生成 #

如果缓存未覆盖所有需要的瓦片，可让GeoServer实时生成瓦片而非返回错误：

• 登录GeoServer后台，进入Tile Caching → Settings
• 勾选Allow non-cached requests选项，保存设置

3. 验证瓦片矩阵集一致性 #

确认GeoServer中使用的是默认EPSG:4326瓦片矩阵集：

• 进入Tile Caching → Tile Matrix Sets，查看EPSG:4326定义
• 确保每个z级的矩阵宽度为2^z，高度为2^(z-1)，无自定义修改

4. 限制Mapbox视图范围（可选） #

如果仅需查看日本区域，设置地图边界避免请求无效瓦片：

// 日本区域大致边界（EPSG:4326）
const japanBounds = [122.93, 24.40, 153.98, 45.56];
map.setMaxBounds(japanBounds);
map.fitBounds(japanBounds);

内容的提问来源于stack exchange，提问作者Takuyawe