GitHub Actions 怎样把构建结果写进 Job Summary

GitHub Actions 的 Job Summary 不是另外上传一份日志，而是把 Markdown 写入当前步骤提供的 GITHUB_STEP_SUMMARY 环境文件。最小做法是在 workflow 的某个步骤中使用 >> 追加标题、检查结果和列表；作业结束后，读者可以在 Actions 运行详情的摘要区域直接查看。

官方地址：https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands

下面用一个构建摘要场景说明入口、写法、界面位置和边界。示例中的仓库名、工作流名和结果文字都是演示数据，不代表真实运行截图。

先确认摘要写入入口

编辑仓库里的 .github/workflows/ci.yml，在需要汇总结果的 job 中找到一个步骤。这里不需要新增 artifact，也不需要把日志重新抓取到脚本里；只要把 Markdown 写入 GitHub Actions 为当前步骤提供的 GITHUB_STEP_SUMMARY 文件即可。

如果使用 GitHub 网页端，路径是：仓库首页 → .github → workflows → 选择 workflow 文件 → 点击编辑按钮。保存前先确认写入摘要的步骤位于目标 job 内，而不是误放到另一个 job。

在步骤中追加构建信息

最小写法可以先写一个标题，再追加检查项。Shell 的 >> 表示追加，连续写入时每次会形成新的行，适合把测试数量、构建产物名称或部署前检查结果组织成一段简短 Markdown。

name: CI

on:
  push:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build and write summary
        shell: bash
        run: |
          # 用追加方式写入当前步骤的 Job Summary
          echo "## 构建摘要" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY" # 空行让 Markdown 更易读
          echo "- 分支：${GITHUB_REF_NAME}" >> "$GITHUB_STEP_SUMMARY"
          echo "- 提交：${GITHUB_SHA:0:7}" >> "$GITHUB_STEP_SUMMARY"
          echo "- 结果：构建步骤已完成" >> "$GITHUB_STEP_SUMMARY"

关键点只有三个：变量要用双引号包住，避免路径或内容出现空格时被 shell 拆开；需要保留前面内容时使用 >>，不要误写成覆盖用的 >；如果要写多行 Markdown，可以继续追加，也可以使用 heredoc，但要让分隔符保持独立一行。

保存后，在 workflow 文件顶部点击 Commit changes，再从仓库的 Actions 菜单选择对应工作流。若只想改变摘要内容，通常只需修改这个步骤，不必改变 job 的触发器。

从运行详情页核对 Job Summary

打开仓库 → Actions → 选择工作流 → 选择一条运行记录 → 点击目标 job。进入运行详情后，摘要会按 job 聚合显示；如果多个步骤都写入摘要，它们会被合并到同一个 job summary 中。

看到“构建摘要”、分支名和结果列表，说明写入位置和 Markdown 结构都符合预期。这里核对的是页面上的摘要区域，不要把单个步骤的日志输出误当成 Job Summary；日志仍然保留在各自步骤的展开面板里。

步骤隔离和覆盖语义要分清

GITHUB_STEP_SUMMARY 对当前步骤是唯一的文件入口，不同步骤各自拥有独立文件。一个步骤追加的内容不会直接改写另一个步骤已经上传的摘要；作业完成后，平台再把这些步骤摘要组合起来展示。

如果当前步骤需要重新生成摘要，可以用单个 > 覆盖本步骤此前写入的内容；如果只是补充测试列表、警告或构建元数据，应继续用 >>。摘要适合给人快速阅读，不适合承载完整日志或大型报告。官方文档还说明了单步内容大小和作业中摘要数量的限制，因此长报告应放到 artifact，再在摘要里保留链接或短结论。

常见问题

为什么写了 echo 却看不到摘要？先确认命令写入的是 GITHUB_STEP_SUMMARY，并且查看的是该次运行的 job 详情，而不是普通日志列表。

多个步骤能共用同一份摘要吗？它们不能直接共享同一个步骤文件，但平台会在 job 级别聚合各步骤上传的摘要。

什么时候应该用 artifact？需要下载完整测试报告、覆盖率文件或较大诊断材料时使用 artifact；Job Summary 只保留标题、结论和少量关键字段。

小结