如何安全清理 Swift Package Manager 快取

SwiftPM 快取不止一層

Swift Package Manager 會在不同範圍儲存不同類型的可再生資料。命令列包通常有一個 .build 目錄，裡面包括依賴檢出、倉庫資料、建置產物和工作區狀態。SwiftPM 還維護共享倉庫快取，讓多個專案不必反覆從網路下載同一份依賴。

Xcode 又增加了一層。App 使用 Swift Package 時，包的檢出與建置產物通常跟隨專案的 DerivedData。因此，同一個依賴如果只在 Xcode 內出問題，處理方法可能與直接執行 swift build 不同。

最安全的原則是：只清理足以解釋當前問題的最小範圍。一次建置失敗，不等於要抹掉全域快取。專案級清理恢復更快，更可能在離線狀態下完成，也不會拖慢其他倉庫。

三個 SwiftPM 命令，作用範圍完全不同

SwiftPM 官方文件把三個命令的職責分得很清楚。swift package clean 刪除當前包的建置產物。遇到舊編譯結果、莫名其妙的連結問題，或只想回收某一個倉庫的空間時，應先用它。

swift package reset 會重置當前包完整的快取與建置目錄。它比 clean 更徹底，可能讓該包的依賴和工作區狀態重新準備。只有 clean 沒解決本地包工作區損壞或不一致時，才需要升級到 reset。

swift package purge-cache 清理的是 SwiftPM 全域共享的倉庫快取。之後多個專案都可能重新聯網獲取依賴，首次解析與建置也會變慢。它適合處理確實異常膨脹或損壞的共享快取，不適合變成每次建置前的固定儀式。

1. 先提交或暫存原始碼改動，確認 Package.swift 和 Package.resolved 仍在專案應有的位置。
2. 進入包根目錄，執行 swift package clean，再重試原來的建置。
3. 如果包級工作區仍然不一致，執行 swift package reset，然後重新解析和建置。
4. 只有確認共享倉庫快取過大或損壞時，才執行 swift package purge-cache。
5. 在清理 Xcode DerivedData 前，先核對依賴圖和命令列建置是否已經恢復。

命令是否可用取決於當前安裝的 Swift 工具鏈。先執行 swift package --help，確認這台 Mac 支援哪些子命令。

不要把 Package.resolved 當快取刪

Package.resolved 記錄的是依賴解析結果，不是下載快取。對 App 專案來說，把它納入版本控制，可以讓團隊成員和 CI 使用一致的依賴版本。刪除後，下一次解析可能選中 Package.swift 允許範圍內的其他版本。

當你明確想重新解析全部依賴時，刪除它可以是一項有意識的排查動作，但這已經改變了實驗變數。如果目標只是騰空間或重建產物，就應該保留 Package.resolved，避免一次清快取悄悄變成依賴升級。

Package.swift 更是原始碼，任何快取清理都不應該刪除或隨意修改它。同理，Sources、Tests、外掛和本地路徑依賴也是專案內容。生成的 .build 可以再生，作者寫下的檔案卻未必能夠恢復。

清理 Xcode 專案使用的 Swift Package

如果依賴由 Xcode 專案使用，可以先嘗試 File > Packages > Reset Package Caches；隨後用 File > Packages > Resolve Package Versions，按專案與解析檔案重新恢復依賴圖。不同 Xcode 版本的選單名稱可能略有差異。

如果問題出在該專案編譯後的包產物，刪除對應專案的 DerivedData 即可。可以透過 Xcode Settings > Locations 開啟位置，再在 Finder 中只處理那一個專案資料夾。下次建置會重新編譯 App 和包，並重建索引。

只有一個專案受影響時，不要順手清空整個 DerivedData 根目錄。保留每天活躍專案的熱快取，可以少付很多編譯時間。如果 Mac 上裝有多套 Xcode，重新解析前先啟動真正要使用的版本，讓正確的工具鏈和平台支援參與建置。

先診斷，再清快取

為了磁碟空間，應該先測量各倉庫的 .build 與共享快取，而不是憑感覺。搜尋廢棄專案裡的 .build，經常比抹掉仍在為活躍專案加速的全域快取更划算。

為了建置故障，則要先儲存原始錯誤。認證失敗、Git 服務不可用、Package manifest 無效、工具鏈不相容、校驗和變化，都不會因為刪掉下載檔案而自動修好。過早清快取還可能抹掉線索，並額外引入一次網路失敗。

清理後，用 swift package show-dependencies 或 Xcode 的包依賴圖核對解析結果，並執行真正相關的測試。依賴能成功下載，不代表它就與當前工具鏈、平台或部署目標相容。

開發機與 CI 應採用不同策略

開發機適合選擇性清理：倉庫長期不再使用時刪掉本地建置產物，只要全域倉庫快取仍在節省下載時間就不必動它。CI 則不同，臨時 Runner 可以每次從乾淨環境開始；長期 Runner 需要明確的體積預算，快取鍵還應包含 Swift 工具鏈與依賴解析狀態。

不要在每次建置前執行 purge-cache。那會放棄複用、增加網路依賴，並讓限流或上游故障更難受。只有測量顯示異常增長、確認快取完整性有問題，或長期 CI 節點到了受控維護視窗時，才值得清理全域快取。

故障記錄裡也要寫清範圍。「清過 SwiftPM 快取」含糊不清；「在倉庫 A 執行 swift package clean」和「清空全域倉庫快取」的影響面與恢復成本完全不同。

用 AskClean 找到周邊的開發者儲存

AskClean 可以盤點 SwiftPM 周圍的大型開發者儲存，包括各專案 Xcode DerivedData、倉庫建置產物、npm 等已宣告的包快取、模擬器資料和無法歸類的大資料夾，並說明每項是否可重建。

SwiftPM 自身仍應以官方 Swift 命令定義的作用範圍為準。AskClean 適合告訴你真正佔空間的是哪一類，而不是把精確的包管理操作變成一次解釋不清的批次刪除。

SwiftPM 命令作用範圍

按問題範圍與恢復成本選命令，不要預設選擇最激進的那個。

常見問題