如何安全清除 Swift Package Manager（SPM）快取

SwiftPM 快取不只一種

Swift Package Manager 會在不同範圍儲存各種可以重新產生的資料。命令列套件通常有一個 .build 目錄，裡面有簽出的原始碼（checkouts）、儲存庫資料、建置輸出與工作區狀態。SwiftPM 也維護一份共用的儲存庫快取，讓多個專案不必每次都從網路下載相同的依賴套件。

Xcode 又多了一層。App 使用 Swift 套件時，套件的 checkout 與建置產物通常跟著專案的 DerivedData 走。因此，只在 Xcode 裡出現的套件問題，處理方式可能和用 swift 命令列工具建置同一個套件時不同。

最安全的原則是：只清理足以解釋症狀的最小範圍。不要因為一次建置失敗，就直接抹掉所有全域快取。專案層級的清理復原得比較快，比較常能在離線狀態下完成，也不會拖慢不相關的儲存庫。

選對 SwiftPM 指令

SwiftPM 官方文件列出三個範圍刻意不同的指令。swift package clean 會刪除該套件的建置產物；遇到過時的編譯結果、莫名其妙的連結器問題，或只想回收單一儲存庫的空間時，應該先用它。

swift package reset 會重置該套件完整的快取與建置目錄。範圍比 clean 大，可能讓該套件的依賴與工作區狀態都得重新準備；clean 解決不了本機套件工作區損毀或不一致的問題時，再改用它。

swift package purge-cache 會清除 SwiftPM 的全域儲存庫快取。這會影響各專案共用的下載加速，之後在多個儲存庫解析或建置時，可能都需要連網、也會比較久。請只在全域快取確實過大或損壞時使用，不要當成例行的建置保養。

1. 先提交（commit）或暫存（stash）原始碼變更，並確認 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 套件

如果是 Xcode 專案使用的套件依賴，先用 File > Packages > Reset Package Caches（前提是你安裝的 Xcode 版本有這個指令），再用 File > Packages > Resolve Package Versions，依專案與解析檔重新建立依賴關係圖。選單名稱可能因 Xcode 版本而異。

如果問題出在該專案編譯好的套件產物，就透過 Xcode 的 Settings > Locations 或 Finder，只刪除那個專案的 DerivedData。這會把產生出來的 App 與套件輸出一起移除，之後第一次建置會重新編譯並重建索引。

只有一個專案受影響時，別把整個 DerivedData 根目錄都刪掉；保留常用專案的快取，只移除相關的專案資料夾。如果這台 Mac 裝了好幾套 Xcode，解析套件前先開啟真正要用的那個版本，讓它的工具鏈與平台支援來負責重建。

先診斷，再清快取

如果是磁碟空間吃緊，就實際測量各個 .build 目錄與共用快取，不要用猜的。搜尋儲存庫裡的 .build 資料夾，常會找到早已棄置的 clone；清掉它們產生的輸出，比抹掉仍在替進行中工作加速的全域快取划算。

如果是建置失敗，先記下原始錯誤。驗證失敗、Git 主機無法連線、套件資訊清單（manifest）無效、tools version 不相容，以及 checksum 變動，都不會因為刪掉下載檔就自動修好。刪除快取反而可能抹掉線索，還多出一次網路失敗。

清理後，用 swift package show-dependencies 或 Xcode 的套件依賴關係圖，和預期的解析結果比對，並執行相關的測試，而不只是看解析成功。依賴套件可能下載得很順利，卻仍與你的部署目標或工具鏈不相容。

團隊與 CI 的維護策略

開發用筆電適合選擇性清理：儲存庫不再使用時，刪掉套件本機的建置輸出；全域儲存庫快取只要還能省下下載時間，就保留下來。CI runner 則不同：用完即丟的 worker 每次都可以從乾淨狀態開始，長期運作的 runner 則需要容量上限，以及包含 Swift 工具鏈與解析狀態的快取鍵。

不要把 purge-cache 變成每次建置前的固定儀式。它會丟掉可以重複使用的內容、加重對網路的依賴，遇到速率限制或上游服務中斷時也更難受。只有在測量顯示異常增長、診斷出快取完整性有問題，或在長期運作的基礎設施上做有範圍限制的維護作業時，才執行它。

在事故紀錄裡寫清楚指令與範圍。「清過 SwiftPM 快取」語意不清；「在儲存庫 A 執行 swift package clean」和「清除了全域儲存庫快取」的影響範圍與復原成本天差地遠。

用 AskClean 盤點周邊的開發者儲存空間

AskClean 可以盤點 SwiftPM 周邊的主要開發者儲存類別，包括各專案的 Xcode DerivedData、儲存庫建置產物、npm 等已知的套件快取、模擬器儲存空間，以及無法辨識的大型資料夾。它會說明每個項目能不能重建，並在刪除前先詢問你。

至於 SwiftPM 本身，快取範圍仍以官方 Swift 指令為準。AskClean 適合用來找出周邊哪個類別在佔空間，而不該把精確的套件管理操作，變成一次說不清楚的批次刪除。

SwiftPM 指令的作用範圍

依範圍與復原成本選擇，而不是挑最激進的指令。

常見問題