GitHub Actions 步骤并行怎么验收：background、wait-all 与日志边界

一个前端仓库的 CI job 里，单元测试、接口契约检查和文档构建互不依赖，却要排队跑完再打包。以前常见的做法是把命令写成 shell 后台任务，结果日志混在一起，某个检查提前退出时也很难判断整个 job 到底该不该继续。GitHub Actions 新增步骤级并行关键字后，可以把这些独立步骤拆开运行，同时保留每个步骤自己的日志。

先把流水线基线量出来

先拿一个有三个独立检查的 job 做基线：单元测试耗时 4 分 20 秒，接口契约检查耗时 2 分 10 秒，文档构建耗时 1 分 40 秒。过去三步串行，理论总时长接近 8 分钟，再加上 runner 准备和缓存恢复，Pull Request 的反馈经常超过 9 分钟。

这个数字只是第一步。还要记下每个步骤是否会写入同一个目录、是否会启动本地服务、失败后是否允许后续步骤继续。若三个步骤会同时改写同一个生成目录，单纯加并行关键字很可能把时间优化的问题换成文件互相覆盖的问题。

background 与 wait-all 分别解决什么问题

官方更新说明里提到的核心变化是：步骤可以用 background: true 异步启动，后续步骤不必立刻停住；需要汇合时，用 wait 等待指定步骤，或用 wait-all 等待之前所有后台步骤。这样每个步骤的输出仍然各自归档，不必把多个命令的输出拼到同一个 shell 进程里。

steps:
  - name: 单元测试
    id: unit
    run: go test ./...
    background: true

  - name: 接口契约检查
    id: contract
    run: ./scripts/check-contract.sh
    background: true

  - name: 文档构建
    id: docs
    run: npm run docs:check
    background: true

  - name: 汇合并生成报告
    run: ./scripts/build-report.sh
    wait-all: true

上面的写法把“启动检查”和“汇合生成报告”分成两个阶段。报告步骤只有在三个后台步骤都结束后才开始，因而可以安全读取测试结果。这里别急着把所有步骤都标成后台：需要前置产物的步骤仍应保持顺序，或者明确放在等待点之后。

用 parallel 简化同一组并行任务

如果一组步骤只是“同时开始，全部完成后继续”，可以使用 parallel 语法表达同一个意图。它本质上是把组内步骤转成后台步骤，并在组末尾放置等待点，适合多个独立构建或多套静态检查。

steps:
  - parallel:
      - name: Linux 构建
        run: make build-linux
      - name: macOS 构建
        run: make build-macos
      - name: 文档检查
        run: npm run docs:check

  - name: 汇总工件
    run: ./scripts/collect-artifacts.sh

使用简写前，要确认组内命令没有隐含的先后关系。例如两个构建都写入 dist/，即使编译本身互不依赖，收集工件时也可能遇到同名文件覆盖。更稳妥的做法是每个步骤写入 dist/linux、dist/macos 等独立目录。

把总时长和有效反馈一起验收

以开头那组三项检查为例，理想状态下并行后的总耗时接近最长的 4 分 20 秒，而不是三个时长简单相加。实际测量要固定 runner 类型、分支、缓存状态和输入提交，连续跑几次再比较中位数，避免一次网络抖动影响结论。

除了时长，还应观察失败反馈是否符合预期。比如接口契约检查在 40 秒时就失败，系统仍可能等待另两个后台步骤结束后才进入汇总；这不等于失败被吞掉。你需要在汇总步骤和 job 结果里确认失败状态按预期传播，不能只看最后一个脚本返回 0。

长驻服务要配合 cancel 做收尾

另一个典型场景是先启动本地 API 服务，再让浏览器测试访问它。服务可以作为后台步骤启动，但测试结束后应该用 cancel 停掉它，避免占用 runner 资源，也避免后续步骤误连到旧端口。

steps:
  - name: 启动本地 API
    id: api
    run: ./scripts/start-api.sh
    background: true

  - name: 等待服务就绪
    run: ./scripts/wait-api-ready.sh
    wait: api

  - name: 浏览器检查
    run: npm run browser:check

  - name: 停止本地 API
    run: ./scripts/stop-api.sh
    cancel: api

这里的关键不是把服务“放到后台”就结束，而是给它清晰的启动、就绪、使用和停止边界。如果就绪检查失败，也要让收尾动作能够执行；生产仓库中可以再配合临时目录清理和端口占用检查，避免重试时留下脏状态。

常见问题

background: true 会让整个 job 立刻成功吗？

不会。它只改变当前步骤的推进方式。后续可以用 wait 或 wait-all 等待结果，最终仍要按工作流的失败传播规则检查 job 状态。

什么时候应该用 wait 而不是 wait-all？

当后一步只依赖某一个后台步骤时，用 wait 指定它更省等待时间；需要读取多个检查结果或统一生成报告时，再用 wait-all。

并行步骤能不能共用同一个输出目录？

能否共用取决于写入是否互斥，但实践中更建议按步骤或目标平台分目录，最后在汇总阶段统一收集。这样更容易定位覆盖和缺文件问题。

parallel 和 matrix 是一回事吗？

不是。parallel 解决同一个 job 内步骤的并行与汇合；matrix 通常用于按多个参数组合展开 job。两者可以分别使用，但资源消耗和日志组织方式不同。

上线前的四项复查

把串行 job 改成并行后，至少保留一次对照记录：同一提交下的总时长中位数、每个步骤的独立日志、失败状态是否能传到汇总、以及共享目录和后台服务是否被正确清理。只要其中一项说不清，先缩小并行范围，再逐步扩大到更多检查。