在独占远程 Mac 上迁移 Swift 6：严格并发 CI 门禁与 Actor 隔离 Runbook

Swift 6 严格并发检查（-strict-concurrency=complete）触发的错误数量与代码库规模正相关：中等规模 iOS 项目首次启用时，出现 200–800 个编译错误并不罕见。这些错误需要逐模块修复，修复期往往横跨数周甚至数月。在此期间，CI 环境必须保证：

• Xcode 小版本固定：Swift 6 的 Actor isolation 诊断在不同 Xcode 版本间措辞会变化，钉住版本才能让 CI 输出可对比。
• 无邻居 CPU 争抢：严格并发全量编译比普通 debug build 耗时多 20–40%，独占节点避免 P95 尾延迟爆表。
• 磁盘 DerivedData 命名空间隔离：多个 PR 同时跑并发检查，需要各自独立的增量编译缓存，否则缓存污染导致结果不可信。
• 错误计数可追踪：把每次构建的 Swift 6 错误数、修复 commit、剩余模块列表写入结构化日志，便于向管理层证明迁移进度，而不是只报「还在改」。

独占节点的价值在于：同一 Xcode 小版本下，错误措辞与行号在数周内保持稳定，方便对比「上周 412 个、本周 87 个」这类可审计曲线；分钟池里频繁换镜像则会把问题混成环境噪声。拨备与验收字段可与节点 Runbook 六步一并对齐。

Swift 提供三档编译器标志，可在 OTHER_SWIFT_FLAGS（Xcode Build Settings）或 Package.swift 的 swiftSettings 里设置：

实践中推荐按模块渐进：先在叶子模块（无依赖或依赖少）开启 complete，再向核心模块推进。SwiftPM 的 .enableUpcomingFeature("StrictConcurrency") 可精确控制单个 target 的检查级别。

迁移期 90% 的编译错误集中在以下三类，先处理完这三类可清掉绝大部分红字：

① 跨 Actor 访问非 Sendable 类型

// ❌ 错误：从非 @MainActor 上下文访问 @MainActor 隔离的属性
actor DataFetcher {
    func load() async {
        let result = await networkClient.fetch()
        // ❌ passing argument of non-sendable type 'UserModel' across actor boundary
        await MainActor.run { viewModel.update(result) }
    }
}

修复方式：让 UserModel 实现 Sendable（值类型通常自动满足），或将跨边界的转换提前到 Actor 边界内完成。

② @MainActor 漏标

UIKit/SwiftUI 的 ViewController、ObservableObject 子类在迁移前隐式跑在主线程；Swift 6 要求显式标注 @MainActor。批量修复可用 Xcode 的「Fix」按钮，但建议人工 review 每一处，避免把不应在主线程的逻辑也拉了进来。

③ 全局变量并发访问

// ❌ Swift 6 中不可变全局常量需要是 Sendable 或 nonisolated
var sharedCache: NSCache<NSString, AnyObject> = .init()

// ✅ 用 nonisolated(unsafe) 明确声明（迁移期过渡方案）
nonisolated(unsafe) var sharedCache: NSCache<NSString, AnyObject> = .init()

// ✅ 更好：包裹进 Actor 并通过 async 接口访问
actor CacheStore {
    private let cache = NSCache<NSString, AnyObject>()
    func object(forKey key: String) -> AnyObject? { cache.object(forKey: key as NSString) }
}

把严格并发检查纳入 PR 门禁的核心思路：单独开一个 Job 跑并发检查，不与常规测试 Job 合并。这样并发检查失败不会污染测试报告，也便于在修复期设置不同的失败策略（warn-only vs. block-merge）。在 NUKCLOUD 上拨备节点时，建议先在 定价页 选定磁盘与区域，再经 下单页 交付 SSH 与 Runner 基线，避免迁移期临时借用分钟池导致 P95 不可比。

修复期通常持续数周：请把「并发错误计数」「全量编译 wall time」「DerivedData 体积」三项写入结构化日志，并与节点规格变更（加盘、换区）关联，否则很难判断是代码回退还是环境漂移。

name: Swift 6 Concurrency Gate

on:
  pull_request:
    branches: [main, release/*]

jobs:
  concurrency-check:
    runs-on: self-hosted          # NUKCLOUD 独占远程 Mac Runner
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4

      - name: Select Xcode (钉住小版本)
        run: sudo xcode-select -s /Applications/Xcode_16.3.app

      - name: Restore DerivedData cache
        uses: actions/cache@v4
        with:
          path: ~/DerivedData/swift6-check
          key: swift6-${{ runner.name }}-${{ hashFiles('**/*.xcodeproj/project.pbxproj', '**/Package.resolved') }}
          restore-keys: swift6-${{ runner.name }}-

      - name: Build with strict concurrency (complete)
        run: |
          xcodebuild build \
            -project MyApp.xcodeproj \
            -scheme MyApp \
            -destination 'generic/platform=iOS Simulator' \
            -derivedDataPath ~/DerivedData/swift6-check \
            OTHER_SWIFT_FLAGS="-strict-concurrency=complete" \
            | xcbeautify --renderer github-actions

      - name: Upload build log on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: swift6-build-log-${{ github.sha }}
          path: ~/DerivedData/swift6-check/Logs/Build/

1. 01
   基线快照：在独占远程 Mac 上用 -strict-concurrency=minimal 跑一次全量编译，记录错误数与编译耗时，作为迁移起点的可量化基线。
2. 02
   叶子模块先行：从 SwiftPM 依赖图中找出无下游依赖的 target，逐一开启 complete。每个 target 修复完毕后提单独 PR，保持 diff 可审查。
3. 03
   CI 分支策略：在 Git 的 feature/swift6-migration 长期分支上以 warn-only（continue-on-error: true）运行并发检查 Job，不阻断日常 PR 合并。只有当某个模块达到 0 错误时，才将该模块的检查级别升级为门禁（block-merge）。
4. 04
   钉住 Xcode 版本：把 xcode-select 版本号写入 Runbook 与 README，确保本地 Mac 开发者与 CI 节点使用相同小版本，避免「本地过、CI 挂」的错误扰动。
5. 05
   错误趋势看板：把每次 CI 运行的 Swift 6 错误数写入结构化日志或 Build Metrics，用折线图跟踪迁移进度；给团队设置「本周减少 X 个错误」的周目标。
6. 06
   全量门禁验收：全部模块达到 0 错误后，在 main 分支的 Branch Protection Rule 里启用「Require swift6-concurrency-check to pass」，同时把 SWIFT_VERSION = 6 写入所有 target 的 Build Settings，正式切换 Swift 6 语言模式。

Swift 6 迁移期同时需要开发者本地快速试错与CI 全量可信验证，两者对节点的需求不同：