Expo EAS构建失败：Mapbox令牌缺失致Install pods报错

核心问题定位 #

构建时下载MapboxCommon返回403，本质是使用的令牌缺少DOWNLOADS:READ权限，或构建环境未正确传递令牌。

具体解决步骤 #

1. 生成带下载权限的Mapbox令牌 #

• 登录Mapbox控制台进入Access Tokens页面
• 创建或编辑现有令牌，务必勾选DOWNLOADS:READ权限
• 复制生成的pk开头的public令牌

2. 配置Expo环境变量 #

• 方式一：在Expo Dashboard项目设置中添加环境变量MAPBOX_DOWNLOAD_TOKEN，值为上述令牌
• 方式二：本地项目根目录创建.env文件，添加MAPBOX_DOWNLOAD_TOKEN=pk.eyJ1Ijoi...（确保.gitignore包含.env避免令牌泄露）

3. 更新app.config.js配置 #

修改插件配置，通过环境变量传递令牌，避免硬编码：

plugins: [
  [
    '@rnmapbox/maps',
    {
      RNMapboxMapsImpl: 'mapbox',
      RNMapboxMapsDownloadToken: process.env.MAPBOX_DOWNLOAD_TOKEN,
    },
  ]
]

4. 验证环境变量传递 #

• 运行eas build:configure确保EAS构建能读取环境变量
• 云构建需确认Expo Dashboard的环境变量已保存启用；本地构建需确保.env文件正常加载

5. 清理缓存重试 #

• 清理Expo缓存：expo r -c
• 清理CocoaPods缓存：进入ios目录执行pod cache clean --all
• 重新触发构建：eas build

额外注意事项 #

• 区分运行时令牌和下载令牌：前者用于地图渲染，后者仅用于构建依赖下载，两者均为pk开头，但下载令牌必须具备DOWNLOADS:READ权限
• 确认@rnmapbox/maps版本与当前Expo SDK版本兼容，建议使用最新稳定版

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