MapProxy请求瓦片超出范围问题排查求助

问题重现 #

配置自定义CRS（EPSG:XXXX）的MapProxy服务器后，手动访问TMS瓦片URL时收到错误：

<TileMapServerError>
<Message>The requested tile is outside the bounding box of the tile map.</Message>
</TileMapServerError>

确认请求的z/x/y在EPSG:XXXX范围内，但仍被判定超出；尝试修改origin无效，且同CRS在Proj4Leaflet中可正常工作。

配置文件如下：

services:
  demo:
  tms:
    use_grid_names: true

layers:
  - name: my_layer
    title: My example layer
    sources: [my_cache]

caches:
  my_cache:
    grids: [my_grid]
    disable_storage: true
    sources: [my_source]
    format: image/jpg

sources:
  my_source:
    type: tile
    url: https://example_tile_url/%(z)s/%(x)s/%(y)s.jpg
    grid: my_grid

grids:
  my_grid:
    srs: 'EPSG:XXXX' # 自定义SRS
    bbox: [w, s, e, n] # 取自EPSG官网的WGS84 Bounds
    bbox_srs: 'EPSG:4326'
    origin: sw
    res: [1000,9000,8000...] # 13个分辨率值（m/px）
    tile_size: [256,256]
    num_levels: 12

globals:
  image:
    formats:
      image/jpg:
        encoding_options:
          jpeg_quality: 100

排查步骤与解决方案 #

1. 验证WGS84 BBox到目标SRS的转换正确性 #

MapProxy会自动将bbox_srs: EPSG:4326定义的边界转换为目标SRS坐标，若转换出错会导致网格边界不符合预期：

• 手动用Proj4工具转换WGS84 BBox的四个角点到EPSG:XXXX，比如使用proj命令行：

  echo "w s" | proj +init=EPSG:4326 +to=EPSG:XXXX
  echo "e n" | proj +init=EPSG:4326 +to=EPSG:XXXX
  

• 将转换后的坐标直接作为bbox值，同时删除bbox_srs配置，避免自动转换的误差。

2. 修正分辨率数组与层级数的匹配 #

配置中res数组有13个值，但num_levels设为12，会导致层级对应混乱：

• MapProxy的res数组索引对应层级（从0开始），需保证num_levels和res数组长度一致，或直接删除num_levels，让MapProxy自动根据res长度计算层级数。

3. 确保自定义SRS的Proj4定义被正确加载 #

MapProxy依赖Proj4处理坐标转换，若EPSG:XXXX是非标准内置CRS，需手动传入Proj4定义：

• 在配置的globals节点添加自定义SRS的Proj4参数（即你在Proj4Leaflet中使用的定义）：

  globals:
    srs:
      proj_data:
        EPSG:XXXX: "+proj=xxx +ellps=xxx +datum=xxx +units=m +no_defs"
  

• 重启MapProxy，查看启动日志是否有SRS加载错误。

4. 排查TMS与XYZ瓦片行号的差异 #

TMS规范的行号（y）从南到北递增，而多数瓦片源（如XYZ）是从北到南递增，即使origin设置正确，也可能因行号规则不匹配报错：

• 在sources.my_source中添加reverse_y: true反转行号：

  sources:
    my_source:
      type: tile
      url: https://example_tile_url/%(z)s/%(x)s/%(y)s.jpg
      grid: my_grid
      reverse_y: true
  

5. 用MapProxy工具验证网格计算 #

使用mapproxy-util grid-info命令查看自定义网格的详细信息，确认各层级的瓦片范围是否符合预期：

mapproxy-util grid-info --config your_config.yaml my_grid

该命令会输出每个层级的瓦片min/max x/y值，对比你请求的坐标是否在范围内，快速定位是坐标转换还是网格配置问题。

内容的提问来源于stack exchange，提问作者Ariel K.