[{"data":1,"prerenderedAt":595},["ShallowReactive",2],{"blog-article-\u002Fzh\u002Fblog\u002Fhow-to-clear-xcode-derived-data-safely":3},{"id":4,"title":5,"author":6,"body":7,"category":576,"cover":577,"coverAlt":578,"description":579,"draft":580,"extension":581,"meta":582,"navigation":583,"path":584,"publishedAt":585,"seo":586,"stem":587,"tags":588,"translationKey":592,"updatedAt":593,"__hash__":594},"articles_zh\u002Fzh\u002Fblog\u002Fhow-to-clear-xcode-derived-data-safely.md","如何安全清理 Xcode Derived Data","Harry",{"type":8,"value":9,"toc":560},"minimark",[10,19,27,33,38,41,57,60,63,80,83,87,173,184,188,191,220,223,227,230,296,299,315,318,338,341,388,391,395,402,405,444,447,451,454,457,460,464,473,483,486,491,494,498,501,505,508,512,515,518,548,556],[11,12,13,14,18],"p",{},"Xcode Derived Data 可以安全删除。默认目录里保存的是 Xcode 能够重新生成的构建产物和索引，删除后",[15,16,17],"strong",{},"不会丢失项目源代码","，代价只是下一次构建和代码索引需要更长时间。",[11,20,21,22,26],{},"真正需要注意的是清理范围：先退出 Xcode，并确认删除的是 ",[23,24,25],"code",{},"~\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData","，不要误删 Archives、模拟器设备数据或项目目录。",[28,29,30],"blockquote",{},[11,31,32],{},"本文路径与检查命令于 2026 年 8 月 10 日在 macOS 15.7.7、Xcode 16.2 环境验证。Xcode 菜单可能随版本调整，但只要没有自定义构建位置，默认 Derived Data 路径和下文的终端方法仍然适用。",[34,35,37],"h2",{"id":36},"xcode-derived-data-是什么","Xcode Derived Data 是什么？",[11,39,40],{},"Xcode 会把构建项目和理解代码时生成的文件放入 Derived Data，常见内容包括：",[42,43,44,48,51,54],"ul",{},[45,46,47],"li",{},"编译结果和中间构建文件",[45,49,50],{},"用于代码跳转、搜索和补全的索引",[45,52,53],{},"构建日志及其他项目级辅助数据",[45,55,56],{},"当前工作区使用的 Swift Package 本地检出和相关构建数据",[11,58,59],{},"Apple 的文档说明工作区索引位于独立的 Derived Data 目录中，Xcode 发布说明也会在部分构建故障的恢复步骤中建议清理对应项目的 Derived Data。换句话说，这个目录应当可以重新生成，不应该作为源代码的唯一保存位置。",[11,61,62],{},"以下情况适合考虑清理：",[42,64,65,68,71,74,77],{},[45,66,67],{},"已经不用的旧项目留下了数 GB 构建数据",[45,69,70],{},"Xcode 反复使用过期构建结果",[45,72,73],{},"代码补全或索引状态异常",[45,75,76],{},"Xcode 升级后，Package 或 Macro 构建失败",[45,78,79],{},"当前更需要磁盘空间，可以接受首次重建变慢",[11,81,82],{},"不要因为 Derived Data 存在就定期清空。正在开发的项目可以利用增量构建数据缩短编译时间；一个体积很小且工作正常的目录没有清理价值。",[34,84,86],{"id":85},"哪些内容可以安全删除","哪些内容可以安全删除？",[88,89,90,106],"table",{},[91,92,93],"thead",{},[94,95,96,100,103],"tr",{},[97,98,99],"th",{},"位置",[97,101,102],{},"建议",[97,104,105],{},"删除后的影响",[107,108,109,123,136,149,162],"tbody",{},[94,110,111,117,120],{},[112,113,114],"td",{},[23,115,116],{},"~\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\u002F项目名-*",[112,118,119],{},"可清理确认过的单个项目",[112,121,122],{},"该项目需要重新构建和索引",[94,124,125,130,133],{},[112,126,127,129],{},[23,128,25],{}," 内的全部内容",[112,131,132],{},"需要彻底重置时可以清理",[112,134,135],{},"所有 Xcode 项目都需要重新构建和索引",[94,137,138,143,146],{},[112,139,140],{},[23,141,142],{},"~\u002FLibrary\u002FDeveloper\u002FXcode\u002FArchives",[112,144,145],{},"不要当作缓存清理",[112,147,148],{},"可能丢失用于分发或崩溃分析的归档与匹配调试符号",[94,150,151,156,159],{},[112,152,153],{},[23,154,155],{},"~\u002FLibrary\u002FDeveloper\u002FCoreSimulator\u002FDevices",[112,157,158],{},"必须单独检查",[112,160,161],{},"可能丢失模拟器应用、设置和测试数据",[94,163,164,167,170],{},[112,165,166],{},"Git 仓库或项目目录",[112,168,169],{},"不要删除",[112,171,172],{},"这里保存的才是源代码和项目配置",[11,174,175,176,179,180,183],{},"清理前还应打开 Xcode 的 ",[15,177,178],{},"Settings → Locations","。如果 Derived Data 被设置成 ",[15,181,182],{},"Custom","，请以这里显示的路径为准，不要直接套用默认目录。",[34,185,187],{"id":186},"方法一通过-finder-清理-derived-data","方法一：通过 Finder 清理 Derived Data",[11,189,190],{},"如果希望先看清每个项目目录再删除，Finder 是最直观的方式。",[192,193,194,197,204,211,214,217],"ol",{},[45,195,196],{},"保存工作，停止正在运行的构建和测试。",[45,198,199,200,203],{},"打开 ",[15,201,202],{},"Xcode → Settings → Locations","。",[45,205,206,207,210],{},"找到 ",[15,208,209],{},"Derived Data","，点击路径旁的箭头，在 Finder 中打开目录。",[45,212,213],{},"退出 Xcode。",[45,215,216],{},"只把存在问题或已经不用的项目目录移到废纸篓；需要完全重置时，再移动 Derived Data 目录内的全部内容。",[45,218,219],{},"重新打开 Xcode 并构建项目。",[11,221,222],{},"先移到废纸篓可以保留一个短暂的恢复机会。确认项目能够正常打开和重新构建后，再清空废纸篓。",[34,224,226],{"id":225},"方法二通过终端检查和清理","方法二：通过终端检查和清理",[11,228,229],{},"先确认目录和总占用：",[231,232,237],"pre",{"className":233,"code":234,"language":235,"meta":236,"style":236},"language-bash shiki shiki-themes github-light github-dark","du -sh \"$HOME\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\"\ndu -sh \"$HOME\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\"\u002F* 2>\u002Fdev\u002Fnull | sort -h\n","bash","",[23,238,239,263],{"__ignoreMap":236},[240,241,244,248,252,256,260],"span",{"class":242,"line":243},"line",1,[240,245,247],{"class":246},"sScJk","du",[240,249,251],{"class":250},"sj4cs"," -sh",[240,253,255],{"class":254},"sZZnC"," \"",[240,257,259],{"class":258},"sVt8B","$HOME",[240,261,262],{"class":254},"\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\"\n",[240,264,266,268,270,272,274,277,280,284,287,290,293],{"class":242,"line":265},2,[240,267,247],{"class":246},[240,269,251],{"class":250},[240,271,255],{"class":254},[240,273,259],{"class":258},[240,275,276],{"class":254},"\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\"\u002F",[240,278,279],{"class":250},"*",[240,281,283],{"class":282},"szBVR"," 2>",[240,285,286],{"class":254},"\u002Fdev\u002Fnull",[240,288,289],{"class":282}," |",[240,291,292],{"class":246}," sort",[240,294,295],{"class":250}," -h\n",[11,297,298],{},"每个项目目录通常以可识别的项目名开头，后面跟着一段唯一标识。可以先在 Finder 中打开检查：",[231,300,302],{"className":233,"code":301,"language":235,"meta":236,"style":236},"open \"$HOME\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\"\n",[23,303,304],{"__ignoreMap":236},[240,305,306,309,311,313],{"class":242,"line":243},[240,307,308],{"class":246},"open",[240,310,255],{"class":254},[240,312,259],{"class":258},[240,314,262],{"class":254},[11,316,317],{},"如需永久删除单个项目，请把示例目录名替换成自己输出中的完整名称：",[231,319,321],{"className":233,"code":320,"language":235,"meta":236,"style":236},"rm -rf \"$HOME\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\u002FYourProject-xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n",[23,322,323],{"__ignoreMap":236},[240,324,325,328,331,333,335],{"class":242,"line":243},[240,326,327],{"class":246},"rm",[240,329,330],{"class":250}," -rf",[240,332,255],{"class":254},[240,334,259],{"class":258},[240,336,337],{"class":254},"\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\u002FYourProject-xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n",[11,339,340],{},"如需永久删除默认 Derived Data 目录内的所有项目：",[231,342,344],{"className":233,"code":343,"language":235,"meta":236,"style":236},"find \"$HOME\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\" \\\n  -mindepth 1 -maxdepth 1 -exec rm -rf {} +\n",[23,345,346,361],{"__ignoreMap":236},[240,347,348,351,353,355,358],{"class":242,"line":243},[240,349,350],{"class":246},"find",[240,352,255],{"class":254},[240,354,259],{"class":258},[240,356,357],{"class":254},"\u002FLibrary\u002FDeveloper\u002FXcode\u002FDerivedData\"",[240,359,360],{"class":250}," \\\n",[240,362,363,366,369,372,374,377,380,382,385],{"class":242,"line":265},[240,364,365],{"class":250},"  -mindepth",[240,367,368],{"class":250}," 1",[240,370,371],{"class":250}," -maxdepth",[240,373,368],{"class":250},[240,375,376],{"class":250}," -exec",[240,378,379],{"class":254}," rm",[240,381,330],{"class":250},[240,383,384],{"class":254}," {}",[240,386,387],{"class":254}," +\n",[11,389,390],{},"这些命令不会经过废纸篓。按下回车前必须重新阅读完整路径；Xcode 正在构建、测试或索引时，不要执行最后一条命令。",[34,392,394],{"id":393},"方法三先尝试-clean-build-folder","方法三：先尝试 Clean Build Folder",[11,396,397,398,401],{},"如果只是单个项目构建异常，并不需要同时删除索引和其他工作区数据，可以先在 Xcode 中执行 ",[15,399,400],{},"Product → Clean Build Folder","。Apple 也在故障排查文档中使用过这个操作。",[11,403,404],{},"工作区对应的命令行写法类似：",[231,406,408],{"className":233,"code":407,"language":235,"meta":236,"style":236},"xcodebuild \\\n  -workspace YourApp.xcworkspace \\\n  -scheme YourApp \\\n  clean\n",[23,409,410,417,427,438],{"__ignoreMap":236},[240,411,412,415],{"class":242,"line":243},[240,413,414],{"class":246},"xcodebuild",[240,416,360],{"class":250},[240,418,419,422,425],{"class":242,"line":265},[240,420,421],{"class":250},"  -workspace",[240,423,424],{"class":254}," YourApp.xcworkspace",[240,426,360],{"class":250},[240,428,430,433,436],{"class":242,"line":429},3,[240,431,432],{"class":250},"  -scheme",[240,434,435],{"class":254}," YourApp",[240,437,360],{"class":250},[240,439,441],{"class":242,"line":440},4,[240,442,443],{"class":254},"  clean\n",[11,445,446],{},"它的范围比删除整个 Derived Data 目录更小：只是让当前构建系统清理指定项目的构建产物，不是对所有 Xcode 工作区进行磁盘清理。",[34,448,450],{"id":449},"清理后会发生什么","清理后会发生什么？",[11,452,453],{},"第一次构建通常会明显变慢。Xcode 需要重新编译 Target、创建代码索引，还可能重新解析或下载 Package 数据。在索引完成前，代码补全和跳转也可能暂时不完整。",[11,455,456],{},"项目文件、Git 历史、签名证书、Provisioning Profile 和 Xcode Archives 都不在默认 Derived Data 根目录中。只删除本文给出的准确路径时，它们不会受到影响。",[11,458,459],{},"如果完整重建后原来的错误再次出现，Derived Data 很可能不是根因。此时应检查第一条有意义的编译错误、依赖解析、当前使用的 Xcode 版本和项目 Build Settings，不要继续反复清缓存。",[34,461,463],{"id":462},"使用-mangodisk-检查-xcode-derived-data","使用 MangoDisk 检查 Xcode Derived Data",[11,465,466,467,472],{},"如果更习惯先查看大小和准确位置，再决定是否清理，",[468,469,471],"a",{"href":470},"\u002Fzh\u002Fdocs\u002Ffeatures\u002Fdeep-clean","MangoDisk 深度清理","中包含独立的 Xcode Derived Data 规则。",[11,474,475,476,478,479,203],{},"这条规则刻意保持了很窄的边界：只处理默认的 ",[23,477,25],{}," 根目录，要求先关闭 Xcode，并且不会默认选中。它不包含项目源码、Archives、签名材料、模拟器设备或已安装的模拟器运行时。扫描完全在本地进行，清理前需要由你检查结果并确认。完整的确认和清理历史流程可以参考 ",[468,480,482],{"href":481},"\u002Fzh\u002Fdocs\u002Fsafety","MangoDisk 安全指南",[34,484,485],{"id":485},"常见问题",[487,488,490],"h3",{"id":489},"xcode-打开时可以删除-derived-data-吗","Xcode 打开时可以删除 Derived Data 吗？",[11,492,493],{},"不要在构建、测试或索引时删除。先退出 Xcode，避免清理过程中相关文件仍在被写入。",[487,495,497],{"id":496},"删除-derived-data-能修复所有-xcode-构建错误吗","删除 Derived Data 能修复所有 Xcode 构建错误吗？",[11,499,500],{},"不能。它适合处理过期或状态不一致的生成数据，但无法修复源代码错误、签名无效、依赖缺失或错误的构建设置。",[487,502,504],{"id":503},"多久应该清理一次","多久应该清理一次？",[11,506,507],{},"只有在能够释放明显空间，或者有证据表明构建数据已经异常时才需要清理。每次构建后清空健康的 Derived Data 没有收益。",[487,509,511],{"id":510},"为什么清理后目录又出现了","为什么清理后目录又出现了？",[11,513,514],{},"这是正常现象。只要再次构建项目或执行索引，Xcode 就会重新创建 Derived Data。清理的目的是移除旧的生成数据，而不是关闭后续构建缓存。",[34,516,517],{"id":517},"参考资料",[42,519,520,528,535,542],{},[45,521,522],{},[468,523,527],{"href":524,"rel":525},"https:\u002F\u002Fdeveloper.apple.com\u002Fdocumentation\u002FXcode-Release-Notes\u002Fxcode-26-release-notes",[526],"nofollow","Xcode 26 Release Notes：清理 Derived Data 的故障恢复步骤",[45,529,530],{},[468,531,534],{"href":532,"rel":533},"https:\u002F\u002Fdeveloper.apple.com\u002Fdocumentation\u002Ftechnotes\u002Ftn3118-debugging-your-apps-launch-screen",[526],"Apple Technical Note TN3118：Clean Build Folder",[45,536,537],{},[468,538,541],{"href":539,"rel":540},"https:\u002F\u002Fdeveloper.apple.com\u002Flibrary\u002Farchive\u002Fdocumentation\u002FXcode\u002FConceptual\u002FRN-Xcode-Archive\u002FChapters\u002Fxc4_release_notes.html",[526],"Xcode 4 Release Notes：工作区索引在 Derived Data 中的位置",[45,543,544],{},[468,545,547],{"href":546},"\u002Fzh\u002Fblog\u002Fcargo-cache-vs-target-folder","Cargo 缓存和 target 目录有什么区别？",[11,549,550,551,555],{},"希望先用可视化方式检查开发工具生成的数据，再决定清理哪些内容？可以",[468,552,554],{"href":553},"\u002Fzh","下载 MangoDisk","，在本地运行深度清理。",[557,558,559],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":236,"searchDepth":265,"depth":265,"links":561},[562,563,564,565,566,567,568,569,575],{"id":36,"depth":265,"text":37},{"id":85,"depth":265,"text":86},{"id":186,"depth":265,"text":187},{"id":225,"depth":265,"text":226},{"id":393,"depth":265,"text":394},{"id":449,"depth":265,"text":450},{"id":462,"depth":265,"text":463},{"id":485,"depth":265,"text":485,"children":570},[571,572,573,574],{"id":489,"depth":429,"text":490},{"id":496,"depth":429,"text":497},{"id":503,"depth":429,"text":504},{"id":510,"depth":429,"text":511},{"id":517,"depth":265,"text":517},"开发者磁盘清理","\u002Fimages\u002Fblog\u002Fhow-to-clear-xcode-derived-data-safely.webp","开发者在释放磁盘空间前检查 Xcode 生成的构建数据","了解 Xcode Derived Data 包含哪些内容、什么时候可以删除，以及如何只清理单个项目或整个目录而不影响源代码",false,"md",{},true,"\u002Fzh\u002Fblog\u002Fhow-to-clear-xcode-derived-data-safely","2026-08-10T00:00:00+08:00",{"title":5,"description":579},"zh\u002Fblog\u002Fhow-to-clear-xcode-derived-data-safely",[589,590,591,576],"Xcode Derived Data","Xcode 缓存","macOS","article-how-to-clear-xcode-derived-data-safely","2026-08-12T00:00:00+08:00","bnRmC95k0NNYm7fXDNPUgwGe6Ni-sH1-kFb91Mgke4w",1786706051541]