是否必须把 Package.resolved 提交到 Git？

在 Mac 云 CI 与多开发者协作场景下，应用与使用 SPM 的 Xcode 工程应提交 lockfile；纯 SwiftPM 命令行包同样建议提交。未提交时云上 resolve 结果可能与本地不一致，表现为 missing package product 或版本漂移。

何时必须加 -disableAutomaticPackageResolution？

当流水线以 xcodebuild 直连 archive/test 且已把 Package.resolved 纳入门禁时，应在构建命令中加该标志，强制使用 lockfile 版本；若存在独立 resolve Job 且产物已校验，可在后续 Job 沿用同一工作区路径时评估是否省略，但共享 runner 上仍建议保留。

只有 SPM 慢、Git clone 正常怎么办？

优先对照企业出口与 CDN：检查 IPv6、代理白名单与 DNS 分流；在 Mac 节点单独跑 xcodebuild -resolvePackageDependencies 并保存日志，与磁盘水位、DerivedData 争用区分。

2026年 Mac 云 CI：SPM 依赖锁定与 Package.resolved 决策矩阵——何时强制 -disableAutomaticPackageResolution（含 FAQ）

在 Mac 云共享构建池上跑 iOS/macOS CI 的团队，常遇到「笔记本能编、云上随机缺包或版本漂移」：根因往往不是 Xcode 版本，而是 Swift Package Manager 在无人值守环境下自动改写了依赖图。本文面向 2026 年要把 Mac 云当成可控 VPS 的平台工程与 iOS 开发者，先拆四类痛点，再给 workspace / xcodebuild / 多 Job 共享节点三列决策矩阵，接着给出五步 Runbook、并行解析参数表与三条可引用指标；读完你能判断何时必须把 Package.resolved 纳入门禁、何时加 -disableAutomaticPackageResolution，并把失败按「解析 / 磁盘 / 企业出口」分流。

1. 痛点拆解：lockfile 缺失、自动解析、共享 runner 与出口误判

Apple 官方在 2026 年仍强调：使用 Swift Package 的 CI 应把 Package.resolved 提交进版本库，并在 xcodebuild 路径上通过 -disableAutomaticPackageResolution 强制使用锁定版本。把 Mac 云当成「另一台 Linux runner」而忽略 lockfile，会把依赖不确定性转嫁给链接阶段，表现为 flaky 的 missing package product。

lockfile 未纳入门禁：开发者本地 Xcode 自动升级了传递依赖，但未提交 Package.resolved；云上第一次 resolve 成功、第二次因缓存污染或分支切换失败，团队误以为是「Mac 云不稳定」。
构建阶段仍允许自动解析：Archive Job 与 PR Job 共用同一 scheme，却未在 xcodebuild 加 -disableAutomaticPackageResolution，导致夜间 main 与白天 PR 使用不同依赖图，回归无法 bisect。
多 Job 共享同一 DerivedData / SPM 缓存根：A 项目的 resolve 写入全局缓存，B 项目链接阶段读到半成品模块；日志里只有模糊的 link error，排障会浪费数小时。延伸阅读：构建队列与 DerivedData/SPM 磁盘治理。
把 SPM 慢误判为编译慢：企业 HTTPS 解密、DNS 分流或 IPv6 路径差异会让元数据拉取间歇 403；若未单独保存 resolve 日志，会与磁盘满、并发 stampede 混淆。对照：企业防火墙与 Git/SPM 出口。

2. 决策矩阵：workspace、xcodebuild 直连、多 Job 共享 Mac 云节点

下列矩阵回答三个实操问题：是否提交 lockfile、是否在构建命令禁用自动解析、是否拆独立 resolve Job。与「只在本地能编」的临时方案不同，Mac 云 CI 的价值在于把依赖图变成可审计契约。

场景	提交 Package.resolved	-disableAutomaticPackageResolution	独立 resolve Job
单仓库 · xcodebuild Archive（推荐默认）	必须（PR 门禁 + main 保护）	必须（archive / test 均加）	建议：先 resolve 探针再 archive，日志分仓
多 scheme 并行 · 同一 Mac 节点	必须；禁止多分支共用一个未版本化的 lockfile	必须；并为每并发槽位设独立 `-derivedDataPath`	必须：resolve 与 compile 分队列，避免叠峰 IO
纯 SwiftPM CLI（swift build / test）	必须；用 `swift package resolve --force-resolved-versions` 对齐	不适用 xcodebuild 标志；用 CLI 严格模式代替	可选；私包多时用独立 Job 预热 SSH agent
实验分支 · 允许升级依赖	仅在合并前更新 lockfile；禁止直接进 main	实验 Job 可临时关闭，但不得与 release 共 runner 缓存	必须隔离目录与 Unix 用户，防交叉污染

若你使用 Xcode 的 workspace 集成多个 app / extension，lockfile 可能位于 .xcworkspace/xcshareddata/swiftpm/Package.resolved 或工程旁的 Package.resolved；CI 门禁应覆盖实际被 Xcode 读取的路径，而不是假设只有根目录一份文件。

3. 并行解析参数表：何时加速、何时不该开

在 M4 类 Mac 云节点上，适度并行可缩短 resolve 尾延迟；但与 Archive 叠峰时会放大 NVMe 与出口争用。下列参数需在resolve Job中设置，而非在 Archive 高峰硬开。

