CI 顯示已安裝 Swift 6.4，但建置日誌仍無法證明工作實際用了它。
最快做法：先留存 CI 任務呼叫的 Swift 版本、執行路徑與命令，再用隔離工作對同一提交執行建置和測試；重現通過後才逐步推廣。Swift 官方確認 SwiftPM 預設使用 Swift Build，但這不代表所有 Xcode 專案都自動切換。Swift 6.4 發布說明
適合維護 Swift Package 建置流水線、需要核對依賴與測試結果的工程師。
也適合負責 macOS CI 的團隊，為工具鏈升級訂出試跑及回退條件。
若 CI 承載 Apple 平台工作，本文協助區分 SwiftPM 任務與 Xcode 專案流程。
最後更新於 2026 年 11 月 11 日；資料核實自 Swift 6.4 發布說明及 SwiftPM 6.4 官方文件。
[ SECTION_01 ] 先以實際執行入口界定驗收範圍
Swift 6.4 已於 2026 年 9 月 15 日發布，官方發布說明確認 SwiftPM 預設使用 Swift Build。發布日期與預設建置平台說明 可作為這次驗收的起點，不能代替專案驗證。
請把「機器裝了哪個版本」和「CI 任務用了哪個版本」分開。macOS 節點可能有不只一個工具鏈選擇入口；工作啟動方式、shell 環境或任務設定，都可能使執行結果與管理者在互動式終端看到的結果不同。應以任務日誌為準，不以節點清單或人工登入檢查代替。
在 CI 工作中留存下列輸出，並一併保存工作定義中實際呼叫的命令：
command -v swift
swift --version
xcode-select -p
swift --version 用來記錄該工作執行到的 Swift 版本；command -v swift 留下該 shell 找到的執行路徑。若工作直接指定其他工具入口，也要把該入口和任務命令納入紀錄。Swift 的 macOS 安裝文件提供工具鏈安裝與使用資訊；Apple 的 Xcode 命令列工具參考則可供核對相關命令列工具說明。
驗收資料至少要能回答：這是哪個提交、哪個 CI 工作、使用什麼執行入口，以及該工作實際執行了哪些 SwiftPM 或 Xcode 命令。缺少其中一項，版本輸出就很難和某次建置結果可靠對應。
[ SECTION_02 ] 依據證據完整度選擇切換方式
下表的可靠度是驗收證據完整度的定性評估，不是效能分數。若目標是判定變更是否可推廣，應優先採用能重現專案實際工作的隔離試跑，而不是只檢查版本。
| 做法 | 留存證據 | 驗收可靠度 | 適用判斷 |
|---|---|---|---|
| 只確認節點已安裝 Swift 6.4 | 節點工具鏈資訊，未必對應 CI 工作 | 低 | 只作環境盤點，不能據此批准切換 |
| 只在互動式終端查看版本 | 人工 shell 的路徑與版本，未必等同工作環境 | 中低 | 可協助定位，但還需在 CI 任務內重查 |
| 隔離工作執行原有建置與測試 | 同一提交、任務入口、工具鏈、依賴、日誌與結果 | 高 | 作為推廣前的主要驗收依據 |
| 直接替換正式工作流程 | 正式工作結果，但可能缺少可比較基線與回退依據 | 低 | 不建議在證據未齊時採用 |
切換判斷應落在可核對的差異上：工具鏈輸出是否吻合預期，依賴解析是否一致，建置目標與產物是否完整，測試是否實際執行，以及相同條件下能否重現。若只看到「工作成功」，卻沒有這些對應資料，不能把它當作完整驗收。
[ SECTION_03 ] 用同一提交核對依賴解析與鎖定結果
依賴差異會干擾工具鏈變更的判讀。應在切換前後使用同一提交，保持專案原有的依賴條件，並比較解析結果與鎖定檔。若專案使用私有依賴、套件鏡像或其他解析設定，也要留存相關設定及其來源。
Swift Package 的依賴宣告與套件管理方式可對照 Swift Package 依賴文件。驗收時，不要只記錄「解析成功」；還要保存鎖定檔是否改變、實際解析到的版本，以及差異是否能由工具鏈、設定或提交內容解釋。
鎖定檔出現差異，不等同 Swift 6.4 一定造成問題；未出現差異，也不代表後續建置與測試必然一致。若兩次執行的提交或依賴設定不同，先補齊條件再比較。若在相同條件下仍有差異，保留日誌與鎖定結果，定位變更來源後再決定是否暫緩。
[ SECTION_04 ] 建置與測試分開驗收，避免把成功訊息當通過
SwiftPM 工作應以專案實際使用的建置與測試任務為準。記錄執行的命令、目標、結束狀態和日誌；若工作預期產生套件或其他建置產物，也要確認產物確實生成，並且能對應到該提交。SwiftPM 6.4 的行為應參照官方版本文件，不要從單一成功訊息推斷所有目標都已完成。
建置成功和測試通過是兩項不同證據。測試驗收要留下實際發現及執行的測試、通過或失敗結果，以及未執行項目的原因。失敗時，保留首條錯誤及前後日誌；在條件相同時重跑，才有機會區分工具鏈差異、專案問題與 CI 環境差異。
特別要界定 SwiftPM 工作和 Xcode 專案、Apple 平台歸檔任務的邊界。SwiftPM 的預設建置平台變更，不能直接推論 Xcode 專案建置或歸檔流程也會自動改變。歸檔工作應按專案自己的命令與流程驗收，並參照 Apple 對 Xcode 歸檔流程的說明。Swift 工具鏈文件中的建置說明也可用於核對適用範圍，不能取代工作本身的日誌。Swift 建置文件
[ SECTION_05 ] 把快取與重跑列入可重現性驗收
快取會影響驗收證據是否能重現，但不能因某次使用快取的工作通過，就直接認定遷移穩定。應在相同提交與依賴條件下，分別記錄團隊預期的快取重用結果和清理後執行結果；若兩者不同，保存環境差異、日誌及重跑結果，再判定差異是否可接受。
這裡不應預設某種快取一定會造成或避免故障。不同工作可能採用不同快取範圍與流程，應核對 CI 實際設定。版本、路徑、依賴狀態、建置結果和測試結果要能互相對照；如需談特定快取行為，應以 Swift 官方文件或標明環境與日期的實測為依據，不能用單次成功替代證明。
[ SECTION_06 ] 以驗收紀錄決定推廣、暫緩或回退
可照以下步驟建立可複核的試跑紀錄：
- 固定要驗收的提交，記下工作名稱與預期任務，不混用不同分支或依賴條件。
- 在 CI 任務內輸出 Swift 版本、執行路徑及實際呼叫的命令，確認驗收對象不是人工終端環境。
- 對照切換前後的依賴解析與鎖定檔；若有差異，先找出可重現來源。
- 執行專案原有的 SwiftPM 建置及測試工作，分別記錄結束狀態、目標、產物和測試結果。
- 在團隊要求的快取條件下重跑，保存環境差異及日誌，確認結果能否重現。
- 對照驗收證據作決策：結果一致且可重現，才逐步推廣；失敗原因仍不明或證據缺漏，就暫緩並保留原流程；若差異影響必要目標，回退至已知可用的工作設定，再繼續排查。
通過代表工具鏈、依賴、建置及測試證據都對應同一提交，必要工作可重現。暫緩適用於結果不完整、差異未定位或重跑不一致。回退則用於新流程無法滿足專案必要任務，且團隊需要先恢復既有可用路徑。這是專案准入判斷，不是對所有 Swift Package 的相容性結論。
[ SECTION_07 ] 常見問題
Swift 6.4 的 SwiftPM 預設建置平台變更代表什麼？
Swift 官方發布說明指出，SwiftPM 預設使用 Swift Build。這說明的是 SwiftPM 的預設建置平台，不表示所有 Xcode 專案、歸檔工作或 CI 任務都會自動改用相同流程。應確認任務實際呼叫的工具與命令，再用專案建置及測試結果驗收。
如何確認 macOS CI 工作實際執行的是 Swift 6.4？
在 CI 工作本身留存 Swift 版本輸出與執行路徑，並核對工作定義呼叫的命令及執行帳戶。只查看節點已安裝的工具鏈，不足以證明任務使用了它；應以該工作日誌中的實際輸出為準。
升級 Swift 6.4 後 Swift Package 建置失敗，先檢查什麼？
先比對同一提交的工具鏈版本與路徑，再核對依賴鎖定結果、私有依賴或鏡像設定，以及首條建置錯誤。接著確認目標與測試是否實際執行，並在相同條件下重跑。先定位可重現的差異，不要把單次環境故障直接判成工具鏈相容性問題。
Swift 6.4 適合直接切換正式 macOS CI 嗎？
不宜只因工具鏈已發布就全面切換。先以隔離工作使用既有提交和依賴條件完成建置、測試與重跑驗證；結果可重現、失敗可定位且產物符合要求後，再逐步推廣。若證據不完整，先保留原工作流程並延後切換。
如果團隊目前只能依賴共用的 Linux 工作或個人 Mac 來驗證，前者無法代替 macOS 工具鏈任務，後者則可能難以讓整個團隊重現相同環境。當缺少獨立的 macOS 試跑節點時，可先比較遠端 Mac 的租用方案，判斷是否適合承載隔離建置與測試。需要短期驗證工具鏈或建立可重複的試跑環境時，NOVAKVM 可作為比較選項；若工作長期穩定、負載固定，或必須直接連接實體介面，則應先評估自有 Mac 是否更合適。查看 NOVAKVM 的 Mac 服務，再依工作週期與驗收需求決定是否租用。
常見問題
Swift 6.4 的 SwiftPM 預設建置平台變更，實際代表什麼？
Swift 官方發布說明指出，SwiftPM 預設使用 Swift Build。這項變更說明的是 SwiftPM 的預設建置平台，不代表所有 Xcode 專案、歸檔工作或 CI 工作都會自動改用相同流程。應先確認任務實際呼叫的工具與命令，再以專案建置和測試結果驗收。
如何確認 macOS CI 工作實際執行的是 Swift 6.4？
在 CI 工作本身留存 Swift 版本輸出與執行路徑，並核對工作定義呼叫的命令及其執行帳戶。只查看節點已安裝的工具鏈不足以證明任務使用了它；若 shell 初始化、工具選擇或執行環境不同，應以工作日誌中的實際輸出為準。
升級 Swift 6.4 後 Swift Package 建置失敗，應先查哪些項目？
先比對同一提交的工具鏈版本與路徑，再核對依賴鎖定結果、私有依賴或鏡像設定，以及首條建置錯誤。接著檢查建置目標和測試是否真的執行，最後在相同條件下重跑。先定位可重現的差異，避免把單次環境故障直接判成工具鏈相容性問題。
Swift 6.4 可以直接切換正式 macOS CI 嗎？
不宜只因工具鏈已發布就直接全面切換。先以隔離工作使用既有提交和依賴條件完成建置、測試及重跑驗證；只有結果可重現、失敗可定位，而且目標任務的產物符合要求，才逐步推廣。若證據不完整，先保留原工作流程並延後切換。