2026-04-20 租用 Apple Silicon 云端 Mac 上的 Ruby Bundler 与 CocoaPods 可复现 CI
许多团队通过 SSH 租用 Mac mini M4 或 Mac Studio 作为 iOS CI 构建机，仓库里依然大量使用 CocoaPods。真正的问题从来不是“Pods 不好”，而是 Ruby 工具链不可复现：有的任务调用系统 pod，有的任务吃到周二升级的 Homebrew，还有的残留 gem install cocoapods 写在 ~/.gem 里。本篇 2026-04-20 手册在 租用的 Apple Silicon 主机上，把 Bundler 管理的 CocoaPods 标准化到 HK / JP / KR / SG / US 全区域，并把缓存目录对齐到按任务隔离的工作区，让多租户机器上的 NVMe 占用可预测。请交叉阅读 SwiftPM 与 CocoaPods 取舍、命令行工具与完整 Xcode，以及 并行 xcodebuild 任务，让依赖解析与编译步骤保持同一套假设。
为何在无头构建机上仍需要 Bundler
CocoaPods 本质是 Ruby 程序。你调用的 pod 可执行文件，稳定性取决于背后的 gem 组合。Bundler 通过 Gemfile.lock 把这套组合钉死——这正是十几支产品团队共用一套云端 Mac 机队时最需要的保障。没有 Bundler，“我这条分支绿了”往往等价于“谁最后登录就把全局 CocoaPods 升了一档”。
- 可复现 — 同一份
Gemfile.lock在各区域得到一致的解析行为。 - 可审计 — 安全团队可以对比两次发布之间的 gem 版本差异。
- 可隔离 —
bundle install --path vendor/bundle把 gem 放进工作区，而不是共享 home。
Ruby 工具链矩阵（3.1 / 3.2 / 3.3）
Apple Silicon 上的 macOS 镜像常带较新的系统 Ruby；也有团队叠加 rbenv 或 asdf。请为整套机队选择 唯一 策略，并在基础设施仓库里写成代码。把精确的 ruby -v 与 xcodebuild -version 一并写进构建元数据。
| 方案 | 优点 | 风险 |
|---|---|---|
| 系统 Ruby + Bundler | 全新 SSH 主机上启动快 | 系统升级可能抬升 Ruby；用 plist 或 CI 环境变量固定 |
| 每用户 rbenv | 补丁级版本精确 | launchd 任务必须显式 source rbenv shim |
| asdf + .tool-versions | 一个文件同时管 Ruby、Node 等 | 首次安装时间更长 |
Gemfile 与锁文件规范
同时提交 Gemfile 与 Gemfile.lock。把 cocoapods 固定到经过验证的小版本，并显式列出插件（例如 cocoapods-acknowledgements）——不要依赖“最新插件解析到什么”。在 CI 中推荐：
bundle config set --local deployment 'true'
bundle config set --local path 'vendor/bundle'
bundle install --jobs 4 --retry 3
pod install 之前运行 bundle check，可在有人改了 Gemfile 却忘记更新 Gemfile.lock 时快速失败。
bundle exec pod install（何时加 --deployment）
始终使用 bundle exec pod install（若需要 Bundler 严格强制执行锁文件，则加 bundle exec pod install --deployment）。除非你喜欢周五晚上的随机性，否则不要在生产流水线里直接调用裸 pod。针对 CI 缓存，传入确定性的 CP_HOME_DIR，或使用 CocoaPods 官方建议、且作用域限定在任务目录下的缓存环境变量。
~/Library/Caches/CocoaPods 且不做命名空间隔离，可能出现半成品下载——请按 $CI_JOB_ID 或按仓库克隆路径隔离缓存。
缓存、Pods/ 与工作区布局
把 Pods/ 与 *.xcworkspace 的生成限制在该次构建对应的克隆路径内。在短命工作区上，仅当校验和与 Gemfile.lock + Podfile.lock 一致时，才在多次运行之间缓存 vendor/bundle 与 CocoaPods specs 缓存；一旦不一致就要积极失效——陈旧的 specs 缓存会引发看起来像网络问题的模糊解析错误。
NVMe 与多租户卫生
CocoaPods 下载可能单次就增加 数百 MB；含多个 Podfile 的 monorepo 会成倍放大。在 512 GB 共享主机上，请把解析阶段与 模拟器与归档清理 的磁盘指引结合使用。若 pod 步骤期间磁盘经常超过 70%，请拆分 lane 或通过 定价页 升级到 1 TB / 2 TB 节点，而不是在流水线中段无休止地临时清理。
区域构建机：CDN 与延迟
从 新加坡 或 东京 访问 specs CDN 通常很快，但企业代理或 TLS 检查会增加重试。为 bundle install 配置重试参数；若安全团队要求镜像或缓存代理，请按区域记录例外，让 香港 与 美东 行为一致。
相关手册
若你把 lane 迁向 SwiftPM，请用 SwiftPM 解析与缓存 对比缓存体量与锁语义。Pods 解析完成后的签名流程，请回到你们既有的自动/手动签名文章——Bundler 不会替代描述文件。
常见问题：云端 Mac 上的 Bundler + CocoaPods
| 问题 | 实务答案 |
|---|---|
| 能否用 Homebrew 装 CocoaPods？ | CI 不建议——请用 Bundler 管理 gem，让升级走代码评审，而不是意外的包版本跳动。 |
| Bundler 2 与 1 怎么办？ | 统一主版本；开发笔记本与 CI 不一致是常见的“本地能跑”来源。 |
| CI 要不要提交 Pods/？ | 团队策略——要么全提交实现封闭构建，要么每次都生成；不要半提交。 |
结论：把 CocoaPods 当作另一种编译工具链——固定版本、限定缓存范围，并在共享 SSH 构建机上始终通过 bundle exec 调用。