变量 / 标志	建议起点（单节点 8–12 并发槽）	不应开启的情况
`SWIFT_PACKAGE_MANAGER_PARALLEL_FETCH_LIMIT`	8–12（与 CPU 核数、出口带宽联调）	磁盘可用空间 < 15% 或队列深度已告警
`XCODE_PACKAGE_RESOLVE_PARALLELISM=YES`	resolve 探针 Job 开启	与 Archive 同机同时跑满时
`-scmProvider system`	私包走系统 Git + SSH agent 时加在 xcodebuild	未配置 `known_hosts` / agent 时（会先表现为 auth 失败）
`-disableAutomaticPackageResolution`	所有 compile / archive / test 的 xcodebuild	仅当你故意在隔离 Job 中刷新 lockfile 且未进入 release 线

4. 五步 Runbook：从门禁到三次验收

把 lockfile 纳入版本门禁：PR 必须包含 Package.resolved 变更说明；若 Xcode 本地提示升级依赖，要求开发者显式提交 lockfile，禁止「只在本地 resolve」。
resolve 探针 Job（Mac 云 SSH 用户下）：在 archive 前执行 xcodebuild -resolvePackageDependencies -scheme YourApp -destination 'generic/platform=iOS'，保存完整日志；失败则直接 fail，不进入 compile。
固定路径的 archive：为每个并发槽位设置 DERIVED_DATA_PATH 与 -derivedDataPath，并在 archive 命令加 -disableAutomaticPackageResolution；私包场景按需加 -scmProvider system。
出口与代理一次性验收：对照企业出口文，在节点上夜间跑一次「大依赖拉取」演练，确认 SPM 元数据域名与 Git 走同一策略，避免「clone 正常、resolve 随机 403」。
三次构建验收：固定同一 commit 连续跑三次，记录 resolve 耗时 P95、compile 与 link 占比；若仅第一次 resolve 慢、后两次仍慢，查磁盘与缓存根；若三次依赖版本不一致，查 lockfile 门禁与自动解析标志。

# 示例：resolve 探针 + archive（示意，按你的 scheme 替换）
export DERIVED_DATA_PATH=/Volumes/ci/slot${JOB_SLOT}/DerivedData
xcodebuild -resolvePackageDependencies -scheme App -derivedDataPath "$DERIVED_DATA_PATH" -destination 'generic/platform=iOS'
xcodebuild -scheme App -configuration Release -derivedDataPath "$DERIVED_DATA_PATH" \
  -disableAutomaticPackageResolution -scmProvider system \
  -destination 'generic/platform=iOS' archive

5. 三条可引用指标：resolve 占比、lockfile 漂移、解析失败聚类

resolve 占端到端耗时比例：在 45+ 包工程中，若 resolve 持续高于端到端约 20% 且与代码变更无关，优先查出口与并行度，而不是加 CPU。
lockfile 漂移次数：统计「main 上构建成功但 lockfile 未变」的次数；若每周 > 2 次，说明仍有 Job 在自动解析，应强制加标志或拆 Job。
解析失败 vs 链接失败聚类：日志含 missing package product、checksum、failed downloading 归入解析类；含 linker command failed 且 resolve 已成功归入编译/磁盘类——避免用「重试 archive」掩盖依赖问题。

SPM 缓存与 DerivedData 共用 NVMe 时，「解析成功但链接失败」常来自磁盘水位或并发 stampede，而非业务代码。把 resolve 放在温节点或低并发队列、把 Archive 放在常驻低并发槽，与冷启动 vs 温节点的策略一致：依赖解析是 IO 与出口敏感型任务，不适合与 Archive 在无闸门情况下叠峰。

若团队已实践「PR 走弹性、Nightly 走常驻 Mac 云」，本文补齐第二层：在 Mac 云内部把 SPM 锁定义成与签名链同级的契约；否则弹性池只会放大依赖漂移，而不是吸收尖峰。

7. FAQ

问：Xcode 会删掉 Package.resolved，怎么办？ 在 CI 中用门禁检测 lockfile 是否存在；本地用「提交前 resolve + diff lockfile」流程。若出现 missing package product，先 git checkout -- Package.resolved 再 resolve，而不是在 archive 里反复重试。

问：多分支共用一个 Mac 云 runner 会冲突吗？ 会。应为每个项目或槽位使用独立 Unix 用户与 DERIVED_DATA_PATH，禁止多 repo 共写同一 SPM 缓存根。

问：能否只在 Linux 上 resolve、Mac 上只编译？ 不能可靠替代：iOS 链路的包图与 Xcode 集成解析强相关，且签名与 SDK 只能在 macOS 上完成；Linux 前置最多做元数据镜像，不能作为 lockfile 真源。

8. 结论

在 Mac 云 CI 上，Package.resolved 不是「可选优化」，而是把 Swift 依赖从个人笔记本习惯升级为可复现契约的最低门槛；-disableAutomaticPackageResolution 则是防止无人值守构建偷偷改写依赖图的保险丝。

仅依赖开发者本机偶尔 resolve、或把 SPM 缓存扔在多台共享 runner 的同一目录里，短期看似省事，长期会把版本漂移与 flaky 链接转嫁成排障黑洞；完全指望托管 macOS Runner 的默认缓存策略，又很难按项目定制 lockfile 门禁与出口白名单。对要把 iOS 交付做成稳定产能、又希望继续用 SSH 管理「像 VPS 一样」的 Mac 节点的团队，租赁 VPSMAC 的 Apple Silicon Mac 云主机，用独占或低并发槽位承载 resolve + Archive 重链路，并把 lockfile 与路径契约写进 Runbook，通常比继续在共享缓存根上碰运气更接近问题本质。