React项目生产环境maplibregl不显示、MapTiler瓦片加载失败问题

常见问题原因 #

• 密钥配置错误
  • 代码中的my-key没有替换为你在MapTiler后台申请的有效密钥，或者密钥已过期、被停用
  • 密钥在MapTiler后台设置了域名/IP白名单限制，当前运行环境的域名（比如本地开发的localhost:3000）没有被加到白名单中
• 地图初始化参数冲突
  你的初始化代码同时传入了center/zoom和bounds/fitBoundsOptions两组定位参数，两类参数在初始化时会互相干扰，导致地图计算初始瓦片坐标时逻辑异常，你当前报错的瓦片请求层级是z=2，和你设置的初始层级z=13完全不符，属于参数冲突导致的典型表现
• 样式与瓦片服务权限不匹配
  你使用的MapTiler密钥没有开通对应v3矢量瓦片服务的访问权限，或者你选用的basic基础样式对应的瓦片版本和请求的v3版本不兼容
• 网络访问限制
  本地网络环境（比如公司内网、代理）拦截了MapTiler的pbf瓦片请求，或者请求头的配置不符合MapTiler的接口要求

对应解决方案 #

1. 先校验密钥有效性：
   直接在浏览器地址栏访问你用到的style.json地址（替换my-key为你的实际密钥），如果能正常返回JSON数据就说明密钥本身有效，否则去MapTiler后台确认密钥状态和白名单配置
2. 修正初始化参数冲突：
   删除重复的定位参数，要么保留center和zoom，要么保留bounds和fitBoundsOptions，不要同时传入。修正后的代码示例：

   // 仅保留bounds相关定位逻辑的示例
   map = new maplibregl.Map({
       container: 'map',
       style: 'https://api.maptiler.com/maps/basic/style.json?key=替换为你的实际密钥',
       renderWorldCopies: true,
       bounds:[listShips[0].geometry.coordinates,listShips[1].geometry.coordinates],
       fitBoundsOptions: {padding: 300}
   });
   

3. 确认服务权限：
   去MapTiler后台确认你的账户已经开通了矢量瓦片v3版本的访问权限，也可以更换为官方兼容的测试样式地址做对比验证
4. 排查网络问题：
   打开浏览器开发者工具的网络面板，查看pbf请求的具体报错状态码：
   • 403：优先确认密钥权限和白名单配置
   • 404：确认瓦片地址、样式版本是否正确
   • 跨域错误：检查本地是否有反向代理篡改了请求头

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