如何安全清理 Xcode Derived Data

Xcode Derived Data 可以安全删除。默认目录里保存的是 Xcode 能够重新生成的构建产物和索引，删除后不会丢失项目源代码，代价只是下一次构建和代码索引需要更长时间。

真正需要注意的是清理范围：先退出 Xcode，并确认删除的是 ~/Library/Developer/Xcode/DerivedData，不要误删 Archives、模拟器设备数据或项目目录。

本文路径与检查命令于 2026 年 8 月 10 日在 macOS 15.7.7、Xcode 16.2 环境验证。Xcode 菜单可能随版本调整，但只要没有自定义构建位置，默认 Derived Data 路径和下文的终端方法仍然适用。

Xcode Derived Data 是什么？

Xcode 会把构建项目和理解代码时生成的文件放入 Derived Data，常见内容包括：

Apple 的文档说明工作区索引位于独立的 Derived Data 目录中，Xcode 发布说明也会在部分构建故障的恢复步骤中建议清理对应项目的 Derived Data。换句话说，这个目录应当可以重新生成，不应该作为源代码的唯一保存位置。

以下情况适合考虑清理：

不要因为 Derived Data 存在就定期清空。正在开发的项目可以利用增量构建数据缩短编译时间；一个体积很小且工作正常的目录没有清理价值。

位置	建议	删除后的影响
`~/Library/Developer/Xcode/DerivedData/项目名-*`	可清理确认过的单个项目	该项目需要重新构建和索引
`~/Library/Developer/Xcode/DerivedData` 内的全部内容	需要彻底重置时可以清理	所有 Xcode 项目都需要重新构建和索引
`~/Library/Developer/Xcode/Archives`	不要当作缓存清理	可能丢失用于分发或崩溃分析的归档与匹配调试符号
`~/Library/Developer/CoreSimulator/Devices`	必须单独检查	可能丢失模拟器应用、设置和测试数据
Git 仓库或项目目录	不要删除	这里保存的才是源代码和项目配置

清理前还应打开 Xcode 的 Settings → Locations。如果 Derived Data 被设置成 Custom，请以这里显示的路径为准，不要直接套用默认目录。

如果希望先看清每个项目目录再删除，Finder 是最直观的方式。

先移到废纸篓可以保留一个短暂的恢复机会。确认项目能够正常打开和重新构建后，再清空废纸篓。

先确认目录和总占用：

du -sh "$HOME/Library/Developer/Xcode/DerivedData"
du -sh "$HOME/Library/Developer/Xcode/DerivedData"/* 2>/dev/null | sort -h

每个项目目录通常以可识别的项目名开头，后面跟着一段唯一标识。可以先在 Finder 中打开检查：

open "$HOME/Library/Developer/Xcode/DerivedData"

如需永久删除单个项目，请把示例目录名替换成自己输出中的完整名称：

rm -rf "$HOME/Library/Developer/Xcode/DerivedData/YourProject-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

如需永久删除默认 Derived Data 目录内的所有项目：

find "$HOME/Library/Developer/Xcode/DerivedData" \
  -mindepth 1 -maxdepth 1 -exec rm -rf {} +

这些命令不会经过废纸篓。按下回车前必须重新阅读完整路径；Xcode 正在构建、测试或索引时，不要执行最后一条命令。

如果只是单个项目构建异常，并不需要同时删除索引和其他工作区数据，可以先在 Xcode 中执行 Product → Clean Build Folder。Apple 也在故障排查文档中使用过这个操作。

工作区对应的命令行写法类似：

xcodebuild \
  -workspace YourApp.xcworkspace \
  -scheme YourApp \
  clean

它的范围比删除整个 Derived Data 目录更小：只是让当前构建系统清理指定项目的构建产物，不是对所有 Xcode 工作区进行磁盘清理。

第一次构建通常会明显变慢。Xcode 需要重新编译 Target、创建代码索引，还可能重新解析或下载 Package 数据。在索引完成前，代码补全和跳转也可能暂时不完整。

项目文件、Git 历史、签名证书、Provisioning Profile 和 Xcode Archives 都不在默认 Derived Data 根目录中。只删除本文给出的准确路径时，它们不会受到影响。

如果完整重建后原来的错误再次出现，Derived Data 很可能不是根因。此时应检查第一条有意义的编译错误、依赖解析、当前使用的 Xcode 版本和项目 Build Settings，不要继续反复清缓存。