Swift 官方于 2026 年 9 月 15 日发布 Swift 6.4，并确认 SwiftPM 默认构建系统切换为 Swift Build。这个变化需要验收，但不等于所有 Xcode 项目都会自动改变构建流程。不要只凭节点装有 Swift 6.4 就全量切换：先确认 CI 任务实际调用的 Swift 和 SwiftPM，再用同一提交隔离运行构建与测试；目标项目复现通过后，才逐步推广。结论依据Swift 6.4 发布说明和SwiftPM 6.4 官方发行说明。
适合维护 Swift Package 构建流水线、正在升级 Swift 工具链的团队负责人，以及使用 macOS 承载 Apple 平台任务的 CI 工程师。
如果要核对依赖、构建、测试或制定回退条件，下面的验收流程可直接用于整理流水线证据。
最后更新于 2026 年 11 月 11 日；工具链行为与命令依据 Swift 官方发布说明及 SwiftPM 6.4 文档复核。
[ SECTION_01 ] 先建立可比较的验收基线
SwiftPM 6.4 的变更核心是默认构建系统改为 Swift Build。官方说明列出的差异包括产物输出位置、部分参数的校验行为、测试运行器组织方式和诊断日志。包能编译，不代表所有脚本都仍能在原路径找到产物；测试任务启动成功，也不代表测试已经执行并通过。SwiftPM 6.4 发行说明提供了这些行为变化与回退选项。
切换前先保存原流水线的完整任务定义和运行结果。至少固定提交哈希、任务命令、Swift 工具链、SwiftPM 版本、依赖锁定文件、镜像设置、构建产物位置及测试报告。对照时使用相同提交和相同依赖条件；否则解析结果不同，无法判断差异来自构建系统还是依赖更新。
| 验收选项 | 核对维度 | 适用边界 | 评分 |
|---|---|---|---|
| 原有 SwiftPM 任务 | 命令、工具链、依赖和结果记录 | 作为迁移前基线；保留原日志与产物位置 | ◎ 基线完整 |
| SwiftPM 6.4 隔离任务 | 默认 Swift Build 下的解析、构建、测试、产物 | 验证 Swift Package 工作流是否适配 | ◎ 全项有证据；△ 结果缺项；× 同条件下失败 |
| Xcode 项目或归档任务 | xcodebuild 的 scheme、destination、测试与归档 |
单独验收 Apple 平台项目流程，不能用 SwiftPM 结果替代 | ◎ 独立验证 |
表中评分是验收记录的判定标记，不是官方兼容性结论。◎表示对应任务有完整、可复核的证据；△表示证据缺失或需调查；×表示在固定条件下复现失败。对比项要分清：SwiftPM 包构建不等同于 Xcode 项目构建，更不能代替 Apple 平台归档与分发验证。Apple 将 xcodebuild 定义为构建 Xcode 项目和工作区的命令行工具，具体构建目标与操作则由项目 scheme 等设置决定，详见Apple 命令行工具参考。
[ SECTION_02 ] 工具链身份：检查任务实际调用的入口
机器上安装了新版本，不代表 CI 任务一定使用它。常见偏差包括：任务使用了另一套 PATH；交互式终端与非交互任务加载的环境不同；不同构建步骤切换了 Xcode 活动目录；包装脚本又选择了其他 Swift 可执行文件。只查看节点清单，无法排除这些情况。
把以下采集命令放在构建任务内部执行，并将输出和失败日志一并保存：
pwd
git rev-parse HEAD
command -v swift
swift --version
swift package --version
xcode-select -p
xcodebuild -version
xcrun --find swift
swift --version用于记录执行入口解析到的 Swift 版本；command -v swift与xcrun --find swift帮助对照调用路径。Apple 文档说明，Xcode 命令行工具需要安装 Xcode，并将其设为活动开发目录后才能调用；因此，若任务还运行 xcodebuild，也要记录活动目录和 Xcode 版本，而不是只记录 Swift 版本。Swift 工具链的安装和选择方式可对照Swift 官方 macOS 安装文档。
同一份记录应包含 CI 配置中的实际任务命令、执行账户和关键环境变量。若构建日志显示 Swift 版本正确，但 xcrun 指向的开发目录与预期不符，应先修正入口，再判断兼容性；否则，试跑可能测到的是另一套工具链。
[ SECTION_03 ] 依赖解析：把锁定结果与项目约束一起核对
SwiftPM 在构建或运行时会解析依赖；Package.resolved记录解析结果。Apple 平台应用中的锁定文件也可能位于 Xcode 项目或工作区内部，因此不能只检查仓库根目录。相关行为可查阅Swift Package 依赖文档。
在同一提交上，先比较切换前后的锁定文件内容和哈希，再确认依赖源、镜像、私有仓库凭证与本地依赖配置没有变化。对私有依赖尤其要区分“认证失败”“网络不可达”“版本无法解析”和“源码编译失败”：它们表面上都可能导致任务失败，但责任边界不同。
验收时保存依赖解析输出，并核查 CI 是否意外重新解析或更新了依赖。发现锁定结果变化，不要直接将其写成 Swift 6.4 的普遍风险；先检查提交、依赖声明、镜像配置和执行参数，确认能否在相同条件下复现。若使用了锁定文件以外的版本，先恢复可比条件，再重复测试。
[ SECTION_04 ] 构建指标：确认目标、产物和诊断都对得上
SwiftPM 构建任务应按项目声明的产品和 target 验收。记录执行的命令、退出状态、构建配置、目标平台、完整日志和实际产物。SwiftPM 6.4 发行说明指出，Swift Build 的产物位置可能与旧系统不同；应通过 swift build --show-bin-path获取当前任务的产物目录，不要假定旧路径仍然有效。相关参数的用法也可在Swift 构建文档中核对。
当任务涉及多种构建目标时，要分别列明预期产物：例如库产品、可执行文件、测试目标，或项目脚本后续要读取的文件。构建命令返回成功但预期文件不存在，仍属于验收未完成。若文件位置变化，先调整依赖路径的脚本并重新跑完整任务，再记录结果。
更重要的是划清任务边界。swift build验证 SwiftPM 包的构建；它不能证明 Xcode scheme 下的测试、Simulator 相关任务、签名、归档或导出都通过。Xcode 的归档流程使用独立的 xcodebuild archive操作，Apple 文档将构建和分发归档列为 Xcode 项目流程。遇到这类流水线，应保留原有 Xcode 任务并独立回归，不能从 SwiftPM 默认行为推断归档步骤已经改变或兼容。具体归档流程可参考Apple 的归档说明。
[ SECTION_05 ] 测试指标：将构建成功与测试通过分开
构建完成只说明编译阶段达到其成功条件。测试是否发现、是否执行、是否通过，以及结果是否被 CI 留存，需要单独核验。SwiftPM 6.4 的发行说明提到，Swift Build 按 package 中的 test target 组织测试运行器；如果流水线依赖旧日志格式或从日志中提取测试数量，应检查解析器是否还适用。
在同一提交上对比新旧任务的测试发现结果、执行结果和报告文件。逐项确认测试命令实际运行、退出状态被流水线识别、测试报告上传成功；若有跳过项或条件执行，要在结果中注明原因。测试报告缺失时，不应将单纯的构建成功标成通过。
遇到失败，保存完整日志、失败的测试标识、任务命令和重跑结果。在相同提交、工具链、依赖与环境条件下复跑后，再区分 Swift Build 行为差异、项目测试本身的问题，以及 CI 环境变化。只有单次失败、缺少日志或无法复现时，应标为待调查，而不是据此推断所有 SwiftPM 项目都会失败。
[ SECTION_06 ] 缓存与重复运行：检查可复现性而非单次绿灯
缓存会影响任务实际使用的构建状态。验收记录应标明缓存是否启用、缓存路径、是否清理，以及任务是否复用依赖和构建产物。SwiftPM 命令支持指定缓存和 scratch 路径，默认构建产物目录也可能随平台或工具链变化；可结合前述 Swift 构建文档核对路径处理方式。
先用固定提交完成一次隔离构建，再按团队的 CI 策略执行清理缓存与复用缓存的对照运行。对比两次的依赖锁定文件、产物检查和测试结果；如果结果不同，逐步检查缓存目录、解析结果和环境变量，而不是直接认定缓存机制本身有缺陷。
缓存运行一次通过，只能说明那次任务通过。若正式流水线依赖共享缓存，需确认清理与复用两种路径都符合团队的可复现性要求，并保留对应日志。
[ SECTION_07 ] 用逐项评分决定推广、暂缓或回退
验收结果应落到明确的准入条件，而不是只留一句“CI 通过”。每条结论都关联到具体提交、命令和日志，避免后续无法复核。
- 推广：任务实际工具链身份明确；依赖锁定与预期一致；构建目标和产物齐全；测试有独立通过记录；缓存条件下的重复运行符合团队要求。先让隔离任务承载试跑，再逐步扩大覆盖。
- 暂缓：有一项结果缺日志、缺产物或不可复现；依赖解析条件与基线不一致；Xcode 项目或归档任务尚未单独完成验证。补齐证据后再决定。
- 回退：在同一提交和相同依赖条件下，SwiftPM 6.4 任务稳定复现失败，且失败会阻断现有流水线。SwiftPM 6.4 文档说明，可对包命令显式使用
--build-system native回到旧构建系统；先将回退范围限定到受影响任务，保留失败证据，再继续调查。
评分只对被验证的任务有效。SwiftPM 包通过，不代表 Xcode 项目和 Apple 平台归档通过；Xcode 归档成功，也不能代替包依赖和测试结果的独立记录。
[ SECTION_08 ] 常见验收问题
独立试跑的核心是控制变量：选定一份固定提交，保持依赖和项目约束不变，记录 CI 实际执行环境，再分别检查解析、构建、测试与产物。这样得到的差异才有机会指向工具链或构建系统，而不是混入代码改动、依赖更新或环境漂移。
若团队当前依赖 Linux 或 Windows 节点承担通用任务，它们仍可继续处理适用的工作；但当验收对象要求真实 macOS 工具链、Apple SDK 或 Xcode 归档时，环境边界必须单独满足。应先明确是缺少一台隔离试跑机，还是长期需要稳定运行的正式构建节点，再选择临时测试环境或自有设备。若正在比较自有 Mac 与临时环境，可结合Mac mini 采购方案评估使用周期和维护责任。
面向短期升级验收，当前机器或通用云主机可能有几个实际限制：没有 macOS 工具链、难以复刻团队的 Apple 平台任务、临时改动现有 Runner 会污染基线。此时，租用真实 Mac 可作为隔离试跑的备选，让新旧任务分开验证；具体是否适合，仍应按工具链控制、访问方式、运行周期和数据安全要求评估。可先查看 NOVAKVM 的远程 Mac 环境，再决定是否用于短期验收；若工作负载长期稳定且持续高负载，自购设备通常更值得纳入成本评估。
这项验收的重点不是追求一次绿灯，而是留下能解释结果的证据：工具链入口、依赖锁定、构建产物、测试结果和缓存条件都可复核后，再逐步推进 Swift 6.4 SwiftPM 构建变更验收。
常见问题
Swift 6.4 的 SwiftPM 默认构建平台具体调整了什么？
Swift 官方发布说明确认，SwiftPM 6.4 将 Swift Build 设为默认构建系统。它会影响 SwiftPM 包的构建行为，但不能据此推断所有 Xcode 项目或归档任务也自动切换；应分别按流水线实际执行的命令验证。
如何在 macOS CI 里确认实际运行的是 Swift 6.4？
不要只看节点安装列表。应在 CI 任务本身输出 swift 的查找路径、swift --version、SwiftPM 版本，以及 Xcode 活动开发目录和版本；同时保存完整任务命令，确认日志来自实际构建账户和执行环境。
升级后 Swift Package 构建失败，优先检查哪些证据？
先固定提交、依赖锁定文件、镜像和私有依赖配置，再比对 SwiftPM 构建日志、产物路径与测试发现结果。官方发行说明列出 Swift Build 与旧构建系统的行为差异；必要时在同环境对照原构建系统，避免把未复现的问题归因于工具链。
Swift 6.4 能直接切进正式 macOS CI 吗？
只有目标项目在隔离任务中完成依赖解析、预期构建、测试与重复运行，且日志和产物可复核，才适合逐步推广。若流水线只有构建成功记录、依赖条件发生变化，或 Apple 平台归档尚未单独验证，就应暂缓全量切换。