远程 Mac CI 磁盘空间不足怎么办？2026 排查指南

GitHub 托管 Runner 的每个 job 都运行在全新实例中，而自托管 Runner 不保证每次任务都有干净环境；因此，本周先检查实际占用目录，再按可重建性清理并复验，别把删除整个开发目录当成通用修复。(docs.github.com)

iOS／macOS 开发者：构建或归档失败，怀疑远程 Mac 磁盘不足时，按目录类型定位。
CI 工程师：维护持久化 macOS Runner，需要控制任务间残留时，参考清理与记录步骤。
小型团队运维人员：判断该清理数据、改工作流还是调整主机容量时，用文末验收清单做决定。

远程 Mac CI 磁盘空间不足：先按故障表现分流

“空间不足”可能表现为编译写入失败、归档失败，也可能是主机存储告警。单条错误信息不能证明根因相同。先记下失败发生的阶段、Runner 工作目录、完整日志，以及问题是否只出现一次，还是随着连续构建逐渐恶化。

先看文件系统可用空间，再查具体目录；不要只依据系统存储分类判断。macOS 的“系统数据”是归类项目，可能包括缓存、日志、虚拟内存文件和其他运行时资源，并不能直接说明哪个目录适合删除。(Apple 关于查看 Mac 存储空间的说明)

登录远程 Mac 后，先保存一份基线：

df -h /
du -xhd 1 "$HOME/Library/Developer" 2>/dev/null
du -xhd 1 "$HOME/Library/Developer/Xcode" 2>/dev/null

df 用来查看文件系统可用空间，du 用来比较指定目录的占用。若命令因目录权限而跳过内容，先记录这一点，再按实际目录权限检查；不要为了得到完整输出就直接给整条命令加 sudo。

第一步：辨认 Xcode 构建数据与归档

Xcode 的 DerivedData 可包含构建生成文件、索引等数据；默认构建位置曾记录在 ~/Library/Developer/Xcode/DerivedData/，但项目也可能使用自定义位置。先按项目或 workspace 核实路径，再看占用大小和最近任务记录。(Xcode 发布说明中关于构建位置的说明)

macOS CI 的 DerivedData 可以直接删吗？如果确认是可重建的项目构建数据，并且相关构建已停止，可以把该项目对应的数据作为清理候选。代价是后续构建可能需要重新生成文件、重新索引或恢复依赖；如果多个项目共用目录，整目录删除可能影响其他任务。先保留仍需用于诊断的日志与结果，再选择目标项目处理。

Archives 是单独管理的归档产物，不应与 DerivedData 混为一类。Xcode 的 Archive 操作会生成可在 Archives Organizer 中查看的归档；清理前检查留存要求、交付记录和复现需求。已发布版本、待审核构建或团队要求保留的归档，不应因为磁盘告警就删除。(Apple 关于解决常见归档问题的技术说明)

现场常见情况是：构建后空间骤减，清掉某个项目的可重建数据后可用空间回升，但下一次归档仍失败。此时要重新检查归档目标位置与失败日志；只清 DerivedData 并不能证明归档目录也有空间。

第二步：分别检查 iOS 模拟器运行时与设备数据

模拟器运行时是供模拟器启动的操作系统包，同一运行时可被不同设备类型的模拟器使用；模拟器设备自身的数据则是另一类对象。把两者和项目构建产物分开检查，避免误删仍被当前 Xcode 或测试任务使用的内容。(Apple 关于添加模拟器的说明)

先在 Xcode 的 Components 设置中查看已安装组件及可回收空间；确认某个 iOS 模拟器运行时不再用于测试后，再用 Xcode 提供的删除选项移除。设备数据则到 Device Hub 核对具体模拟器；删除前确认没有测试正在运行，也没有待保留的测试状态。不要通过手工删除系统管理目录来代替 Xcode 的组件管理。(Apple 关于下载和安装 Xcode 组件的说明)

清理模拟器数据后，不要只看可用空间数字。运行项目实际使用的 destination，确认构建、测试和结果保存都完成；若工作流需要该运行时，检查 Xcode 是否已重新识别对应平台支持。Apple 也提醒，模拟器不能完全复现实体设备的性能与功能，因此空间排障通过并不等于设备兼容性验收完成。(Apple 关于构建和运行 App 的说明)

第三步：自托管 Runner 反复失败时查任务残留

如果失败总在同一台持久化主机上、且多次任务后可用空间持续减少，检查 Runner 工作区、构建缓存、日志、测试结果和归档分别占多少。自托管 Runner 由你部署和管理，默认不要求每个 job 都获得干净实例；这意味着清理策略、主机软件维护和容量监控都属于运维责任。(GitHub 关于自托管 Runner 的说明)

不要把“删除工作区”“清缓存”和“清凭据目录”写成一个清理动作。先区分目录用途与所属仓库，再判断是否能安全重建；凭据和 Runner 配置应按安全流程管理，不能当作普通构建垃圾清理。若使用自托管的容器自定义流程，可把任务创建的临时容器、网络等资源安排在 job 结束时清理，并单独记录清理结果。(GitHub 关于自定义 Runner 容器的说明)

相比之下，GitHub 托管 Runner 的 job 使用全新实例；如果故障只在自托管机器反复出现，优先查主机上的持久化数据，而不是先改 Xcode 项目。(GitHub 关于为 job 选择 Runner 的说明)

清理前后按同一工作负载复验

清理后至少要用一次具有代表性的构建、测试或归档任务验证结果。分别检查任务是否能写入中间文件、目标产物是否按预期保存、后续任务能否继续运行，并对照清理前后的 df -h 输出。一次任务成功只能说明这次复验通过，不能证明容量长期够用。

• [ ] 记录报错阶段、完整日志、工作目录和主机可用空间。
• [ ] 找出实际占用较大的目录，核对路径和目录用途。
• [ ] 确认候选数据可重建、没有正在使用，并保留需要的归档与诊断材料。
• [ ] 通过 Xcode 的组件或模拟器管理功能处理对应对象，不手工删系统管理文件。
• [ ] 运行代表性构建、测试或归档，检查任务状态与产物保存。
• [ ] 比较清理前后的空间变化；若很快再次下降，追查任务间残留并设定告警。

设告警时，先依据自身任务运行记录确定阈值，不要照搬未经验证的固定数字。若空间主要被一次性产物占用，调整保留和清理策略；若持续构建的常态占用已逼近主机可用容量，则评估更换容量配置或拆分工作负载。Apple 的存储分类只能协助查看概况，具体清理对象仍需回到文件和目录核验。

当你从本地 Mac 迁移到 CI，常见限制是本机空闲时间受个人使用影响、Linux 主机无法代替 macOS 专属工具链、持久化 Runner 需要自行治理缓存和归档。若只是临时补充远程 macOS 构建环境，租用 MangoVM 的 Mac 可以避免为短期任务先购置专用硬件；但需要实体设备接口，或长期稳定的高负载且已有合适主机时，自购和自管也可能更合适。你可以先按清单完成复验，再查看 MangoVM 的 Mac mini 方案；访问与使用问题可参考 MangoVM 帮助说明，涉及数据处理时查看 MangoVM 数据保护说明。