磁碟告警後刪掉一個 Jenkins Workspace，Mac Agent 仍然被置為離線，甚至新的建置也無法啟動。
最快解法：不要直接清空整個工作目錄；先分開盤點 Jenkins Workspace、Xcode DerivedData、模擬器 Runtime、歸檔與依賴快取，再按照可重建性和發布價值清理。若清理後仍反覆接近禁止接單門檻，就降低並發、拆分簽名節點，並增加固定或按需的遠端 Mac 容量。
適用對象與故障邊界
這篇文章適合負責 Jenkins Mac Agent 日常維運、磁碟告警和節點恢復的企業 IT 人員。
如果你管理 iOS 建置效率、快取策略或流水線穩定性，也可以用這套方法定位增長來源。
需要根據磁碟增長、排隊和維護窗口決定 Mac 節點擴容方式的技術負責人，應特別閱讀最後的容量判斷。
一個常見失敗鏈路是：監控發出磁碟不足告警，值班人員刪除當前專案的 Workspace，Finder 顯示的可用空間卻沒有明顯恢復；接著 Jenkins 把節點標記為不可用，正在等待簽名的工作被迫排隊。這不代表清理沒有作用，也不代表 Jenkins 本身一定是唯一來源。
APFS 的可用空間、檔案系統顯示的邏輯大小，以及實際可回收空間可能不同。正在使用的檔案、快照、暫存資料和開啟中的程序，都可能讓「看見的資料大小」與「刪除後可用空間」不一致。因此，不應只依 Finder 的分類決定刪除範圍。
Jenkins 官方節點管理文件確認，節點可以監控 Remote FS 與暫存目錄的磁碟空間；這些監控結果應與 Mac 本機的目錄盤點互相核對，而不是只看 Jenkins 主控台上的單一百分比。Jenkins 節點管理文件
先做分層盤點
先保留路徑、檔案大小、最後修改時間與目前使用程序的紀錄。盤點時不要只執行一次總容量指令，應把 Jenkins Remote FS、使用者 Library、暫存目錄和歸檔位置分開統計。若企業已經有每日磁碟記錄，再把當前結果與歷史增長曲線比對。
| 資料層 | 常見內容 | 可重建性與主要風險 | 初步處置 |
|---|---|---|---|
| Jenkins Workspace | Git 檢出內容、建置中間檔、並發工作區 | 目前建置可能仍在使用；刪除會中斷流水線 | 先確認任務狀態和實際路徑 |
| Xcode 產物 | DerivedData、索引、編譯中間檔 | 通常可重建，但會增加下一次建置負擔 | 在節點摘除後受控清理 |
| 模擬器資料 | 裝置資料、測試產物、Runtime | Runtime 可能需要重新下載；環境受限時恢復成本更高 | 分開判斷資料與 Runtime |
| 發布資料 | Archives、dSYM、版本關聯檔案 | 可能是發布證據或故障分析依據 | 由發布負責人確認保留週期 |
| 依賴快取 | Swift Package Manager、CocoaPods、Homebrew、Git LFS | 可重建性和共用範圍各不相同 | 先確認是否已有外部副本 |
| 憑證與鑰匙 | Keychain、簽名憑證、設定檔 | 誤刪可能直接造成簽名失敗 | 不納入通用清理腳本 |
目錄盤點的重點不是找出「最大的一個資料夾」，而是找出誰在持續增長、誰最後被任務使用，以及誰刪除後需要重新下載。你也要檢查 Jenkins Controller、Mac Agent 和制品儲存之間是否保存同一份檔案；只清理 Agent，可能只是把容量問題轉移到另一個位置。
Workspace 與並發目錄
遺留工作區與多分支路徑
Jenkins Pipeline 會依工作流程分配 Workspace；多分支任務、定制 Workspace 或並發執行，可能產生帶有後綴的目錄。任務名稱從 Jenkins 中移除後，對應的資料夾不一定會自動回收。這也是「刪掉目前專案，空間仍沒有恢復」的常見原因之一。
先核對三件事：
- Job 的實際 Workspace 路徑，不要假設所有任務都在預設位置。
- 多分支與並發任務是否仍有執行中或等待中的工作。
- Workspace 清理日誌是否顯示成功、跳過、被鎖定或權限不足。
Pipeline 語法文件提供 Workspace 生命週期相關行為的說明，應以實際 Pipeline 定義核對，而不是把所有工作區都視為可以隨時刪除。Jenkins Pipeline 語法文件
自動刪除的適用範圍
「構建結束後自動刪除」可以成立，但前提是該 Workspace 屬於可重建的普通建置，而且清理時機不會與後續步驟衝突。對於需要保留測試報告、簽名產物或除錯資料的流水線，應先將必要檔案交給制品儲存，再清除本地工作區。
可使用 Workspace Cleanup Plugin 提供的 cleanWs 步驟，並在 Pipeline 中明確指定成功、失敗或建置結束時的清理行為。Workspace Cleanup Plugin 官方頁面
不要用沒有任務狀態檢查的批次刪除指令掃過整個 Workspace 根目錄。這種作法可能刪掉正在 checkout、測試、產生 Archive 或等待簽名的活動目錄。若必須人工處理，應先暫停新任務或把節點摘除，記錄待刪路徑、程序和回復方式，再於維護窗口執行。
Xcode 資料與快取分級
DerivedData、模擬器與平台組件
Xcode 相關資料不能全部套用同一個「快取」標籤。
DerivedData 通常可以重新產生，但清除後下一次建置需要重新編譯索引與中間檔。這會影響單次建置時間，但實際影響取決於專案規模、依賴下載狀態和並發狀況，不能直接套用其他團隊的耗時結論。
模擬器裝置資料與 Simulator Runtime 也要分開。測試留下的裝置資料可能可重建；Runtime 或平台組件則可能需要重新下載或從企業內部來源導入。Apple 的 Xcode 組件文件說明了額外組件的下載與安裝管理方式，清理前應確認目標 Xcode 環境有可用的恢復來源。Apple Xcode 組件管理文件
Archives、dSYM 與簽名資料
Archives 不只是編譯暫存檔。它可能與已發布版本、符號化崩潰報告或內部稽核紀錄相關。dSYM 也可能是故障追蹤所需的除錯資料，Apple 對除錯資訊與 dSYM 的用途有明確說明。Apple 除錯資訊與 dSYM 文件
因此，清理規則應先詢問發布與故障分析責任人：
- 哪些 Archive 已經完成外部或內部發布？
- dSYM 是否已上傳至指定的故障分析系統？
- 是否仍需要重現某個版本的簽名、崩潰或合規證據？
- 本機副本是否已由可驗證的制品儲存取代？
如果答案不完整，先不要刪除。簽名憑證、Keychain 和私密設定檔更不能放入共用清理腳本。它們的風險不是「重新下載一次」可以解決的。
依賴快取的責任矩陣
Swift Package Manager、CocoaPods、Homebrew、Git LFS 和專案自訂快取，可能同時出現在 Workspace、使用者目錄與外部制品儲存。你可以用以下四個欄位建立資產表，為每類資料指定責任人：
| 資料資產 | 資料所有者 | 可否重建 | 清理觸發條件 |
|---|---|---|---|
| 依賴下載快取 | 平台或建置團隊 | 依網路與版本來源確認 | 增長超過容量計畫，且已有可用來源 |
| 編譯中間檔 | 專案建置團隊 | 通常可重建 | 維護窗口或節點摘除後 |
| 發布 Archive 與 dSYM | 發布與支援團隊 | 不應直接假設可重建 | 完成保存、驗證與保留週期確認 |
| Git LFS 或大型測試資料 | 專案資料所有者 | 依版本來源確認 | 外部副本可讀取且不影響回滾 |
| Keychain 與簽名設定 | 安全與發布團隊 | 不以一般快取處理 | 不由自動清理觸碰 |
這張表的價值在於把「能不能刪」改成「誰負責、刪後如何恢復」。不要把所有快取永久保存，也不要每次建置完成就刪除所有資料。
清理判斷與安全分支
Jenkins Mac Agent 磁碟清理應採用以下條件，而不是依照資料夾名稱猜測：
- 若目錄屬於已結束、可重新 checkout 的普通建置，且沒有待上傳產物，則可在節點摘除後使用受控 Workspace 清理。
- 若目錄仍被建置、測試、打包或簽名程序開啟，則保留目錄，先停止接收新任務並處理活動程序。
- 若DerivedData 是主要增長來源，且目標 Runtime、依賴和 Xcode 組件都能恢復，則優先清理 DerivedData，而不是先碰 Archive。
- 若模擬器 Runtime 需要受限網路重新下載，則先驗證安裝來源；不能因為它看起來像快取就直接刪除。
- 若Archives、dSYM 或發布版本仍未完成保存驗證，則交由發布責任人決定，不能套用普通 Workspace 規則。
- 若清理後每日增長仍超過企業容量模型，或維護窗口已影響發布，則降低單機並發、拆分普通建置與生產簽名節點，並評估新增固定或按需遠端 Mac。
這些分支也回答了「Mac 建置機反覆磁碟滿究竟是清理策略還是容量不足」：如果主要是遺留工作區或失控快取，先修正生命週期；如果資料已按保留策略管理，仍因並發峰值和平台組件需求頻繁觸發告警，問題就是容量或節點分工。
清理後的流水線驗收
不要以「釋放了多少空間」作為唯一成功條件。清理後至少按以下順序驗收：
- 摘除節點：在 Jenkins 中暫停新任務或將 Mac Agent 設為暫不接收工作，記錄當時的磁碟狀態和活動 Job。
- 保存證據：匯出待刪路徑、目錄占用、最後訪問時間、活動程序與清理前的監控截圖或紀錄。
- 受控清理：只處理已確認可重建、沒有被程序使用的 Workspace、DerivedData 或測試暫存資料。
- 恢復依賴：重新檢查 Git checkout、Swift Package Manager、CocoaPods、Git LFS 和必要的 Xcode 組件來源。
- 普通建置：先跑不涉及生產簽名的源碼檢出、依賴恢復、編譯和測試流水線。
- 簽名驗收：再執行實際簽名、封裝和發布流程，確認 Keychain、憑證、Provisioning 設定及 Archive 產物完整。
- 節點恢復：確認節點重啟後仍能連線，Jenkins 磁碟監控恢復正常，再逐步放回並發工作。
- 記錄後果：記下清理前後的容量、建置排隊、失敗原因、快取重建結果與恢復時間，納入下一次容量評審。
Apple 的發布文件可用來核對測試版與正式發布所需的產物流程；不要把「普通建置成功」誤當成簽名發布已經安全。Apple 發布與分發文件
閾值與容量決策
閾值不應直接抄用其他團隊的固定數值。你需要從單次建置峰值、Xcode 組件安裝需求、依賴恢復來源，以及企業要求的故障恢復餘量推導。至少建立三層狀態：
- 預警：允許建置，但建立工單，觀察目錄增長和最近清理結果。
- 禁止接單：停止新工作，保留正在進行且可安全完成的任務，安排節點盤點。
- 人工介入：檢查活動程序、簽名工作、Runtime 來源和制品副本，必要時執行維護或轉移任務。
每次容量評審應帶上每日增長、清理頻率、快取重建時間、建置排隊、節點離線紀錄與並發數。如果只有磁碟使用量，沒有這些背景資料，你很難分辨是資料生命週期失控、並發過高，還是硬碟本身不足。
Jenkins 的多分支任務可搭配建置丟棄策略，限制不再需要的建置記錄與相關保存範圍；但它不能代替 Workspace、Archive、dSYM 和依賴快取的獨立治理。Jenkins 多分支建置丟棄文件
若清理頻率持續上升，或每次維護都讓發布排隊，建議把普通建置與生產簽名拆到不同節點。簽名節點需要較嚴格的權限、資料保留和變更審核；普通建置節點則可採用更積極的 Workspace 和 DerivedData 生命週期。
現有方案與遠端 Mac 的取捨
如果你繼續把所有 Jenkins 工作集中在一台實體 Mac 上，常見缺點是：並發建置互相爭用磁碟、簽名環境與普通快取混在一起、維護時整條流水線同時停擺。單純增加清理腳本，也可能讓下一次建置花更多時間恢復依賴，卻沒有解決容量峰值。
自購 Mac 的優點是硬體和實體介面掌握在企業手中，適合長期穩定重負載、需要特定外接設備或內部網路隔離的場景；缺點是採購、交付、維修、折舊和閒置容量都由你承擔。對短期專案、節點試點或需要按需增加建置容量的團隊，MACCOME 的遠端 Mac 可先作為獨立 Jenkins Agent，讓你用真實建置資料驗證並發、快取和清理策略。你可以先了解遠端 Mac 建置節點方案，再按你的網路、權限和簽名要求決定是否導入。
若你需要的是臨時建置容量，而不是全年固定持有硬體，遠端 Mac 的優勢在於可以把新增節點和現有節點分開驗收，避免立即改動生產簽名環境。你也可以先從MACCOME 的遠端 Mac 資源選項了解可用的交付方向，再依建置資料決定節點數量。不過，涉及實體 USB、特殊內網路由、長期滿載或嚴格資料不得離開企業場所的情況，仍應優先評估自購 Mac 或內部託管。
完成一次真實清理與驗收後，請把目錄增長、建置峰值、排隊時間和節點恢復結果填入容量表。若現有 Mac 仍反覆觸發禁止接單狀態，再考慮以 MACCOME 的遠端 Mac 試點增加建置節點；先用可驗證的流水線結果決定容量，而不是等下一次磁碟滿了才被動處理。