拆掉一条 3,744 行的流水线,再用它撑过发售周末
今年 8 月,CandyRush 的 Unity 构建流水线是一个 3,744 行的 ci.yml。这一个文件
负责运行测试套件、四个平台的构建、制品发布、跨制品的确定性校验、性能回归闸、
Discord 通知,以及三条 Steam depot 通道。我把它拆开了。十周之后,它支撑了游戏在
Steam 上的发售。
下面是变化的结果,数据来自通过 GitHub API 拉取的 1,290 次 workflow 运行 (2026 年 6 月至 11 月;重构大约在 8 月 26 日落地):
| 之前(7 月至 8 月 25 日) | 之后(8 月 26 日至 11 月 2 日) | |
|---|---|---|
| 拉取请求检查通过率 | 6%(7 月),66%(8 月 1-25 日) | 93%(9 月),100%(10 月、11 月) |
| 拉取请求检查中位耗时 | 约 28 分钟,每个 PR 都跑完整 Unity 套件 | 约 1 分钟;套件每次推送只跑一次 |
| 每个活跃日的流水线总耗时 | 348 分钟(8 月初) | 207 分钟(10 月) |
正式发布(main)部署 | — | 8 次全部成功,包括 11 月 1-2 日的发售周末 |
流水线在底层大改的同时,产出没有掉:8 月合并了 144 个拉取请求,9 月 80 个, 10 月 82 个。
本文接下来讲的是怎么做到的,包括一次经过测量后撤回的并行化,以及四个各自变成 了永久闸的缺陷。
起点
这种文件总是这样长大的。8 月初 1,039 行,19 日 2,082 行,22 日 3,547 行, 当天又涨到峰值 3,744 行。
真正的问题不是体积,而是重复:
- rclone 安装配置:十份逐字相同的副本
- Unity 互斥锁 + 启动 + 结果检查块:七份副本
- R2 环境变量块:十四份副本
而且它们已经各自走样。有的 rclone 副本会静默回退到工具缓存,有的会记录安装日志, macOS 的副本带了一个 Windows 副本没有的架构切换。七个 Unity 构建块里, 只有一部分会检查是否真的产出了可执行程序。这很重要,因为 Unity 什么都没构建 却以零退出的情况,比任何人希望的都要常见。
推动这次重构的不是整洁,而是第二款游戏。写下来的目标是:复制 .github/、设置
几个仓库变量就能启动下一个项目,不改任何 YAML。每一个写死的 Steam app ID、
depot 编号、构建者命名空间和存储桶前缀,都是这个目标的障碍。
第一波:拆分之前先测量
测试套件作为一个 job 运行(先 EditMode,再 PlayMode,再构建),墙钟时间 72 分钟。显而易见的做法是拆成三个并行 job。
算术看起来没问题。每个 job 的前置步骤(清理工作区、准备 vendor 包、包清单、 解析编辑器)实测 21 秒。付三次大约多花 42 秒,却能从关键路径上省下大约十分钟。
在保留它之前,我先测量了:
| 设计 | EditMode | PlayMode | 构建 | 墙钟时间 |
|---|---|---|---|---|
| 单体(一个 job) | 10m14s | 15m31s | ~46m | 72m09s |
| 三路拆分 | 24m25s | 18m27s | 69m23s | 69m |
| 两路(套件 ∥ 构建) | 合计 46m03s | ~55m |
三路拆分只省了约 4%。两路拆分省了 25%,最终上线的就是它。
测量也解释了原因。CPU 密集的 EditMode 套件在三路拆分下慢了 2.4 倍,因为 三个 runner 槽位其实是同一台物理机上的实例。 第三个并发的 Unity 编辑器没有 增加任何算力,只是把同一台机器切得更碎。
前置步骤的算术是对的,但无关紧要。问题从来不是拆分的成本,而是机器有没有余量 可以拆分进去。
定在两个槽位之后,还顺带删掉了只为三路拆分而存在的机制:整个 report job、
结果 XML 的制品传递,以及两个按套件汇总的步骤。测量结果现在写在 workflow 自己的
头部注释里,免得有人无意中重做这个实验。过程中提取出来的复合 action 留下了,
重复的前置步骤也再没回来。
第二波:拆解
三天后是真正的重构:
.github/actionlint.yaml | 27 +
.github/workflows/_tests.yml | 419 +++++
.github/workflows/cd.yml | 2532 ++++++++++++++++++++++++++++++
.github/workflows/ci.yml | 3530 ++++--------------------------------------
4 files changed, 3319 insertions(+), 3189 deletions(-)
ci.yml 从 3,273 行降到 425 行。
按触发器拆,而不是串成链
直觉是用 workflow_run 把 CI 串到 CD。别这么做。这个触发器运行的是
默认分支上的那份 workflow,并且会丢失触发它的 ref,这会让所有从功能分支发起
的手动派发全部失效。
所以改为按触发器拆分。ci.yml 在拉取请求上运行;cd.yml 在推送到
dev/qa/main 以及手动派发时运行。每个事件只触发其中一个。测试套件放在可复用
的 _tests.yml 里,每次推送最先运行且只运行一次,部署通道以它的输出为闸。这就是
拉取请求检查降到一分钟左右的原因:同一个改动不再跑两遍套件。
三条通道,一份实现
git dev -> Steam "development" automatic
git qa -> Steam "qualityassurance" automatic - the merge into qa IS the gate
git main -> default branch uploads only; promotion is a human
Steam 的分支名不能和 git 分支名一致:Steamworks 要求 4-32 个字符,所以 dev 和
qa 在创建时都会被拒绝。我是在接好一张根本不可能生效的映射表之后才发现这一点的。
为什么这些通道不能合并成一个 job:Actions 里的 needs: 是静态的。 一个 job
没法等待"恰好运行了的那一对"。单一的部署 job 需要依赖全部五个上游,再加上分支
逻辑来判断自己在哪条通道,这种结构看起来没问题,失败时却难以读懂。所以这个 452 行
的部署 job 变成了一个 694 行的可复用 workflow,加上四个只在参数上不同的薄调用方。
策略上的差异是输入参数,而不是代码分支。dev 通道刻意不以测试套件为闸:套件红了
不应该让你失去制品。生产通道有闸,因为坏的 dev 构建只需重新部署,而 qa 或
main 上坏的 Steam 构建是永久的。
永远不要 always()
一次清理从 job 图中五处删掉了 always()。原因很具体:即使整个运行被取消,
always() 也返回 true,而 CD 的并发组会取消正在进行的运行。于是:dev 推送 A 的
两个构建都通过了,推送 B 取代并取消了运行 A,而运行 A 的部署照样触发,把一个已被
取代的提交发到 Steam 并设为上线。Steam 构建无法删除。 替代写法是 !cancelled()。
五个复合 action
每一个都替换了已经走样的重复代码:
unity-workspace(272 行):从检出到调用编辑器之间的一切。刻意不检出 仓库,因为本地 action 本身就是从工作区加载的。unity/build-player(144 行):在主机全局锁下执行一次 Unity 批处理构建, 并如实报告结果。非零退出是红,零退出却没有产出可执行程序同样是红。它自身总是以 0 退出并通过输出报告结果,这样 Linux 构建失败不会连累 Windows 的压缩包。rclone/setup(134 行):每个 runner 只把 rclone 解析进工具缓存一次。刻意 不把 R2 凭据作为输入,否则为了省六行代码,就要把凭据的作用范围从一个步骤扩大到 整个 job。git-bash(76 行):在自托管的 Windows runner 上,PATH 里的bash是 WSL 启动器,它会搞乱 Windows 脚本路径。unsparse-workspace(51 行):见下文。
有两个约束决定了它们的形态:复合 action 在调用方的 job 和工作区内运行(可复用
workflow 则是在自己 runner 上的完整 job),以及复合 action 无法读取 secrets
上下文。
四个缺陷,四道永久的闸
这种规模的重构一定会暴露缺陷。目标是每个缺陷只由人发现一次,之后都交给机器。 下面每一个现在都是一项会以非零退出的检查。
描述字段里的表达式
提取 unity-workspace 之后的第一次运行:三个 Unity job 在一分钟内全部停止,报错
Unrecognized named-value: 'secrets'。action.yml 第 19 行,也就是输入描述,
写着"调用方必须传入 ${{ secrets.UTOOLS_PAT }}"。GitHub 会对描述字段中的模板
表达式求值,而 action 没有 secrets 上下文。
同一类问题,出现在 shell 注释里
三天后,run: 块里的一条解释性注释写着"调用方传入
${{ vars.VENDOR_PACK_HOST_ROOT }}"。shell 注释对 runner 来说并不是注释:表达式在
action 加载时就会被校验。
之所以没被拦住,是因为三个不同的盲区:actionlint 根本不检查 action.yml 文件;
我们的语法检查器在解析之前就把每个 ${{ }} 替换成了普通标记,表达式已经不在了;
而我们的 workflow linter 只遍历 doc['jobs']。三个缺口现在都已补上。
日志里写着 PASSED 的误报红
GitHub 会在每个 shell: powershell 步骤末尾追加 exit $LASTEXITCODE。PowerShell
cmdlet 不会重置 $LASTEXITCODE。所以一个步骤如果先运行原生命令、判断其失败无关紧要、
再用 cmdlet 收尾,最后仍然会失败,带着它刚刚放过的那条命令的退出码。
来自一次真实运行的日志:
tar entry for the player: -rwxr-xr-x 0 root root 4672 linux/CandyRush
Linux executable bit PASSED (0755 in the ustar stream).
##[error]Process completed with exit code 1.
根本原因:tar.exe ... | Where-Object {...} | Select-Object -First 1 一找到匹配就
终止管道,导致通往 tar.exe 的管道断开,留下非零的 $LASTEXITCODE。镜像方向的风险
也存在:一个只应发出警告的上传步骤,可能在写入 ok=true 之后让整个构建 job 失败。
这类问题出现过四次,每次都是靠人读 diff 发现的。现在它是一条 linter 规则。
把每个 run: 块当成真代码去解析
一次机械式批量修改把写死的列表换成了由变量驱动的循环,却留下了旧代码块末尾的 }。
YAML 合法。actionlint:零。我们的 workflow linter:零。到了 runner 上,排队几分钟后
必然是解析错误。
于是 check-step-syntax.py 提取每个 run: 块,把表达式替换成普通标记(也就是 shell
实际收到的内容),再交给对应语言的真实解析器:PowerShell 自己的 AST 解析器,以及
bash -n。
有两个细节值得借鉴。第一,它推断 shell,而不是相信标注,因为 shell: bash 不是
空操作:隐式默认值是 bash -e,而显式的 shell: bash 是
bash --noprofile --norc -eo pipefail。把它写出来会给已有的管道步骤新开启
pipefail,可能让原本通过的 job 变红。语法闸不能为了安装自己而改变运行时行为。
第二,第一个版本为每个步骤启动一个解释器:77 次 PowerShell 启动,大约 9 秒的进程 开销,只为了做大约 200 毫秒的解析。改成一次批量调用后,从 9.7 秒降到 0.95 秒。
追踪 job 图
第四道闸会用十一种真实的触发形态去求值每个 job 的 if:,如果某个 job 在所有形态下
都不可达就失败。二十个 job 乘以十一种形态,就是 220 个答案;改一个条件会悄悄改变
其中一部分,而这些在 diff 里都看不出来。
它第一次运行就发现一个 builds job:执行完整个前置步骤,然后跳过了所有构建步骤,
而且恰好发生在发布永久 Steam 构建的那种派发上。原因是四层叠加的否定条件,每次出现
新的派发开关时加一层,已经没人能靠阅读算出结果。
让闸证明自己真的检查过
有一次运行失败,报错 could not read ".github/workflows/*.yml":因为 bash 没有任何
东西可展开,字面上的通配符被直接传给了 actionlint。工作区被裁剪过了。
actions/checkout 会开启 sparse-checkout,而且永远不会关掉它,而我们工具 runner
的工作区是共享且持久的。有一个 job 多年来一直做稀疏检出,在临时的托管 runner 上这完全
正确。把它搬到自托管机器上,前提变了,检出方式却没变。
更有价值的发现是:在同一次被裁剪的运行里,三道自研闸中有两道会找到零个文件、循环零次, 然后报告成功。第三道有输入检查,问题才以红色步骤的形式暴露出来。
现在它们在输入缺失时都会失败,并且每一道都在空目录下做过反向测试。另有一个小 action 负责关闭 sparse 模式,然后断言目录树是完整的。
十周之后
开头的数字就是结果:拉取请求检查约一分钟完成,通过率 93-100%,每一次正式发布部署都 成功了,包括发售周末的两次。
有两件事还没完成,我宁愿直接说明:
dev部署通道仍然不稳定。它已完成的运行中大约一半失败,而推送流水线的中位运行时间 到 10 月从约 31 分钟升到了 59 分钟。它的许多取消是设计使然(较新的推送会取代较旧的 运行)。这条通道上的失败代价很低,但它是下一个要收紧的地方。- "下一款游戏只需设置仓库变量、不改 YAML"这个目标,已经为此做好了设计,但尚未被证明: 目前还没有第二款游戏采用这条流水线。
现在这条流水线是分布在六个文件中的 5,588 行 workflow,而不是一个 3,744 行的文件, 另有 677 行复合 action 和 2,741 行脚本。它没有变小。它变得可拆分、可参数化、有闸, 而且它把游戏发布了出去。
可以泛化的部分
测量机器,而不是算术。 三路拆分对前置步骤的计算是对的,对硬件的假设是错的。 一台机器上的三个 runner 槽位不是三台机器。先测量,把一个只省 4% 的想法变成了省 25% 的 结果。
依赖记忆的闸不是闸。 四个缺陷都曾由人读 diff 发现过一次。现在每一个都是会以非零 退出的检查。
什么都没找到的检查必须证明它找过。 一个默默验证空集合的 linter,只会给出一个毫无 意义的绿勾。
重复的代价是走样,而不是行数。 十份 rclone 配置的问题不在于它们长,而在于只有一部分 仍然是正确的。