← 返回全部文章

拆掉一条 3,744 行的流水线,再用它撑过发售周末

发布于: 最近更新:
candyrushci-cdtoolingevidence

今年 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 秒,却能从关键路径上省下大约十分钟。

在保留它之前,我先测量了:

设计EditModePlayMode构建墙钟时间
单体(一个 job)10m14s15m31s~46m72m09s
三路拆分24m25s18m27s69m23s69m
两路(套件 ∥ 构建)合计 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 配置的问题不在于它们长,而在于只有一部分 仍然是正确的。