雲端 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

這裡明確指定了 workspace、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 的工具鏈狀態。建置結果出現差異時，可以先排除版本漂移，再調查相依套件、程式碼與工作設定，而不必在多個變數之間盲目試錯。

常見問題