症狀：Jenkins Mac Agent 磁碟空間不足，建置開始失敗或主機持續告警。 最快解法：先定位空間被工作區、Xcode 元件還是建置產物占用，再分別制定清理與保留策略；不要批次刪除目錄。若清理後仍反覆告急，依真實任務紀錄調整工作區管理、節點容量或承載方式。
企業 IT 負責人：判斷 Mac 建置節點的磁碟告警是否已影響 CI 穩定性。 平台工程負責人：管理 Jenkins Mac Agent、工作區與 Xcode 建置環境。 技術總監或研發效能負責人：依任務紀錄決定改善清理流程，或調整 Mac 資源。
先判斷磁碟告警是否真是建置失敗原因
主機空間告警、寫入失敗與 Jenkins 任務失敗是不同現象。磁碟剩餘空間偏低，不代表每個失敗任務都由此造成；同樣地，建置日誌出現寫入錯誤，也需要確認錯誤發生時主機是否真的無法寫入。
在同一時間範圍對照主機可用空間、失敗任務階段與錯誤日誌。若任務停在排隊、連線或工具初始化階段，而磁碟仍可正常寫入，便應先查相應原因，不要把所有故障都歸到容量問題。Jenkins Pipeline 的執行與工作區行為可參考Jenkins 官方 Pipeline 說明；主機端則可用 macOS 的儲存空間檢視方式核對類別與占用。
| 觀察到的現象 | 優先核對 | 不宜立即採取的動作 |
|---|---|---|
| 主機可用空間持續下降 | 工作區、Xcode 元件、歸檔與日誌的占用變化 | 直接清空使用者目錄 |
| 任務在輸出檔案時失敗 | 錯誤日誌、寫入路徑、當時可用空間 | 僅因建置失敗就刪除快取 |
| 任務停在排隊或工具初始化 | Jenkins 執行紀錄、Agent 狀態與工具設定 | 把排隊延遲當成磁碟不足 |
按目錄增長來源排查 Jenkins Mac Agent
先建立可重複的盤點方式：在節點上記錄可用空間，並檢查各建置相關目錄的占用及其變化。df -h / 可協助檢視磁碟檔案系統概況；再按實際路徑盤點，而不是只看總容量。常見檢查位置包括 Jenkins 工作區、~/Library/Developer/Xcode/DerivedData、~/Library/Developer/Xcode/Archives，以及使用模擬器時的 ~/Library/Developer/CoreSimulator。路徑是否存在、內容是否可刪，仍須以目標節點與專案設定為準。
第一張表的結果只能用來縮小範圍；最後要把目錄占用變化對到具體任務和保留要求。尤其是共用節點，並行任務可能各自建立工作目錄，導致同一時段占用上升；不要把一次建置的目錄大小直接當作所有任務的固定需求。
| 來源 | 盤點重點 | 清理前先確認 |
|---|---|---|
| Jenkins 工作區 | 任務結束後是否保留目錄；同一任務是否留下不同工作目錄 | 是否仍需失敗現場供重現、比對或除錯 |
| Xcode 元件與 Simulator runtime | 已安裝的 Xcode、平台支援與模擬器 runtime | 專案、分支及測試流程是否仍依賴該版本 |
| 建置產物與日誌 | 歸檔、符號檔、測試報告、暫存輸出與日誌 | 是否涉及發佈、稽核、事故診斷或追溯 |
分開處理工作區、Xcode 元件與建置產物
工作區清理要按任務結果設計，而不是假設每次建置結束都會自動清除。Jenkins 文件說明，Pipeline 的工作區清理行為取決於 Pipeline 寫法及設定；可先核對Pipeline 語法與執行條件及Workspace Cleanup 步驟文件，再確認實際使用的流程。若清理失敗任務目錄會破壞重現條件，就要先保存必要日誌和測試報告，或保留可供診斷的工作區。
Xcode 本體、平台支援、可選元件與 Simulator runtime 也不能混為一談。先列出專案真正使用的 Xcode 與測試目標，再透過Xcode 元件管理文件辨認可管理項目。Apple 亦提供管理額外模擬器的說明；如要移除不再使用的元件，應依官方管理方式操作，不要把手動刪除受系統保護的目錄當成通用清理法。
建置產物需先分類，再決定保存期限。歸檔與符號檔可能是發佈或事故追查所需資料；測試報告和日誌則可能是稽核或問題診斷依據。可重建的暫存輸出與必須留存的證據，不應套用同一種清理規則。若發佈流程包含 Release 建置測試，也要確認測試輸出與相關紀錄已按團隊要求保存，可對照Apple 的 Release 建置測試說明。
| 項目 | 可採取的處理方式 | 可能的代價 |
|---|---|---|
| 可重建的工作區或暫存輸出 | 按任務狀態設定清理條件，先保存必要診斷資料 | 清理過早會提高失敗重現難度 |
| 不再使用的 Xcode 元件或 runtime | 先核對專案依賴，再用官方管理方式移除 | 遺漏仍在使用的測試目標，可能使建置或測試無法執行 |
| 歸檔、符號檔、報告與日誌 | 依發佈、稽核及診斷需求制定保留與封存方式 | 保存不足會失去追溯證據；保存過久則持續占用空間 |
上線清理策略前完成驗收
清理不是完成工作的標誌；驗收要證明空間回收沒有破壞建置依賴，也沒有把故障證據一併移除。先在可控的任務範圍試行，再按團隊的實際工作流程逐項確認：
- [ ] 記錄清理前的主機可用空間、目標目錄占用與對應任務。
- [ ] 確認清理範圍只涵蓋已識別的工作區、元件或可重建產物。
- [ ] 對失敗及中斷任務，確認診斷所需日誌、測試報告與重現資料有保存方式。
- [ ] 使用正式建置流程核對依賴解析、Xcode 選擇與 Simulator runtime 是否仍符合專案設定。
- [ ] 比較清理前後的任務結果、目錄變化及錯誤日誌，確認清理本身沒有引入新故障。
- [ ] 明確記錄清理規則的適用條件、回退方式及負責維護的人員。
用任務紀錄決定優化清理還是調整節點
不要用沒有來源的容量門檻判斷擴充，也不要只看清理後釋出的空間就推斷長期需求。應從具代表性的任務紀錄整理空間增長來源、清理頻率、必須保留的產物，以及並行任務造成的同時占用；再核對清理規則是否真的生效。這些數值必須來自你的 Jenkins Mac Agent 盤點與建置記錄，而不是套用其他團隊的估算。
| 任務紀錄呈現的情況 | 優先決策 | 需要持續核對的資料 |
|---|---|---|
| 工作區在任務結束後持續殘留 | 先調整工作區生命週期與清理條件 | 清理是否影響失敗診斷及任務重現 |
| Xcode 元件或 runtime 不再被專案使用 | 先核對依賴，再按官方方式移除 | 清理後測試目標與建置是否仍可執行 |
| 發佈或稽核產物必須長期保留，且空間持續增長 | 評估封存與保留流程，必要時調整承載方式 | 產物增長、保留要求與節點實際負載 |
| 清理後仍反覆告急，且無法刪除的占用來自固定任務需求 | 依實際負載評估調整 Mac CI 節點 | 任務分布、併發影響及必要產物的保存要求 |
常見問題 FAQ
Jenkins Mac Agent 應先檢查哪些位置？
先看 Jenkins 工作區，再核對 Xcode 的 DerivedData、Archives 與 CoreSimulator 等常見位置，並以目標節點的實際目錄占用為準。同步對照任務階段與錯誤日誌；只看整台主機的剩餘空間，無法判斷是哪一類資料持續增長，也無法排除與磁碟無關的故障。
Xcode Simulator runtime 可以安全移除嗎？
可以評估移除，但要先確認專案的測試目標、分支及其他任務不再依賴該 runtime。使用 Xcode 提供的元件管理方式辨認和移除項目，之後以實際建置與模擬器測試驗證結果；不要把直接刪除受系統管理的目錄當作一般清理步驟。
清理 Jenkins 工作區會刪掉需要保留的資料嗎？
有可能，實際結果取決於 Jenkins Pipeline 的清理設定及工作區內容。失敗任務的來源檔、暫存輸出或重現條件可能仍有診斷價值；清理前先確認日誌與測試報告已保留，再分別檢視成功、失敗和中斷任務適用的規則，避免用單一條件清除所有工作區。
清理後空間很快再次不足，何時該調整 Mac CI？
先從具代表性的任務紀錄判斷增長是否反覆來自必須保留的歸檔、符號檔或並行任務占用，並確認清理規則確實執行。若固定負載與保存要求已無法透過工作區管理及產物策略滿足，才依任務需求評估增加或調整 Mac CI 節點；不應套用未經核實的容量門檻。
如果告警反覆出現的原因是清理規則已無法處理的固定負載，現有節點就可能同時承受空間競爭、診斷資料保留與建置中斷風險。你可以先比較本地購置、其他承載方式與遠端 Mac：本地設備要自行管理硬體與維護，其他環境則須核對是否符合實際 macOS 工作流程，不能只看表面價格。若需求是階段性擴充或測試另一種承載方式，可向 MACGPU 核對可用配置、租期與交付資訊，再以你自己的任務紀錄決定是否適合租用；若長期固定高負載或需要特定實體介面，則應先評估自有設備是否更符合限制。