GitHub Actions中Percy运行失败：Invalid API token错误求助

操作背景 #

• 使用指定项目代码
• 克隆至本地Windows办公局域网环境，通过VSCode运行
• 在Percy平台创建项目并生成API Token
• 将Token配置到GitHub Secrets中
• 执行GitHub Actions流水线时触发报错：[percy] Error: Invalid API token

排查步骤 #

1. 验证Token本身有效性 #

• 登录Percy项目后台，核对复制的Token与生成的原始Token完全一致，重点排查是否包含多余空格、换行符等无效字符。
• 本地测试验证：在项目根目录的Windows命令行中执行set PERCY_TOKEN=你的Token内容，随后运行项目的Percy测试命令，若仍报Token错误，说明Token本身可能无效，需重新生成。

2. 检查GitHub Secrets配置准确性 #

• 进入目标GitHub仓库的「Settings」→「Secrets and variables」→「Actions」页面，确认添加的Secrets名称与流水线YAML文件中引用的名称完全匹配（大小写敏感）。例如YAML中写PERCY_TOKEN: ${{ secrets.PERCY_PROJECT_TOKEN }}，则Secrets名称必须为PERCY_PROJECT_TOKEN。
• 确认Secrets是添加在当前仓库下，而非个人账号或其他关联仓库。

3. 核对流水线YAML的Token传递逻辑 #

• 打开GitHub Actions的YAML配置文件，确认Token通过环境变量正确注入，示例格式如下：

  steps:
    - name: 执行Percy测试
      env:
        PERCY_TOKEN: ${{ secrets.YOUR_SECRET_NAME }}
      run: npm run percy
  

• 确保未在YAML中硬编码Token，且环境变量名为PERCY_TOKEN（Percy工具默认读取该变量）。

4. 排查办公局域网的网络限制 #

• 若使用自托管GitHub Actions Runner，需确认办公局域网的防火墙、代理规则未限制Runner访问Percy的API服务。可在流水线中添加测试步骤验证连通性：

  steps:
    - name: 测试Percy API连通性
      run: curl -v https://api.percy.io/v1/health
  

5. 检查项目代码中的Percy配置 #

• 查看项目内的percy.config.js或同类配置文件，确认未在配置中硬编码Token（硬编码值会覆盖环境变量中的Token）。

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