遠端 Mac CI 磁碟空間不足怎麼辦？2026 排查指南

症狀：遠端 Mac CI 在建置、測試或歸檔時寫入失敗，或主機持續跳出磁碟空間警告。

本週值班建議：先查明空間被 DerivedData、模擬器、Archives 還是工作區占用，再只清理已確認可重建的資料；不要把刪除整個開發目錄當成通用修復。自託管 Runner 另須安排任務後清理與容量告警。

iOS／macOS 開發者：建置或歸檔失敗，想按目錄類型找出原因時可參考。
CI 工程師：維護持久化 macOS Runner，需要降低任務間殘留時可參考。
小型團隊運維人員：需要判斷該清理資料、調整工作流程，還是增加主機容量時可參考。

遠端 Mac CI 磁碟空間不足：先分辨故障階段

同一個「磁碟空間不足」訊息，不一定代表同一個根因。建置中途寫入失敗、產生 Archive 時失敗、系統儲存空間警告，以及 Runner 無法接手工作，都要分開記錄。單看最後一行錯誤，容易把暫時性任務故障誤判為主機容量不足。

先保留失敗工作流程的階段、工作目錄、錯誤訊息，以及任務開始和結束時的磁碟狀態。若問題只在某個專案或工作目錄發生，優先檢查工作區與該任務產物；若多個工作連續失敗，再檢查主機各目錄的實際用量。

macOS 的儲存空間畫面可協助查看分類，但分類名稱不會直接告訴你是哪個專案或檔案占用空間。Apple 的查看 Mac 儲存空間說明適合作為概覽；要找出具體目錄，仍須在有權限的帳戶下核對檔案系統。

可先在 Runner 上記錄：

df -h /
du -sh "$HOME/Library/Developer/Xcode/DerivedData" 2>/dev/null
du -sh "$HOME/Library/Developer/Xcode/Archives" 2>/dev/null
du -sh "$HOME/actions-runner/_work" 2>/dev/null

這些路徑只是常見檢查位置，不代表每台主機都使用相同目錄。工作目錄可能由 Runner 或工作流程設定，資料夾不存在也不表示磁碟沒有其他占用來源。先檢查命令輸出與執行帳戶權限，再決定下一步。

建置資料與 Archives 的清理界線

macOS CI 的 DerivedData 可以直接刪除嗎？

不要先假設整個資料夾都能清掉。Xcode 的 DerivedData 可包含索引、記錄和建置產物；其實際位置可能依 Xcode 設定而異。Apple 的Xcode 建置位置說明可協助你確認相關位置與用途。若無法確定目前建置是否仍依賴某項資料，先保留並比對專案設定。

可以先列出占用最大的子目錄，找出是否由單一專案或多次建置累積。確認該工作已結束、資料可重新產生，而且不需要留存作診斷後，再選擇性清理。刪除後，索引或建置產物可能需要重新生成；如果清掉的是仍在使用的資料，問題可能由磁碟不足轉為建置或診斷資料遺失。

Archives 是另一類資料，不應和 DerivedData 一起當成快取處理。它可能包含你要保存的建置歸檔；Apple 的常見歸檔問題技術說明提供歸檔排錯資訊。清理前先確認發佈、測試與稽核是否仍需要該 Archive，並核對團隊的留存政策。若須保留，就先轉存或調整保留方案，不要直接刪除。

值班案例：若錯誤只在產生 Archive 時出現，而磁碟用量主要落在歷史歸檔，先確認哪些歸檔仍須留存；若用量集中於某個專案的 DerivedData，則先確認該專案的工作已結束，再評估清理可重建產物。兩種情況的處置不同，不能只因錯誤訊息相同就執行同一條刪除命令。

模擬器資料與專案產物分開檢查

iOS 模擬器運行時占用時怎麼判斷？

把模擬器執行環境、模擬器裝置資料，以及專案建置產物分開看。它們可能位於不同位置，並由不同測試流程使用。先列出目前安裝的執行環境與裝置，再確認工作流程是否還會呼叫它們：

xcrun simctl list runtimes
xcrun simctl list devices

