Swift 6.4 于 2026 年 9 月 15 日发布。接入远程 Mac CI 时，不要把升级编译器和切换语言模式当成同一步：先记录现有工具链与 target 设置，再按 target 处理并发诊断；跨平台 Swift 包可继续在现有 CI 执行对应任务，需要 Xcode、Apple SDK 或 Apple 平台目标的构建与测试，则安排到符合项目要求的 Mac 环境验证。(Swift 6.4 发布公告)
负责 Swift 应用或框架迁移的开发者，可按模块处理诊断，避免一次性切换整个项目。
维护 Apple 平台 CI 的工程师，可据此划分构建、测试与产物验收职责。
维护跨平台 Swift 包的 DevOps 工程师，可用本文判断哪些工作流留在现有 CI，哪些需要 Mac 阶段。
更新时间：2026 年 10 月 10 日。 Swift 版本信息核对自 Swift 6.4 发布公告；涉及 Xcode 与工具链对应关系时，应查看 Apple 的Xcode 发布说明。项目落地前，还要在实际构建节点复核工具链、target 设置和构建结果。
[ SECTION_01 ] 第一阶段：分清编译器版本、语言模式与并发检查
Swift 编译器决定工具链能识别哪些语言功能；语言模式决定某个 target 按哪套语言兼容规则编译；并发检查则决定并发安全问题如何诊断。只看到节点装了 Swift 6.4，不能据此推断所有 target 已切换语言模式，也不能当作 Apple 平台构建已经通过。
Swift 官方迁移指南明确区分编译器版本与语言模式，并说明可以按 target 推进迁移。对项目而言，这意味着可以先更新工具链并记录基线，再决定哪些目标进入 Swift 6 语言模式，而不是将整个项目捆绑成一次升级。
| 核对项 | 记录内容 | 对迁移决策的意义 |
|---|---|---|
| 编译器版本 | swift --version 的完整输出；Xcode 节点另记 xcodebuild -version |
确认实际执行的是哪套工具链，不凭节点名称或安装目录猜测 |
| target 语言模式 | Swift Package target 的语言模式；Xcode target 的 SWIFT_VERSION 等实际构建设置 |
判断哪些模块已进入目标模式，哪些仍保持原有模式 |
| 并发检查 | 当前诊断级别、警告与错误，以及检查配置来自何处 | 区分预检结果和切换语言模式后的严格检查结果 |
| 验收范围 | 构建目标、测试目的地、SDK、产物类型 | 决定任务能否留在通用 CI，还是必须由 Mac 与 Apple 工具链执行 |
Swift Package Manager 和 Xcode 项目都支持在模块或 target 范围内管理相关设置。实际迁移前，应以项目使用的工具链文档与构建配置为准。(Swift 迁移指南)
[ SECTION_02 ] 第二阶段：建立基线，再确定诊断路径
开始改代码前，先在现有 CI 配置下保存一份基线。对每个 target 记录编译器版本、语言模式、已启用的并发检查配置、构建结果、测试结果和主要诊断。保留构建日志，而不只保存“通过”或“失败”；之后出现差异时，日志能帮助区分是工具链变了、模式变了，还是源代码改动引起的。
Swift 6.4 下逐步启用并发诊断
先确认目标工具链与该 target 当前语言模式，再按该版本支持的方式进行预检。Swift 官方迁移策略说明，可以选择模块、启用更严格的检查并逐项处理警告；这并不代表所有项目都能在不改配置的情况下使用同一组检查选项。若现有配置无法提供预期诊断，就为独立试点 target 建立受控的模式切换任务，不要假设旧工具链的开关在新版本仍有相同效果。(官方迁移策略)
归类诊断时，按根因而非报错数量分组。常见来源包括共享可变状态、缺少或不准确的 Sendable 语义、actor 隔离边界，以及尚未表达并发约束的依赖或 Objective-C 接口。@unchecked Sendable、nonisolated(unsafe) 和 @preconcurrency 可能改变检查结果，但它们本身不是线程安全证明。对每项临时兼容措施，都留下责任人、原因、适用边界和移除条件。(并发迁移中的常见问题)
迁移指南中的警告预检与 Swift 6 语言模式下的检查，不应混写成一个“已经完成”的状态。若两种设置产生不同级别的诊断，CI 报告要分别标识检查模式和工具链版本。
[ SECTION_03 ] 第三阶段：挑选边界清晰的 target 试点
不要先挑依赖最深、同时拥有最多平台条件代码的应用主 target。优先选依赖关系较少、能单独构建和测试的模块。试点应覆盖真实并发代码，但要能在失败时单独回退，不牵动整个依赖图。
把并发诊断按问题逐项处置：确认共享状态应由 actor 隔离还是由同步机制保护；确认跨隔离传递的值是否确实满足 Sendable；核对闭包和回调是否跨越并发边界；检查第三方库与 Objective-C API 的契约。若必须暂时使用兼容标注，就把它记录为未完成事项，而不是清零诊断后直接宣布迁移成功。Swift 官方指南建议分阶段推进，并强调隔离与 Sendable 应反映代码真实的并发语义。(增量迁移指南)
[ SECTION_04 ] 第四阶段：把试点变成可比较的 CI 任务
将试点 target 的构建和测试放进独立任务，并固定依赖解析、构建参数和测试目的地。流水线至少保存编译器版本、各 target 语言模式、完整构建日志、并发诊断摘要、测试结果与产物校验信息。这样对照旧基线时，才能识别“代码修复了”还是“换了一套构建条件”。
| CI 任务类型 | 推荐执行位置 | 适配度评分 | 验收边界 |
|---|---|---|---|
| 不依赖 Apple SDK 的 Swift Package 构建与测试 | 现有 Linux 或其他已支持的 CI | 高 | 仅证明该平台和该配置下的包任务通过 |
| 需要 Xcode、Apple SDK 或 Apple 平台目标的构建 | 远程 Mac CI | 高 | 记录实际 Xcode、编译器、SDK 与构建目标 |
| 依赖 Apple 平台运行时或 Simulator 的测试 | 符合项目要求的 Mac 执行环境 | 高 | 单独保存测试目的地、测试结果及必要日志 |
| 单独的 Swift 语言模式诊断任务 | 能运行目标工具链的节点 | 中 | 诊断通过不等于平台构建、签名或发布验收通过 |
评分按任务与运行环境的匹配度判断，不代表性能测试或完成时间。Swift 6.4 发布公告介绍了 Swift Package Manager 在 Linux、macOS 和 Windows 上的构建能力；这不意味着通用 CI 可以替代 Xcode 或 Apple SDK 验证。工具链与平台支持信息应再按项目采用的 Xcode 版本核对 Apple 发布说明。
[ SECTION_05 ] 第五阶段：把 Apple 平台验收放到远程 Mac
判断任务是否需要 Mac，依据不是“项目写了 Swift”，而是实际依赖什么：如果构建需要 Xcode、Apple SDK 或 Apple 平台目标，就应在符合项目要求的 Mac 工具链中复测；如果测试依赖 Simulator 或 Apple 平台运行时，也不能用 Linux 上的 swift test 结果代替。跨平台包任务仍可留在现有 CI，Mac 阶段只承担必须由 Apple 工具链验证的部分。
Xcode 版本和其中的 Swift 工具链要查对应的 Apple 发布说明，不要因为 Swift.org 发布了新版本，就推断某个 Xcode 已附带该版本。发布前可在 Mac 节点执行版本检查，并核对构建日志中的实际调用路径。
远程 Mac CI 的执行步骤
- 确认节点工具链。 在实际任务中记录
xcodebuild -version、swift --version和所选工具链路径。若版本不符合项目矩阵，先停止迁移验收，不要用结果覆盖基线。 - 确认 target 设置。 从 Swift Package 配置或 Xcode 构建设置中导出每个目标的语言模式，并检查 CI 是否通过参数或配置文件覆盖本地设置。
- 执行单 target 试点。 只切换已批准的试点 target；其他 target 保持基线模式。保存完整日志，逐条分类并发诊断。
- 执行对应测试。 跨平台包测试按原有平台运行；需要 Xcode、Apple SDK、Apple 平台目标或 Simulator 的任务，在 Mac 节点执行。
- 核验结果与产物。 将构建结果、测试报告、目标平台、SDK、产物类型及必要的校验信息归档。测试通过不能替代产物检查，包测试通过也不能替代 Apple 平台交付验收。
- 比较并决定下一步。 对照基线检查新增诊断、测试失败、兼容处理和回滚路径，再选择扩大迁移、维持双轨或暂缓。
[ SECTION_06 ] 第六阶段：按发布证据扩大范围或回退
升级编译器不代表 target 的语言模式自动改变。Swift 6.4 的兼容性文档指出，使用 Swift 6.4 编译器可以构建采用较早语言模式的代码；启用该版本的严格并发检查，则要遵循其语言模式要求。因此，CI 计划应把“验证新编译器”和“让特定 target 接受严格检查”记录成不同变更，并分别审查影响范围。(Swift 6.4 版本兼容性说明)
按以下条件分支控制推进范围：
- ✅ 若 target 可独立构建、依赖边界已核实、诊断有责任人，且对应测试与 Apple 平台任务通过，则扩大到下一个依赖边界清楚的 target。
- ⚠️ 若只在原有非 Mac CI 通过，但交付依赖 Xcode 或 Apple SDK，则保留当前试点状态，补齐远程 Mac 阶段后再评估。
- ❌ 若迁移依赖大量未解释的抑制标注、测试不稳定或无法恢复原配置，则回退该 target 的模式变更，保留已修复代码与诊断记录，暂缓扩大。
- ✅ 只有实际构建、测试、产物检查和发布链路都复测通过，才把对应 target 记录为已完成；不要把“没有诊断”单独当成发布证据。
现有方案若完全依赖 Linux 节点，会缺少 Apple SDK 与 Xcode 验证；若只用开发者本地 Mac，环境差异和排队会让复测不易复现；若为了少量试点立即采购专用硬件，还要承担闲置、维护和版本管理成本。需要临时 Mac 执行阶段时，可先评估 NOVAKVM 的 Mac 方案，并结合购买 Mac mini 的成本与使用场景比较租赁与自购。若工作负载长期稳定、持续高负载，或必须连接特定物理设备，自购更便于掌控；若只是迁移试点、阶段性 Apple 平台复测，租赁 NOVAKVM Mac 可先补齐真实 Mac 工具链，而不必为了短期验证提前承担整机采购与维护。