云端 Mac 上定位 Swift 编译器崩溃：从现场保全到最小复现

同一提交在开发机上能通过，却在云端 Mac 的持续构建中让 swift-frontend 异常退出。重跑偶尔成功，清空缓存后又换了一个文件失败。此时最危险的动作是连续修改源码、升级依赖和删除全部缓存：现场被同时改变，真正触发编译器崩溃的条件也随之消失。更稳妥的做法是先确认故障类型，再按单一变量原则缩小范围。

先确认它是不是编译器崩溃

CompileSwiftSources 失败不等于编译器崩溃。语法错误、类型推断失败、模块缺失也会在这个阶段返回非零状态。真正值得进入本文流程的信号包括：

• 日志明确写出 swift-frontend 异常退出或 signal 11。
• 输出包含 Stack dump、内部断言失败或编译器调用栈。
• ~/Library/Logs/DiagnosticReports/ 出现时间吻合的 swift-frontend 报告。
• 相同源码和命令可以多次触发，而不是一次性的远程会话中断。

先记录工具链和主机信息，不要只截取日志最后十行：

mkdir -p diagnostics
{
  date -u
  sw_vers
  uname -m
  xcode-select -p
  xcodebuild -version
  xcrun swiftc --version
} | tee diagnostics/environment.txt

find "$HOME/Library/Logs/DiagnosticReports" \
  -maxdepth 1 -type f -name 'swift-frontend*' \
  -exec cp {} diagnostics/ \;

崩溃报告、完整构建命令和触发源码必须来自同一次复现。把不同轮次的材料拼在一起，往往会形成无法验证的假线索。

用隔离构建保住第一现场

为复现单独准备 DerivedData，并把终端输出完整保存。不要一开始就删除全局缓存，因为缓存是否参与触发本身就是待验证变量。

set -o pipefail
rm -rf "$PWD/.diagnostics-derived-data"

xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Debug \
  -destination 'generic/platform=iOS Simulator' \
  -derivedDataPath "$PWD/.diagnostics-derived-data" \
  -jobs 1 \
  build 2>&1 | tee diagnostics/build-single-job.log

这里把并发度降到一，只用于判断崩溃是否与并行编译有关，不代表长期配置。若单任务仍稳定崩溃，保留该日志；若故障消失，再以固定源码、固定 DerivedData 分别测试 -jobs 2 和日常并发值。每组至少重复三次，并记录成功、普通编译错误或编译器崩溃，不能只写“失败”。

在 OVPS 云端 Mac 上复现时，也应记录实际选择的 Xcode 路径。仅比较界面显示的版本名不够，同一主版本下的构建号和 Swift 工具链仍可能不同。

建立单一变量对照矩阵

排查顺序应从成本最低、破坏最小的变量开始。每次只改一项，并复制一份新日志。

不要同时切换 Xcode、更新依赖并清缓存。若切换工具链后问题消失，只能说明故障与工具链组合相关，不能直接证明新版本已经修复。还要把失败文件、编译模式和触发次数放在同一张记录里。

识别缓存假象

只有当空 DerivedData 能通过、旧目录稳定失败时，才进一步检查模块缓存和构建数据库。先归档问题目录，再做定点清理。若直接执行大范围删除，就失去了比较旧产物与新产物的机会。

从失败文件缩减到最小复现

在完整日志中找到失败的 Swift 编译任务。若问题可脱离工程重现，复制相关声明到 Repro.swift，先用类型检查验证：

xcrun swiftc -typecheck Repro.swift 2>&1 | tee diagnostics/repro.log

缩减时按依赖反方向操作：先删无关方法，再删协议实现、泛型约束和属性包装；每删一块就运行一次判定脚本。不要凭肉眼猜测某段语法“看起来复杂”，编译器崩溃经常由两个普通特性的组合触发。

#!/bin/zsh
set -o pipefail

output="$(mktemp)"
xcrun swiftc -typecheck Repro.swift >"$output" 2>&1

if grep -Eiq 'signal 11|segmentation fault|stack dump|swift-frontend.*failed' "$output"; then
  cp "$output" diagnostics/latest-crash.log
  rm -f "$output"
  exit 0
fi

rm -f "$output"
exit 1

这个脚本把“仍然触发目标崩溃”定义为成功，便于配合人工二分或源码缩减工具。每次缩减后还要确认错误签名一致；如果从内部断言变成普通类型错误，说明已经删掉关键条件。

若单文件无法复现，就保留最小模块边界：一个精简工程、必要的构建设置、锁定的依赖版本和一条执行命令。不要携带业务数据、访问凭据或无关资源。

形成可复查的交付包

最终材料应让另一台云端 Mac 在没有口头说明的情况下完成验证。建议目录只包含：

• README.md：预期现象、执行命令、重复次数和实际结果。
• environment.txt：系统架构、Xcode 构建号与 Swift 版本。
• Repro.swift 或精简工程：只保留必要源码。
• build.log：未经截断的标准输出与错误输出。
• 崩溃报告：与该次执行时间对应的诊断文件。
• check.sh：用退出状态明确表示是否复现目标崩溃。

交付前在新目录重新执行一次，确认脚本没有依赖原工程的绝对路径、用户目录或残留模块缓存。若问题只在特定并发度出现，就把并发参数和复现概率写清楚；若只在某个工具链构建号出现，则同时记录可通过的对照版本。这样得到的不是一句“Swift 偶尔崩了”，而是一组可以重复、比较和继续修复的工程证据。

常见问题