CI 在雲端同步目錄完成建置，卻在程式碼簽章階段失敗。
最快的處理方式：若失敗發生於 macOS 14 或以上版本，且實際建置產物位於雲端同步目錄，Swift 6.4.2 公告列出的修復值得在隔離 CI 試跑；先確認實際工具鏈與產物路徑，再以同一提交做路徑對照，不要只憑版本號宣告故障已排除。Swift 6.4.2 已於 2026 年 10 月 30 日發布，公告指出 Xcode 27.2 包含此工具鏈。(forums.swift.org)
適合閱讀的對象：維護 Swift Package 或 Apple 平台專案 CI 的工程師，需要比對修復描述與自身錯誤。
負責 macOS 建置節點的 DevOps 工程師，需要查明活動工具鏈、工作目錄與簽章結果。
發布負責人則可依驗收證據決定分批升級、暫緩，或移動工作區。
最後更新於 2026 年 11 月 1 日；版本與修復範圍核對自 Swift 6.4.2 官方公告及 Apple Developer Xcode 發布資訊。
修復範圍先對照故障發生位置
Swift 6.4.2 公告所列的是：在 macOS 14 及更新版本，於雲端同步目錄內建置時發生的程式碼簽章失敗修復。這是明確的適用線索，不是所有 codesign 錯誤都能套用的通用修正。(forums.swift.org)
Swift 6.4.2 修復了哪些 macOS 雲端同步目錄簽章問題？
官方公告描述的是「在同步目錄內建置時的簽章失敗」。公告沒有承諾所有專案、所有同步工具或所有簽章錯誤都會因此消失。因此，先留存失敗階段、錯誤原文、作業系統版本，以及倉庫和實際建置產物的位置；若錯誤發生在憑證讀取、權限檢查或上傳流程，不能只因工作區位於同步目錄就斷定符合修復範圍。
| 驗收觀察項目 | 符合公告描述的線索 | 尚不足以判定的情況 |
|---|---|---|
| 作業系統 | macOS 14 或更新版本 | 其他版本，或 CI 日誌未記錄系統版本 |
| 建置位置 | 簽章所需的建置輸入或產物確實位於雲端同步目錄 | 只有原始碼倉庫在同步目錄，產物路徑未知 |
| 失敗階段 | 建置流程中的程式碼簽章失敗 | 憑證、權限、提交或發佈步驟失敗 |
| 工具鏈 | 確認實際使用 Swift 6.4.2 | 只看 Xcode 應用程式名稱，未確認命令實際呼叫對象 |
工具鏈紀錄要能對應到 CI 實際呼叫
Swift 6.4.2 可透過獨立 Swift 工具鏈安裝；官方公告亦指出 Xcode 27.2 包含 Swift 6.4.2。Apple 發布資訊列出 Xcode 27.2 的正式發布日期為 2026 年 10 月 29 日。兩種安裝方式不應混成同一項紀錄：節點裝了某個 Xcode，不代表每個工作都使用該 Xcode 的 Swift。(forums.swift.org)
Swift 官方公告確認的 Xcode 27.2 工具鏈內容
官方公告明確列出包含關係；但驗收仍須記下 CI 執行時所選的 Xcode、活動 Developer 目錄，以及實際執行的 Swift 版本。Apple 說明，xcode-select --print-path 可顯示活動 Developer 目錄，而 DEVELOPER_DIR 可在單次命令中指定不同的 Xcode 目錄。(developer.apple.com)
在發生問題的 CI 工作中，將下列命令放在建置與簽章步驟之前。若 CI 另有設定 DEVELOPER_DIR、TOOLCHAINS 或包裝腳本，也要一併保留其值與命令執行環境。
sw_vers
xcode-select --print-path
xcodebuild -version
command -v swift
swift --version
xcrun --find swift
xcrun swift --version
輸出要連同工作識別資訊保存，避免只截取一行版本字串：
ProductName: macOS
ProductVersion: <CI 實際輸出>
/Applications/<實際選用的 Xcode>.app/Contents/Developer
Xcode <實際輸出>
Build version <實際輸出>
<swift 執行檔路徑>
Apple Swift version <實際輸出>
以上是紀錄格式示意，不是預期輸出的固定版本。若 swift --version 與 xcrun swift --version 顯示的工具鏈資訊不一致，先查清 PATH、活動 Xcode 與 CI 環境變數，再進入修復驗收。Apple 的命令列工具設定說明也列出活動目錄和臨時選用目錄的查核方式。
路徑對照要追到簽章輸入與最終產物
同步目錄中的原始碼，不等於簽章產物也在同步目錄。倉庫、Derived Data、Archive、匯出目錄及簽章輸入檔可能分散在不同位置；只記錄倉庫位置，無法證明失敗產生於公告所指的建置情境。
先從 CI 日誌或建置設定取出這些路徑，並記下解析後的實際位置：
pwd
printf 'HOME=%s\n' "$HOME"
printf 'TMPDIR=%s\n' "$TMPDIR"
對 Xcode 工作，另將實際使用的 Derived Data、Archive 與匯出路徑寫入驗收紀錄。不要把示例路徑當成固定預設值；工作流程可能透過參數、環境變數或腳本覆寫輸出位置。
| 對照試跑 | 保持不變的條件 | 要比較的證據 |
|---|---|---|
| 同步目錄建置 | 提交、工具鏈、建置參數、簽章設定與節點條件 | 失敗階段、錯誤輸出、產物路徑與簽章驗證 |
| 非同步目錄建置 | 與對照組相同，僅調整工作區及相關產物位置 | 是否仍在相同步驟失敗、是否出現不同錯誤 |
| 修補工具鏈重測 | 使用相同提交及可追溯的工具鏈選擇 | 建置、簽章與產物驗證各自的結果 |
確認 CI 實際執行 Swift 6.4.2 的方法
在 CI 工作本身執行版本查核，並保存執行檔位置、xcodebuild -version、Swift 版本輸出及相關環境變數；不要用管理介面顯示的節點安裝清單代替執行證據。若使用獨立安裝工具鏈，記錄其實際選用方式；若使用 Xcode，記錄活動 Developer 目錄與該 Xcode 的版本輸出。Apple 的 Xcode 系統需求與工具鏈資訊可用來交叉核對 Xcode 對應的 Swift 資訊，但 CI 實際輸出仍是判讀自身工作的關鍵。
建置成功不等於交付簽章已驗收
同一個提交應分別記錄建置、簽章和產物驗證，並把日誌、產物位置及驗證結果相互關聯。如此才能分辨失敗究竟消失、移到另一個階段，還是只在某次執行中沒有重現。
升級後程式碼簽章仍失敗，應檢查哪些建置證據？
先確認 CI 選到的工具鏈是否與預期相符，再核對簽章輸入和輸出是否真的在對照的目錄中；接著檢查錯誤發生於建置、簽章命令還是簽後產物驗證。若是 app bundle，可依交付型態使用適當的驗證工具。Apple 的簽章檢查技術說明指出，codesign --verify 檢查簽章一致性，但這不等於已確認應用程式適用於每種發佈目的。
codesign --verify --deep --strict --verbose=2 "/path/to/YourApp.app"
這裡的路徑應指向該次 CI 的實際產物。Apple 亦提醒，--deep 適用於驗證巢狀程式碼，不應被當成簽署時的通用補救方式；遇到失敗時，保留完整錯誤及指出的子元件，繼續定位具體問題。可參考 Apple 的macOS 程式碼簽章技術說明。
用可勾選紀錄決定試跑、推廣或回退
請在升級或調整路徑前完成下列核對。任一關鍵項目尚未確認，都應將結果標記為「未定」，而不是把單次成功寫成已修復。
- [ ] 記錄 CI 的 macOS 版本、失敗階段與完整簽章錯誤。
- [ ] 保存倉庫、Derived Data、Archive、簽章輸入與輸出的實際路徑。
- [ ] 在建置工作中執行版本命令，確認 Swift 與 Xcode 的實際選用結果。
- [ ] 使用同一提交及相同建置、憑證條件，對照同步與非同步工作路徑。
- [ ] 分開記錄建置、簽章及產物驗證結果，並保留對應日誌與產物識別資訊。
- [ ] 若結果符合預期，先在隔離 CI 重複觀察；確認團隊所需工作流程都能驗收後，再分批推廣。
- [ ] 若工具鏈或路徑不符公告情境，先調整工作區或繼續查錯，不把升級當成唯一修復手段。
決策可依證據分流：修復範圍、工具鏈及路徑都吻合，且同提交的對照結果支持問題已排除時，進入隔離節點試跑；只有部分吻合時，維持小範圍驗證並補齊紀錄；若實際路徑不在同步目錄，或錯誤屬於憑證、權限等其他階段，保留原環境並沿著該階段排查。一次成功只代表該次提交和條件下的觀察，不能推論長期穩定，也不能據此宣稱效能有所提升。
如果團隊目前依賴共用 CI 節點，工具鏈選擇不一致、工作目錄難以隔離、建置期間節點被其他任務干擾，都可能讓對照結果難以解讀。若需要一個獨立的 macOS 執行環境來試跑與驗收，可評估 NodeMini 的遠端 Mac 方案，先把工具鏈、提交和產物路徑固定，再決定是否適合納入 CI。若團隊只需了解可用的遠端 Mac 選項，也可由 NodeMini 的遠端 Mac 資訊頁開始；若工作長期固定、需要實體介面或本機除錯，則應把自購 Mac 與現有節點一併納入評估。