症状： Jenkins Mac Agent 出现磁盘告警或构建写入失败，但告警本身不能证明磁盘就是根因。 最快处理： Jenkins 官方说明，工作区是否自动清理取决于配置；先定位占用来源，再按对象清理，反复告急时再评估节点承载。(Jenkins Pipeline 文档)
企业 IT 负责人：你需要判断磁盘告警是否正在影响 CI 稳定性。 平台工程负责人：你维护 Jenkins Mac Agent、工作区和 Xcode 构建环境。 技术总监或研发效能负责人：你要依据任务记录，决定优化清理流程还是调整 Mac 资源。
先把磁盘告警与构建失败分开
磁盘使用率告警、文件写入失败和 Jenkins 构建失败不是同一件事。空间告警可能尚未造成任务失败；构建失败也可能发生在队列等待、网络访问、依赖解析或工具链阶段。先将主机磁盘信息、失败任务阶段和错误日志放到同一时间窗口核对，不要看到失败就直接删目录。
Jenkins Mac Agent 磁盘空间不足时，先检查哪些位置？ 先盘点构建工作区、Xcode 组件与模拟器运行时、归档及日志等构建产物；同时记录占用最大的目录和对应任务。下面的命令用于查看剩余空间及已确认路径的目录大小，路径要替换成你环境中的实际值：
df -h /
du -sh "/实际的 Jenkins 工作区路径"
du -sh "$HOME/Library/Developer/Xcode"将输出与构建日志中的失败阶段、错误信息和任务状态交叉核对。如果日志显示写入失败并且同一时段空间明显减少，磁盘问题的关联性更强；若失败出现在拉取依赖或等待执行阶段，先排查对应环节，不要把清理当成通用修复。macOS 的存储设置也能查看卷和类别的已用、可用空间；不过“系统数据”等类别并不等于一个可以直接整目录删除的目标。可参考 Apple 的 Mac 存储设置说明。
| 观察到的信号 | 优先核对 | 处置方向 | 误判风险 |
|---|---|---|---|
| 工作区随任务反复增长 | 工作区路径、并发任务目录、清理条件 | 核对成功、失败和中断任务的清理策略 | 直接清掉失败目录，可能丢失复现线索 |
| Xcode 相关目录占用突出 | 已安装组件、平台支持、Simulator runtime | 按项目与任务实际依赖核对可移除项 | 删除仍被测试任务选用的运行时 |
| 归档、日志或报告持续累积 | 文件用途、保留要求、归档位置 | 为可重建数据与需留存证据分别设策略 | 删除发布、审计或诊断仍需要的材料 |
| 空间看似充足但构建仍失败 | 失败阶段、错误日志、队列与依赖状态 | 先排除非磁盘故障 | 把无关故障归因于容量 |
再核对工作区是否真的按预期回收
Jenkins 的工作区用于任务处理检出的文件；具体目录与清理行为受 Pipeline 和节点配置影响。Jenkins 文档特别提示，有些工作区可能不会在一段时间无活动后自动清理。因此，不能只看“任务已结束”就假定目录已经回收。(Jenkins Pipeline 文档)
清理工作区会不会删掉需要保留的文件？ 会，取决于清理范围和条件。Jenkins 的 cleanWs 支持按任务状态执行，也支持配置包含或排除模式；清理整个匹配目录时，目录内容都可能被删除。先确认归档、测试报告、崩溃日志和复现所需文件是否已保存到工作区之外，再启用自动清理。(Jenkins Workspace Cleanup 步骤文档)
清理策略不要只覆盖成功任务。失败与中断任务往往更需要诊断证据，可先保留必要日志和报告，再清理确定可重建的源码副本或临时输出。若团队需要在任务结束后执行清理，Pipeline 的 post 阶段可按状态设置动作；先在非生产任务上验证配置，再逐步推广。(Jenkins Pipeline 语法文档)
⚠️ 工作区清理不是故障证据管理方案。先定义哪些文件必须保留、保存在哪里、由谁确认已归档，再决定清理范围和触发条件。
盘点 Xcode 组件与 Simulator runtime
Xcode 组件并非只有一个应用本体。Apple 将平台支持、可选组件和不同系统版本的 Simulator runtime 分开管理；Xcode 的组件设置会显示已安装或启用的组件及移除后可回收的存储空间。优先用这套管理界面盘点，不把手动删除受系统保护或用途不明的目录当作通用操作。(Apple Xcode 组件管理文档)
移除 Xcode Simulator runtime 前要核实什么？ 先确认没有项目、测试矩阵或并行任务依赖对应系统版本，再考虑移除。Apple 提供在 Xcode 设置的组件区域选择运行时并删除的方式；删除前应对照 Jenkinsfile、测试配置和团队支持的模拟器版本，删除后再验证任务实际选择的运行时。(Apple Simulator 管理文档)
建议先列出团队实际使用的 Xcode 版本、目标平台和模拟器系统版本，再由组件管理界面确认待移除项。若构建任务依赖特定运行时，不要为了腾空间先删再试；应安排维护窗口，或先在独立验证节点上确认替代组件可用。
为归档、日志和构建输出设保留边界
磁盘占用不一定来自工作区。归档、符号文件、测试报告、日志和临时输出各自承担不同用途：有些能够由任务重建，有些则可能用于发布、审计或定位失败。Apple 的文档说明，Xcode 会将应用归档保存在磁盘上，供后续分发等流程使用；因此归档不能一概按“缓存”处理。(Apple 发布构建测试文档)
| 数据对象 | 清理前要核对 | 推荐处置 | 相对误删风险评分* |
|---|---|---|---|
| 可重建的临时输出 | 是否能由同一任务重新生成 | 先确认重建条件，再纳入自动清理 | 低 |
| 失败任务日志与测试报告 | 是否仍在诊断或复现窗口内 | 先保存证据，再按团队规则回收 | 中 |
| 发布归档与符号文件 | 是否承担分发、符号化、审计或回滚用途 | 明确保留责任与归档位置后再清理 | 高 |
| 未核实用途的目录 | 所属任务、工具和所有者是否明确 | 暂停删除，先确认归属 | 高 |
用小范围验收避免清理后反复返工
在将清理策略推广到全部任务前，先对一个代表性流水线做受控验证。重点不是追求一次性腾出尽可能多的空间，而是确认清理对象明确、任务依赖仍满足、失败时仍保留足够证据。
- [ ] 保存清理前的磁盘信息、主要目录占用和对应任务记录。
- [ ] 确认工作区中哪些文件可重建，哪些日志、报告或归档必须保留。
- [ ] 用 Xcode 组件管理界面对照项目需求，确认拟移除组件或 Simulator runtime 未被任务依赖。
- [ ] 先在单条非关键流水线执行清理，检查成功、失败和中断场景下的清理行为。
- [ ] 清理后重新运行依赖解析、模拟器选择和真实构建，核对日志是否出现新的缺失组件或文件错误。
- [ ] 确认失败任务仍有诊断证据，并记录可回退的清理配置或恢复步骤。
- [ ] 观察同类任务后续记录；若空间仍持续告急，重新核对增长来源和并发影响，不重复扩大删除范围。
根据重复告警记录决定是否调整节点
哪些迹象说明 Mac CI 节点需要重新评估？ 当有代表性的任务记录显示占用持续增长，且清理策略已明确、构建必需组件和需保留产物无法再安全削减时，再评估节点容量或承载方式。不要凭单次告警设定扩容阈值，也不要假设增加节点一定能解决共享工作区、产物保留或并发配置问题。
你可以按这组条件判断：
- 若主要增长来自可重建工作区：先修正成功、失败和中断任务的清理策略。
- 若主要增长来自仍在使用的 Xcode 组件或模拟器：核对版本需求，收敛不再支持的构建组合。
- 若增长来自发布归档、符号文件或审计证据：先确定保留责任与归档位置，再评估节点本地留存是否必要。
- 若上述策略已落实，仍因固定任务负载和并发构建持续告急：基于真实任务记录评估调整节点容量、增加 Mac CI 承载或改变任务分配方式。