# 如何安全清理 Xcode Derived Data > 了解 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，常见内容包括： - 编译结果和中间构建文件 - 用于代码跳转、搜索和补全的索引 - 构建日志及其他项目级辅助数据 - 当前工作区使用的 Swift Package 本地检出和相关构建数据 Apple 的文档说明工作区索引位于独立的 Derived Data 目录中，Xcode 发布说明也会在部分构建故障的恢复步骤中建议清理对应项目的 Derived Data。换句话说，这个目录应当可以重新生成，不应该作为源代码的唯一保存位置。 以下情况适合考虑清理： - 已经不用的旧项目留下了数 GB 构建数据 - Xcode 反复使用过期构建结果 - 代码补全或索引状态异常 - Xcode 升级后，Package 或 Macro 构建失败 - 当前更需要磁盘空间，可以接受首次重建变慢 不要因为 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 清理 Derived Data 如果希望先看清每个项目目录再删除，Finder 是最直观的方式。 1. 保存工作，停止正在运行的构建和测试。 2. 打开 **Xcode → Settings → Locations**。 3. 找到 **Derived Data**，点击路径旁的箭头，在 Finder 中打开目录。 4. 退出 Xcode。 5. 只把存在问题或已经不用的项目目录移到废纸篓；需要完全重置时，再移动 Derived Data 目录内的全部内容。 6. 重新打开 Xcode 并构建项目。 先移到废纸篓可以保留一个短暂的恢复机会。确认项目能够正常打开和重新构建后，再清空废纸篓。 ## 方法二：通过终端检查和清理 先确认目录和总占用： ```bash du -sh "$HOME/Library/Developer/Xcode/DerivedData" du -sh "$HOME/Library/Developer/Xcode/DerivedData"/* 2>/dev/null | sort -h ``` 每个项目目录通常以可识别的项目名开头，后面跟着一段唯一标识。可以先在 Finder 中打开检查： ```bash open "$HOME/Library/Developer/Xcode/DerivedData" ``` 如需永久删除单个项目，请把示例目录名替换成自己输出中的完整名称： ```bash rm -rf "$HOME/Library/Developer/Xcode/DerivedData/YourProject-xxxxxxxxxxxxxxxxxxxxxxxxxxxx" ``` 如需永久删除默认 Derived Data 目录内的所有项目： ```bash find "$HOME/Library/Developer/Xcode/DerivedData" \ -mindepth 1 -maxdepth 1 -exec rm -rf {} + ``` 这些命令不会经过废纸篓。按下回车前必须重新阅读完整路径；Xcode 正在构建、测试或索引时，不要执行最后一条命令。 ## 方法三：先尝试 Clean Build Folder 如果只是单个项目构建异常，并不需要同时删除索引和其他工作区数据，可以先在 Xcode 中执行 **Product → Clean Build Folder**。Apple 也在故障排查文档中使用过这个操作。 工作区对应的命令行写法类似： ```bash 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，不要继续反复清缓存。 ## 使用 MangoDisk 检查 Xcode Derived Data 如果更习惯先查看大小和准确位置，再决定是否清理，[MangoDisk 深度清理](/zh/docs/features/deep-clean)中包含独立的 Xcode Derived Data 规则。 这条规则刻意保持了很窄的边界：只处理默认的 `~/Library/Developer/Xcode/DerivedData` 根目录，要求先关闭 Xcode，并且不会默认选中。它不包含项目源码、Archives、签名材料、模拟器设备或已安装的模拟器运行时。扫描完全在本地进行，清理前需要由你检查结果并确认。完整的确认和清理历史流程可以参考 [MangoDisk 安全指南](/zh/docs/safety)。 ## 常见问题 ### Xcode 打开时可以删除 Derived Data 吗？ 不要在构建、测试或索引时删除。先退出 Xcode，避免清理过程中相关文件仍在被写入。 ### 删除 Derived Data 能修复所有 Xcode 构建错误吗？ 不能。它适合处理过期或状态不一致的生成数据，但无法修复源代码错误、签名无效、依赖缺失或错误的构建设置。 ### 多久应该清理一次？ 只有在能够释放明显空间，或者有证据表明构建数据已经异常时才需要清理。每次构建后清空健康的 Derived Data 没有收益。 ### 为什么清理后目录又出现了？ 这是正常现象。只要再次构建项目或执行索引，Xcode 就会重新创建 Derived Data。清理的目的是移除旧的生成数据，而不是关闭后续构建缓存。 ## 参考资料 - [Xcode 26 Release Notes：清理 Derived Data 的故障恢复步骤](https://developer.apple.com/documentation/Xcode-Release-Notes/xcode-26-release-notes) - [Apple Technical Note TN3118：Clean Build Folder](https://developer.apple.com/documentation/technotes/tn3118-debugging-your-apps-launch-screen) - [Xcode 4 Release Notes：工作区索引在 Derived Data 中的位置](https://developer.apple.com/library/archive/documentation/Xcode/Conceptual/RN-Xcode-Archive/Chapters/xc4_release_notes.html) - [Cargo 缓存和 target 目录有什么区别？](/zh/blog/cargo-cache-vs-target-folder) 希望先用可视化方式检查开发工具生成的数据，再决定清理哪些内容？可以[下载 MangoDisk](/zh)，在本地运行深度清理。