症狀：Swift 6.4 編譯器已升級，CI 卻開始出現並發診斷，團隊不確定是否要整個專案一起切換語言模式。Swift 6.4 已於 2026 年 9 月 15 日發布。
最快做法：先在現有語言模式下開啟並發檢查，再按 target 逐步遷移；需要 Xcode、Apple SDK 或 Apple 平台目標的工作，安排到符合專案要求的遠端 Mac CI 驗證。
適合負責 Swift 專案遷移、Apple 平台 CI 維護，或跨平台 Swift Package 工作流程的開發者與 DevOps 工程師。
若只需要一般跨平台建置，未必需要把所有工作搬到 Mac；若要驗證 Apple 平台交付，則需另外確認 Mac 工具鏈與測試任務。
[ SECTION_01 ] 第一步：先建立可比較的建置基線
遷移前先留一份基線。否則診斷變多時，很難判斷原因是編譯器、語言模式、建置設定，還是程式碼本身。
| 核對項目 | 記錄方式 | 為甚麼要分開看 |
|---|---|---|
| Swift 編譯器版本 | 在實際 CI 工作目錄記錄 swift --version，並保存 Xcode 版本資訊 |
不同節點可能呼叫不同工具鏈；版本更新不代表 target 語言模式同步改變 |
| target 語言模式 | 按 Xcode target 或 Swift Package target 記錄實際設定 | 遷移可以先限定在特定 target，不必假設整個專案採用同一模式 |
| 並發診斷與建置結果 | 保存建置指令、診斷輸出、測試結果與失敗紀錄 | 有對照資料，才能分辨新增診斷與原有失敗 |
官方遷移指南明確區分編譯器版本與語言模式，也說明遷移可按 target 推進。請從實際建置設定確認語言模式，勿只看 IDE 或工具鏈標示便判定已完成遷移。Swift 遷移指南說明了這些概念的邊界。
實作時可在 CI 保存 swift --version、xcodebuild -version、建置命令及完整輸出。Xcode 的版本與工具鏈對應關係，應按實際使用版本查閱 Apple Developer 的 Xcode 發布說明，不要從 Swift 編譯器版本反推某個 Xcode 版本必然包含該工具鏈。
[ SECTION_02 ] 第二步：維持原語言模式，先開啟並發診斷
不要把診斷與語言模式切換綁成一次變更。先在目前模式下檢查專案會遇到哪些並發問題，再判斷遷移範圍。
可以先在一個可控 target 開啟完整並發診斷，並在 CI 中保留輸出。將問題按資料隔離、Sendable、隔離邊界及相依套件分組；先標記來源，再安排修改。若診斷集中在跨模組傳遞的型別，應先確認型別是否真的可安全跨隔離區使用，而不是直接添加忽略或抑制處理。
Swift 官方遷移策略提供了先檢查、再處理、逐步擴大範圍的做法；增量遷移指南也支援逐部分採用，而非要求一次改完。實際診斷選項及設定方式仍須按目前工具鏈文件與專案建置方式確認。
[ SECTION_03 ] 第三步：挑選邊界清楚的 target 作為試點
試點不應只按程式碼量挑選。更重要的是依賴關係是否容易辨認、能否獨立建置，以及診斷是否能回溯到所屬模組。先挑一個責任清楚的 target，再核對它使用的資料型別、併發呼叫與跨模組介面。
處理診斷時，優先修正真正的隔離與安全問題。對 Sendable 宣告，要檢查型別所持有的狀態及使用方式；對 actor 或其他隔離邊界，要確認呼叫端如何跨越邊界。若問題來自尚未遷移的依賴或 Objective-C 介面，記錄依賴版本、診斷位置與暫行相容方式，並將這些事項列入後續複查。
官方列出的常見並發遷移問題可協助分類診斷。抑制訊息可以是暫時的相容措施，但不能當作並發安全已獲驗證的證據。
遷移決策條件
- 若 target 可獨立建置、依賴清楚，而且診斷能歸屬到明確模組，先在該 target 試點；保留原有模式的對照工作，確認結果後再擴大。
- 若診斷主要來自尚未遷移的外部依賴或 Objective-C 邊界，先記錄證據並保留相容路徑；不要為了消除警告而一次切換所有 target。
- 若工作只驗證跨平台 Swift 程式碼，可讓相符平台的現有 CI 繼續執行；若任務需要 Xcode 或 Apple 平台工具鏈，另設 Mac 工作階段，不以跨平台測試代替。
| CI 任務 | 可沿用非 Mac CI 的條件 | Mac 驗證的必要性 |
|---|---|---|
| 跨平台 Swift Package 建置與測試 | 目標平台與依賴均受該執行環境支援，且任務不要求 Apple SDK | 不需要只因採用 Swift 6.4 就搬到 Mac |
| Xcode 專案建置 | 不適用於依賴 Xcode 的建置流程 | 在符合專案要求的 Mac 與 Xcode 工具鏈中執行 |
| Apple 平台目標或 Simulator 測試 | 非 Mac 測試只能作為其他平台的補充 | 需用相符 Apple SDK、目標與 Simulator 設定驗證 |
| 發布產物驗收 | 可先在一般 CI 執行不依賴 Apple 工具鏈的檢查 | Apple 平台建置、測試與產物需在 Mac 工作流程中核對 |
[ SECTION_04 ] 常見問題：編譯器、語言模式與 CI 的界線
Swift 6.4 專案要怎樣逐步開啟並發檢查？
先記錄目前編譯器版本與各 target 的語言模式，再於試點 target 啟用完整並發診斷。按資料隔離、Sendable 與隔離邊界整理問題，逐項修正並保留診斷結果；不要一開始就把整個專案切到 Swift 6 語言模式。
升級 Swift 編譯器後，語言模式會自動切換到 Swift 6 嗎？
不會因為編譯器版本更新就推定語言模式已改變。編譯器版本、target 的 Swift 語言模式及並發檢查設定是不同項目，應從實際建置設定與編譯記錄逐一核對，再依專案狀況安排切換。Swift 版本相容性說明可用來確認版本與語言模式相關界線。
CI 可以逐個 target 遷移 Swift 並發檢查嗎？
可以。先選依賴關係清楚、可獨立建置的 target，在 CI 為它保留專屬診斷、建置與測試結果。確認依賴邊界和回退方式後，再擴大至其他 target；遇到尚未遷移的依賴時，記錄相容處理，不要把隱藏診斷當成完成。
Swift 並發遷移時，哪些 CI 建置和測試需要 Mac？
一般跨平台 Swift Package 任務可留在符合目標平台的既有 CI。若任務依賴 Xcode、Apple SDK、Apple 平台目標或 Simulator，就要在符合專案要求的 Mac 工具鏈中執行。Package 測試通過不能取代 Apple 平台建置、測試與交付產物驗收。
[ SECTION_05 ] 第四步：把試點變成可重現的 CI 工作
試點要能由 CI 重跑，而不是只在開發者電腦上驗證一次。為該 target 保存建置指令、工具鏈資訊、語言模式、並發診斷、測試結果與失敗輸出。將產物及測試報告與提交版本關聯，讓比較有明確依據。
可以按以下順序接入：
- 固定試點 target 與建置入口，讓本機和 CI 執行相同工作。
- 在工作開始時記錄實際 Swift 編譯器及 Xcode 資訊；不要只保存節點名稱。
- 保留 target 的語言模式設定，並單獨啟用要觀察的並發診斷。
- 分開執行建置與測試，分別保存退出狀態、診斷內容和產物。
- 對照遷移前基線，檢查新診斷、測試變化及是否能回退。
- 確認試點可重現後，再納入下一個 target；不符合條件時，暫停擴大並回到基線排查。
跨平台 Swift Package 可以在支援其目標的平台上執行相應工作，但這只能回答該環境涵蓋的問題。若工作流程需要 Apple SDK 或 Xcode，仍須獨立安排 Apple 平台驗證。
[ SECTION_06 ] 第五步：在遠端 Mac 驗收 Apple 平台工作
需要 Xcode、Apple SDK、Apple 平台目標或 Simulator 的任務，應在符合專案版本要求的 Mac 工具鏈中建置與測試。工具鏈版本不可憑 Swift 版本猜測；請按實際 Xcode 發布說明和專案相容性逐項核對。
遠端 Mac CI 的驗收應分開看三類證據：
- 環境證據：記錄 macOS、Xcode、Swift 編譯器及建置目標，並確認執行工作使用的是預期工具鏈。
- 建置與測試證據：保存 Apple 平台建置結果、測試報告、Simulator 或目標設定及失敗記錄。
- 交付證據：核對產物是否由預期工作流程產生，並確認產物與測試結果對應同一提交。
團隊若要拆分既有工作與 Mac 階段，可先閱讀 NOVAKVM 的 Mac 遠端使用入口，再按實際需要確認適用的遠端 Mac 方案資訊。這些資料不能取代專案自己的工具鏈相容性檢查；節點是否合用，仍以實際建置和測試結果為準。
[ SECTION_07 ] 第六步：按證據擴大、維持雙軌或暫緩
試點通過後，不必自動推進整個專案。比較遷移前後的診斷、測試結果、依賴狀況與回退難度，再決定接下來的範圍。若新增診斷仍集中在未遷移依賴，或 Apple 平台測試尚未通過，維持分階段工作比宣告完成更可靠。
| 結果狀態 | 適配評級 | 建議處理 |
|---|---|---|
| 診斷已處理，試點建置與測試可重現，Apple 平台驗收亦通過 | 適合擴大 | 逐個納入下一批 target，沿用相同記錄方式 |
| 跨平台測試通過，但 Apple 平台工具鏈尚未驗證 | 僅部分通過 | 保留非 Mac CI 任務，補上遠端 Mac 建置與測試 |
| 外部依賴或互通邊界仍造成未處理診斷 | 暫緩切換 | 記錄限制、維持相容設定，等待依賴或程式碼調整 |
| 回退方式不明，或測試無法重現 | 暫緩擴大 | 先修復 CI 對照與測試鏈路，再重新評估遷移 |
Swift 6.4 的遷移狀態應以實際 target、建置、測試及交付鏈路記錄，不以「編譯器已更新」或「警告消失」作為唯一完成條件。本文版本與步驟核對自 Swift.org 的 Swift 6.4 發布公告、遷移策略及 Apple Developer 的 Xcode 發布說明。最後更新於 2026 年 10 月 10 日；核實來源為上述官方資料，實際工具鏈仍須以目標專案及執行環境為準。
若現有 Linux 或其他非 Mac CI 已能處理跨平台 Package 工作，不必為了 Swift 並發遷移而全部替換；但它無法代替需要 Xcode、Apple SDK 或 Simulator 的驗收。自購 Mac 可掌握實體設備與長期環境，代價是採購、維護及節點管理；若只是為遷移試點增加 Apple 平台建置與測試，安排一台租用的遠端 Mac 作為獨立執行階段，通常更容易控制試點範圍。可先用 NOVAKVM 的遠端 Mac 進行實際工具鏈與 CI 驗證，再依長期負載決定是否保留。
常見問題
Swift 6.4 專案要怎樣逐步開啟並發檢查？
先記錄目前編譯器版本與各 target 的語言模式，再於試點 target 啟用完整並發診斷。按資料隔離、Sendable 與隔離邊界整理問題，逐項修正並保留診斷結果；不要一開始就把整個專案切到 Swift 6 語言模式。
升級 Swift 編譯器後，語言模式會自動切換到 Swift 6 嗎？
不會因為編譯器版本更新就推定語言模式已改變。編譯器版本、target 的 Swift 語言模式及並發檢查設定是不同項目，應從實際建置設定與編譯記錄逐一核對，再依專案狀況安排切換。
CI 可以逐個 target 遷移 Swift 並發檢查嗎？
可以。先選依賴關係清楚、可獨立建置的 target，在 CI 為它保留專屬診斷、建置與測試結果。確認依賴邊界和回退方式後，再擴大至其他 target；遇到尚未遷移的依賴時，記錄相容處理，不要把隱藏診斷當成完成。
Swift 並發遷移時，哪些 CI 建置和測試需要 Mac？
一般跨平台 Swift Package 任務可留在符合目標平台的既有 CI。若任務依賴 Xcode、Apple SDK、Apple 平台目標或 Simulator，就要在符合專案要求的 Mac 工具鏈中執行。Package 測試通過不能取代 Apple 平台建置、測試與交付產物驗收。