GitHub Pages部署异常：v3找不到工件 v4部署失败（附日志）

问题1：actions/deploy-pages@v3 无法识别已上传的 coverage-report 工件 #

原因 #

actions/upload-artifact@v4 与 deploy-pages@v3 存在版本兼容性冲突。v4 版本的上传工件动作对存储和检索机制做了更新，而 v3 版本的部署动作未适配该机制，导致无法找到已上传的工件。

解决方法 #

升级 deploy-pages 至 v4 版本（你已完成此操作），或降级 upload-artifact 至 v3 版本以保持版本匹配。

问题2：actions/deploy-pages@v4 识别到工件但部署失败 #

核心原因及修复方案 #

1. 工件缺少默认入口文件 index.html

GitHub Pages 部署要求根目录下存在 index.html 作为默认访问入口，而你生成的覆盖率报告文件名为 coverage-report.html，不符合 Pages 的访问规则，这是最可能的失败原因。

修复：
修改报告生成步骤，直接将输出文件命名为 index.html：

# 修改 Generate coverage report 步骤中的输出文件名
go tool cover -html=$COVERAGE_FILE.out -o index.html
# 更新输出变量
echo "report-file=index.html" >> $GITHUB_OUTPUT

对应的完整步骤片段：

run: |
  PKG_DIR="${{ inputs.package-directory || './...' }}"
  COVERAGE_FILE="${{ inputs.coverage-file || 'coverage-report' }}"
  go test -race -coverprofile=$COVERAGE_FILE.out $PKG_DIR
  go tool cover -html=$COVERAGE_FILE.out -o index.html
  COVERAGE_PERCENTAGE=$(go tool cover -func=$COVERAGE_FILE.out | grep total: | awk '{print substr($3, 1, length($3)-1)}')
  if (( $(echo "$COVERAGE_PERCENTAGE < ${{ inputs.coverage-threshold }}" | bc -l) )); then
    echo "Error: Coverage $COVERAGE_PERCENTAGE% is below the required threshold of ${{ inputs.coverage-threshold }}%"
    exit 1
  fi
  echo "report-file=index.html" >> $GITHUB_OUTPUT

2. GitHub Pages 配置异常

检查仓库 Pages 设置：

• 确认部署来源选择为 GitHub Actions，而非分支或静态文件夹
• 若配置了自定义域名，暂时移除域名配置后重新测试部署

3. 部署权限不足

默认的 github.token 可能缺少 Pages 部署的完整权限。创建一个具备 repo 和 pages:write 权限的个人访问令牌（PAT），存储为仓库密钥（如 PAGES_DEPLOY_TOKEN），替换部署步骤中的令牌：

- name: Deploy to GitHub Pages
  id: deployment
  uses: actions/deploy-pages@v4
  with: 
    artifact_name: coverage-report
    token: ${{ secrets.PAGES_DEPLOY_TOKEN }}

4. 工件内容验证

查看工件内的 HTML 文件是否损坏：可手动下载工件（日志中提供的下载 URL），解压后在本地浏览器打开确认文件正常。

验证步骤 #

1. 重新运行流水线，确认工件上传和部署步骤的日志输出
2. 访问日志中给出的 status_url，查看 GitHub Pages 部署的详细失败原因
3. 若暂时无法修改文件名，可尝试直接访问完整路径（如 https://sonichigo.github.io/mux-postgresQL/coverage-report.html）确认文件是否可访问

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