2026年独占远程 Mac iOS/macOS CI：SwiftPM 的 Package.resolved 到底该不该提交？——可复现构建、缓存预热、CI 锁版本漂移与 SSH 流水线决策矩阵 + FAQ
把「依赖图钉死」还是「让解析器在 CI 上当场决定」？本文用独占远程 Mac + SSH 流水线的真实约束，拆解 Package.resolved、缓存预热与锁漂移，并给出可写进 Runbook 的决策矩阵与 FAQ。
1. 先把对象说清楚：你在锁什么？
Package.resolved记录的是 SwiftPM 解析后得到的精确版本与校验信息（含 Git revision 或 registry 版本等），用来复现同一张依赖图。它与 Package.swift 里写的版本范围不是一回事：范围是「允许解在哪一片」，resolved 是「这一次解在了哪一点」。
在 Xcode 工程 + SPM 集成依赖的场景里，常见路径是工程目录下的 xcworkspace/xcshareddata/swiftpm/Package.resolved（或等效位置）；纯 Swift Package 仓库则多在根目录 Package.resolved。CI 脚本若只备份其一，会在「命令行能编过、Xcode 工程却重新解依赖」这类问题上反复踩坑。
2. 可复现构建：为什么「应用类」仓库几乎总是提交？
对可交付的应用/固件/内部工具，业界共识是：提交 Package.resolved。这样 PR 与主干、本地与 CI、本周与下周，都在同一张已解析的依赖图上做 diff；出现「只发生在 CI」的回归时，你能先排除「解析器选了另一组兼容版本」这一大类变量。
对对外发布的 Swift Package 库，常见做法是不提交 resolved（或仅把 resolved 当作本地/示例用途），以免把「库的兼容面」误锁成「某个消费方的一次解析结果」。若你维护的是库，却在独占 Runner 上跑「矩阵：多 Swift 工具链 × 多平台」，更应以 Package.swift 的语义与 CI 矩阵为主，而不是以单份 resolved 冒充兼容承诺。
3. 缓存预热：提交 resolved 与「省下载」不是同义词
独占远程 Mac 的一大优势是持久化磁盘：你可以在机器维度预热 SourcePackages、Git 镜像或自建 registry 代理。但缓存命中依赖键（解析结果、工具链版本、registry 配置、甚至网络出口），而不是单靠「有没有 resolved 文件」。
实践上：提交 resolved 减少的是解析不确定性；缓存策略减少的是重复 fetch/checkout。两者叠加最好——在 SSH 流水线上用固定 -clonedSourcePackagesDirPath 或团队约定的 DerivedData/SourcePackages 路径，并在 Runbook 写明何时允许清空缓存（大版本 Xcode 升级、registry 迁移、安全事件）。
4. CI「锁版本漂移」：即使提交了也会动？
会。典型来源包括：Xcode / Swift 工具链升级、Package 使用版本范围且上游打了新 tag（若你在 CI 上执行会改写 resolved 的命令）、镜像/registry 元数据变化、以及多根工程/多 workspace 下解析入口不一致。独占 Runner 若长期不升级工具链，会把问题推迟成「一次性大爆炸」；托管机则相反，漂移更频繁但更均匀。
缓解策略：把工具链版本写进验收清单；对应用仓库在 CI 上校验「resolved 是否被意外改写」；对库仓库用矩阵覆盖解析边界。若你在管理一批独占主机上的目录与初始化流程，可参考我们此前整理的 Mac 架构资源库：批量初始化与自动化交付，把「依赖目录、权限、清理策略」和机器生命周期绑在一起。
5. 决策矩阵（独占远程 Mac + SSH 流水线）
| 场景 | Package.resolved | 理由摘要 |
|---|---|---|
| iOS/macOS 应用主仓库 | 提交 | 强可复现；便于 PR 审查依赖变更 |
| 可复用 SwiftPM 库（对外） | 通常忽略 | 避免误代表兼容面；用矩阵验证范围 |
| 单仓多 App / 多 workspace | 每入口各一份并都提交 | 防止「CLI 与 Xcode 各解各的」 |
| Fork/补丁依赖 + 频繁 rebase | 提交 + 严格流程 | 冲突在 resolved 上可见；需约定合并策略 |
| 安全审计要求「可钉死供应链」 | 提交 + 校验 | 与 SBOM/allowlist 联动；CI 防篡改 |
6. SSH 独占流水线上的硬建议
- 显式解析步骤：在
xcodebuild前调用-resolvePackageDependencies（或团队封装等价物），失败时日志要落盘。 - 非交互：SSH 会话无钥匙串弹窗；凭据走环境或钥匙串预置，避免首次解析阻塞。
- 并发 jobs：同一用户下并行构建时，避免多个 job 争用同一 DerivedData/SourcePackages 路径——这是 flaky 的高发区。
- 升级日：Xcode 大版本切换后安排一次「冷启动」构建验收，再恢复缓存。
若你仍在搭「从笔记本 SSH 到第一台远程 Mac」的最小通路，可对照 远程 Mac mini 上基于 SSH 的最小依赖部署实践 中的权限与目录约定，把同样的纪律迁移到 CI 工作目录（未必安装同一套软件，但会话、路径、非交互原则一致）。
7. FAQ
CI 报错「package resolution failed」优先看什么？
工具链版本、网络/registry、Git 凭据、以及 Package.swift 与 resolved 是否指向同一解析入口（Xcode 工程 vs 包根目录）。
resolved 合并冲突怎么解？
不要手搓 JSON：在主干合并后于本地或 Runner 上执行一次官方解析流程，生成新的 resolved 再提交；冲突本身说明依赖图同时在变，应用审查而不是「选一边」。
不提交 resolved 能更快吗？
偶尔省掉合并烦恼，但换来的是不可解释的 CI 漂移；在独占长跑 Runner 上，这种漂移更难用「换一台干净机器」自证。
在 Mac mini 上把「锁依赖」做成默认正确
依赖解析与编译同样是 CPU、磁盘与 I/O 的混合负载：Apple Silicon 的统一内存与带宽让大型 SPM 图在解析与增量编译时更不容易掉速；macOS 作为官方工具链的一等公民，避免了跨平台模拟层带来的额外变量。对需要长期无人值守的独占 CI 而言，macOS 的稳定性与极低崩溃率意味着更少的「半夜 job 红」。
若你希望把本文的缓存策略、SSH 非交互解析与多 job 隔离真正跑稳，一台静音、低待机功耗且能 7×24 放在机房的 Mac mini M4 往往比临时拼凑的虚拟机池更省心——总拥有成本也更容易算清。若你正在物色这样一台「解析与构建都靠谱」的主力节点，现在就是把它纳入团队基础设施的好时机：前往 SSHMac 首页了解方案。