Mapbox地图在Github Pages/Render部署后显示异常，本地运行正常求助

常见原因及修复步骤 #

1. 检查Mapbox Access Token的权限设置 #

• 登录Mapbox账号进入Access Tokens页面，确认token已开启Public API权限。
• 重点核对URL限制：如果设置了允许的域名，必须把Github Pages域名（如username.github.io）和Render部署的域名添加进白名单；如果之前没设置限制，可暂时关闭限制（清空所有域名）测试，确认是否是域名白名单导致的问题。

2. 确认代码中token的注入方式 #

• 避免硬编码token，通过环境变量传递：
  • Github Pages：在仓库Settings > Secrets and variables > Actions中添加REACT_APP_MAPBOX_TOKEN变量，代码里用process.env.REACT_APP_MAPBOX_TOKEN调用。
  • Render：在项目部署的Environment设置中添加同名环境变量。
• 换token后要同步更新所有部署环境的变量，否则部署后仍会使用旧值或空值。

3. 检查Mapbox GL JS依赖版本 #

• 旧版本可能和部署环境存在兼容性问题，执行命令更新依赖：

  npm update mapbox-gl @mapbox/mapbox-gl-react
  

• 确认package.json中依赖为最新稳定版。

4. 验证部署后的token是否生效 #

• 打开浏览器开发者工具（F12），切换到Network标签刷新页面，查看https://api.mapbox.com/styles/v1/mapbox/...这类请求的响应：
  • 返回401/403错误：说明token无效或权限不足；
  • 请求成功但地图灰色：检查是否有其他资源加载失败。
• 也可在控制台打印process.env.REACT_APP_MAPBOX_TOKEN，确认部署后token是否正确注入。

5. 核对Github Pages路由配置 #

• 若项目用到React Router，需在package.json中配置homepage字段：

  "homepage": "https://username.github.io/repo-name"
  

• 即使basic示例没用到路由，路径错误也可能导致地图资源加载失败。

6. 确认Mapbox样式URL正确性 #

• 检查代码中地图样式的URL是否有效，比如：

  mapboxgl.accessToken = process.env.REACT_APP_MAPBOX_TOKEN;
  const map = new mapboxgl.Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v12', // 确认此样式未废弃
    center: [-74.5, 40],
    zoom: 9
  });
  

• 避免使用已废弃的样式ID，比如旧版streets-v11可能已失效。

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