Apple 說明了加入額外模擬器與下載、安裝 Xcode 元件的相關方式。先以目前 Xcode 的管理工具確認項目是否仍被測試目標使用；不要未經確認就手動刪除系統管理的執行環境或仍在使用的裝置資料。

若確定某個測試裝置已無用途，先記錄清理對象與清理前用量，再透過合適的工具逐項移除。避免一次清掉全部模擬器資料，否則後續測試可能需要重新建立裝置或下載元件，反而延長修復時間。Apple 的建置與執行 App 說明也可用來核對建置及執行流程所需的 Xcode 元件。

提醒：如果模擬器項目正在被測試工作使用，或你無法確認它是否由目前的 Xcode 管理，先暫停清理；保留項目清單與錯誤記錄，比手動刪除後再追查缺少的元件安全。

自託管 Runner 的任務間殘留

自託管 macOS Runner 怎麼避免快取持續累積？

先分辨 Runner 類型。GitHub 託管 Runner 的工作環境由服務管理；自託管 Runner 則由你負責主機與環境維護。GitHub 說明了工作應在哪種 Runner 上執行及自託管 Runner 的管理特性。不要把託管環境的任務生命週期直接套用到長期運作的自有主機。

在持久化主機上，工作區、下載快取、建置產物與記錄可能跨任務留下。清理政策應按用途和風險拆開：

工作區：先確認任務已結束、沒有其他工作共用該目錄，再依倉庫與工作流程安排清理。
快取與產物：確認能否由來源重新取得或重建；需要加快後續工作時，可保留受控快取並設定淘汰條件。
憑據與設定：不要把憑據目錄當成一般快取刪除。清理前先確認憑據管理方式與工作流程依賴。
任務記錄：保留足以診斷故障的資訊，同時依團隊政策管理過期記錄。

若 Runner 使用容器，也要釐清容器與主機的儲存邊界；GitHub 的自託管 Runner 容器自訂說明可供核對相關設定。建立任務前後的磁碟紀錄，才能分辨是單次工作產物暴增，還是多次任務持續累積。

清理後的建置復驗清單

清完資料不代表故障已解決。選一個能代表實際工作負載的流程，確認建置、測試或歸檔可以完成，產物也能按原本方式保存。若只測到一個空白建置，卻沒有覆蓋原本失敗的流程，不能據此判定已修復。

[ ] 記錄清理前的可用空間、最大占用目錄與失敗階段。
[ ] 確認清理對象可重建，且不屬於必須留存的 Archive、憑據或仍在使用的模擬器資料。
[ ] 執行原本失敗的建置、測試或歸檔工作，核對錯誤是否消失。
[ ] 檢查產物是否成功寫入預期位置，後續任務能否正常啟動。
[ ] 記錄清理後的可用空間與主要目錄用量，安排任務後檢查及容量告警。
[ ] 若問題很快重現，重新比對任務前後紀錄，再決定調整快取、工作流程或主機容量。

如果問題只由一次性的大型工作造成，針對該任務調整產物留存或清理時機通常比全面刪除安全。若多個工作在相同主機反覆耗盡空間，就應按實際負載重新評估容量與清理政策，而不是定期盲目清空開發資料。

若清理涉及保存建置產物或憑據，也要先核對團隊的資料保護要求；MangoVM 的資料保護說明可供你查看相關資訊，並據此設定適當的留存與存取界線。

如果你只需短期測試或臨時增加 macOS 建置環境，遠端 Mac 租用可免去自購硬體與自行維護主機，但仍要先確認磁碟配置、存取方式及資料留存要求。相較之下，沿用 Windows／Linux 主機無法直接提供完整的 macOS 專屬工具鏈；長期自託管則要自行承擔空間治理與 Runner 維護；本地 Mac 若已滿載，也不會因任務移到另一個工作目錄就自動解決容量問題。若持續重負載且需要固定硬體，先比較自購與租用的長期成本；若只是階段性建置需求，可查看 MangoVM 遠端 Mac 方案，並依工作負載確認合適的主機容量。