云端 Mac 多版本 Xcode 固定与可复现构建

同一台云端 Mac 同时承载稳定分支、日常开发分支和升级验证分支时，最容易被忽略的变量不是代码，而是当前生效的 Xcode。某个任务执行了全局切换，后续流水线就可能悄悄换用另一套 Swift 编译器或 SDK。结果往往表现为本地能编译、远程失败，或者同一提交隔天生成不同的构建结果。

先把工具链当成项目依赖

Xcode 不应只是机器上的一个图标，而应像语言运行时一样被明确记录。建议保留版本化目录，不要让新安装包直接覆盖旧目录：

/Applications/Xcode_16.1.app
/Applications/Xcode_16.2.app
/Applications/Xcode_16.3.app

先盘点现有安装和当前全局选择：

find /Applications -maxdepth 1 -name 'Xcode*.app' -print
xcode-select --print-path
xcodebuild -version
xcrun --find swift
swift --version

记录时至少包含 Xcode 版本、构建号、Swift 版本和项目使用的 SDK。只写“使用最新版”无法复现历史构建，也无法判断失败来自代码还是工具链变化。

版本固定的目标不是拒绝升级，而是让升级成为一次可观察、可回退的工程变更。

按作用域选择 Xcode

选择方式应根据任务范围决定。全局默认值适合人工维护，任务级环境变量更适合自动化。

需要修改全局默认值时，可以执行：

sudo xcode-select --switch /Applications/Xcode_16.2.app/Contents/Developer

CI 中不要反复执行这条命令。应在任务开始时设置：

export DEVELOPER_DIR="/Applications/Xcode_16.2.app/Contents/Developer"
xcodebuild -version
xcrun --sdk iphoneos --show-sdk-version

DEVELOPER_DIR 会传递给子进程，因此后续的 xcrun、swift 和 xcodebuild 会从同一套 Developer 目录解析工具。不同流水线可以各自设置不同路径，而不争抢全局状态。

用预检脚本阻止静默漂移

仅在日志中打印版本还不够。预检应在版本不符时立即结束任务，避免花十几分钟编译后才暴露问题。下面的脚本固定 Xcode 16.2，并确认应用目录、实际版本、SDK 和 Swift 路径：

#!/bin/bash
set -euo pipefail

XCODE_APP="/Applications/Xcode_16.2.app"
EXPECTED_VERSION="16.2"

test -x "$XCODE_APP/Contents/Developer/usr/bin/xcodebuild"
export DEVELOPER_DIR="$XCODE_APP/Contents/Developer"

ACTUAL_VERSION="$(xcodebuild -version | awk 'NR == 1 {print $2}')"
test "$ACTUAL_VERSION" = "$EXPECTED_VERSION"

echo "developer=$DEVELOPER_DIR"
echo "xcode=$ACTUAL_VERSION"
echo "swift=$(xcrun --find swift)"
echo "sdk=$(xcrun --sdk iphoneos --show-sdk-version)"

xcodebuild -checkFirstLaunchStatus

把脚本放入仓库，例如 ci/verify-toolchain.sh，让版本要求随代码评审。升级时同时修改脚本和项目文档，变更记录会比主机上的手工操作更可靠。

如果项目对 SDK 有明确要求，可以增加精确判断。不要根据 Xcode 主版本猜测 SDK，因为同一系列的不同版本可能携带不同 SDK。

构建命令也要显式化

预检通过后，再执行固定入口的构建：

export DEVELOPER_DIR="/Applications/Xcode_16.2.app/Contents/Developer"

xcodebuild \
  -workspace Example.xcworkspace \
  -scheme Example \
  -configuration Release \
  -derivedDataPath "$PWD/.derived-data" \
  CODE_SIGNING_ALLOWED=NO \
  build

这里显式指定工作区、scheme、配置和 Derived Data 路径。CODE_SIGNING_ALLOWED=NO 只适合不需要签名的编译验收；归档或设备构建应使用项目已有的安全签名流程，不能照搬该参数。

新版本先并行验证再切换

安装新 Xcode 后，先保留旧版，让升级验证使用独立任务运行。首次准备可以由管理员执行：

sudo DEVELOPER_DIR="/Applications/Xcode_16.3.app/Contents/Developer" \
  xcodebuild -runFirstLaunch

随后对同一提交分别运行旧版和新版，比较编译是否通过、测试数量、警告变化、产物架构以及归档元数据。不要一开始就删除旧目录，否则依赖或编译参数不兼容时缺少快速回退路径。

升级验收还应检查项目格式是否被自动改写。若新版 Xcode 修改工程文件，应把改动作为独立提交审查，不要与业务代码混在一起。这样可以区分工具自动迁移、依赖更新和真正的功能修改。

常见踩坑与交付检查

第一个坑是只切换 xcode-select，却忘记任务环境中残留的 DEVELOPER_DIR。环境变量优先级更高，日志看到的全局路径不等于任务实际路径。第二个坑是直接把应用命名为 Xcode.app，升级覆盖后无法判断旧任务使用了什么。第三个坑是只验证编译器，不验证 SDK 与 xcrun 路径，最终混入非预期工具。

交付前按以下顺序检查：

1. Xcode 应用目录含明确版本号，旧版仍可用。
2. 仓库中记录期望版本，而不是依赖人工记忆。
3. 每个 CI 任务单独设置 DEVELOPER_DIR。
4. 预检同时核对 Xcode、Swift、SDK 和工具路径。
5. 构建命令显式指定 workspace、scheme 与配置。
6. 新版本通过编译、测试和产物检查后再设为默认。
7. 并行任务不修改全局 xcode-select。

完成这些步骤后，云端 Mac 的工具链状态就能随日志追踪。出现构建差异时，可以先排除版本漂移，再调查依赖、代码和任务配置，而不是在多个变量之间盲目试错。

常见问题