在 Mac mini M4 云主机上搭建 iOS CI/CD 全流程

在团队规模变大之后，"谁的电脑能出包"这件事本身就会变成瓶颈。我们把 iOS 项目的 CI/CD 整体迁移到 Kvmzen 的 Mac mini M4 云主机之后，出包等待时间明显缩短，签名事故也几乎归零。这篇手记记录了从零搭建这套流水线时踩过的坑，以及最终收敛出来的 Fastfile 与缓存策略，供同样在评估云端 Mac 的团队参考。

为什么选择云端 Mac mini M4 做 CI/CD

Xcode 的构建是典型的"计算密集 + 强依赖系统版本"的任务，本机 Runner 很难长期稳定维护。选择云端 Mac 节点主要基于三点判断：

• 规格可控：镜像固定 Xcode 与命令行工具版本，不会因为某人手动升级系统而"团队里只有他能编译"。
• 随时扩容：发版前的回归测试可以临时多开几个节点并行跑，跑完即释放，不用为峰值常年预留硬件。
• 7×24 值守：M4 芯片待机功耗低，夜间构建、定时安全扫描都可以放心常驻运行，不用担心电费或噪音。

我们踩过的第一个坑：以为「云主机」等于「远程显示器」，只用它做手动打包。真正把收益吃透，是把它接入 CI 触发链之后才开始的。

CI/CD 流水线设计

阶段划分

一次完整的发版流水线，我们拆成了四个阶段：

1. 代码拉取与依赖解析（SPM / CocoaPods）
2. 单元测试与静态分析（并行执行）
3. xcodebuild archive 归档与签名
4. 上传 TestFlight 并通知值班群

钩子与触发条件

main 分支的每次合并会自动触发阶段 1-2；只有打上 release/* 标签才会继续跑阶段 3-4，避免每次小改动都消耗签名配额。本地调试 Fastlane 脚本时，我们习惯先用 Ctrl+C 中断一次完整跑批，单独重跑失败的那一步，能省下不少等待时间。

示例 Fastfile 片段

lane :ci_archive do
  cocoapods
  run_tests(scheme: "Kvmzen")
  build_app(
    scheme: "Kvmzen",
    export_method: "app-store",
    output_directory: "./build"
  )
  upload_to_testflight(skip_waiting_for_build_processing: true)
end

这段脚本本身并不复杂，关键是要让它在同一套镜像基线上重复运行都能得到一致结果——这也是我们把镜像版本号写进构建日志的原因，方便回溯某次失败是环境问题还是代码问题。

缓存与依赖管理

缓存没配好，云端构建的速度优势会被下载依赖的时间吃掉。下面是我们线上跑了三个月后总结的对照表：

几个术语的口径先对齐一下：

DerivedData

Xcode 的增量编译产物缓存目录，跨构建复用可以显著缩短二次编译时间。

SPM 缓存

Swift Package Manager 拉取到本地的包源码与解析结果缓存，避免每次构建都重新拉取远端仓库。

镜像基线

云主机开机即用的系统快照，包含固定版本的 Xcode、CLT 与预热好的依赖缓存。

常见问题排查

最容易被忽略的一点：证书过期不会立刻报错，而是在上传 TestFlight 的最后一步才失败，这时候整条流水线已经空转了十几分钟。我们现在把证书有效期检查放进了阶段 1，提前失败、提前告警。

早期我们用过一种"每晚全量清空缓存重新构建一次"的笨办法来防止缓存腐化，后来改成按镜像版本号做缓存失效（版本号不变就复用，升级镜像才清空），既保住了速度，也不会让脏缓存悄悄潜伏几周才暴露问题。

"不要相信一次绿色的 CI；要相信连续十次绿色的 CI。"——这是我们值班手册里反复强调的一句话，尤其适用于刚迁移到新云节点的头两周。

常见问题