Unity Library目录完全指南：缓存原理、删除时机与重导入加速

Unity的项目根目录里，有个文件夹动不动就被人点名批评，就是Library。我入行做Unity开发这些年，被它坑过也被它救过：有时候项目报错怎么都消不掉，删一次Library立刻治愈；有时候只是想清理磁盘空间，却在删完重导入的半小时里怀疑人生。今天这篇，我打算把和Library目录打交道的经验完整聊一遍——它里面到底有什么、什么情况下非删不可、怎么删才不容易二次踩坑、以及团队协作、磁盘空间管理和重导入加速这些平常不太有人讲透的细节。不管你是刚接触Unity的新人，还是带着大型项目到处救火的资深开发者，这篇应该都能用得上。

1. Library缓存的是“加工结果”，不是项目的“革命本钱”

1.1 先搞懂Unity的导入管线在做什么

很多刚入门的朋友对Library有一个认知误区，觉得它像Build出来的游戏包一样属于“可以随手删的垃圾”。实际上，Library里存的是Unity导入管线处理过的半成品数据，它不是垃圾，但确实可以安全删除然后重新生成。

Unity里面Assets目录存放的是原始资源文件，比如PNG贴图、FBX模型、音频、Prefab、Script脚本等等。这些东西引擎不能直接拿来用，需要经过一道“导入”工序。导入时引擎会读取Assets目录里每个资源旁边的.meta文件，知道这个资源叫什么、GUID是多少、用哪个导入器、导入参数是什么，然后生成引擎真正能识别的资源数据，写到Library目录里去。

可以打个比方：Assets是菜市场买回来的原材料，.meta文件是你记账时写的备注，Library是厨房里切好洗好的半成品。正常开发时你一直用半成品，效率很高；一旦半成品坏了，把整个冰箱清掉重新备菜就行，虽然花时间，但你不会真把材料本身弄丢。

1.2 Library里面到底装了什么东西

打开一个大项目的Library目录，你会发现子文件夹特别多。我按实际开发中遇见的频率和体积排了个表：

这里最需要记住的是：Assets目录里的原始文件才是真正不可替代的数据，Library里的东西全部可以由Assets里的原始文件重新生成。所以“删掉Library会不会丢失项目数据”这个问题的答案很明确：不会，但要付出重新导入的时间成本。

1.3 为什么我不建议手动删Library里的单个子目录

有一种操作我特别不建议新手尝试：项目出了点问题，就进Library里挑一个看着可疑的子目录删掉。这样做的问题在于，Unity的导入管线是一个整体状态机，各个子目录之间的缓存互相有依赖关系。你单独删掉ShaderCache，编辑器顶多重新编译一阵子，问题不大；但如果你单独删掉Artifacts，其他缓存还保留着旧状态，很容易出现“编辑器认为资源已经导入完成，实际数据却已经缺失”的奇怪状态，最后比不删还难排查。

我见过最野的做法是把Library里的目录删得只剩PackageCache，理由是“省得重新下载包”。这种操作偶尔能蒙对，但一旦包资源和导入资产之间产生了半生不熟的交互状态，排查起来相当痛苦。正确的姿势很简单：要么不要轻易动Library，要么就等Unity完全退出后整体删掉整个目录，让引擎从头完整生成一遍。

2. 什么时候该删Library，什么时候先别急着动

2.1 症状一：报错怎么都消不掉，反反复复

一类很典型的情况是编辑器里出现各种“不该存在”的报错，比如：

• Internal build system error
• Could not load file or assembly
• 某个Shader编译报错，但把资源重新导入N遍还是老样子
• 场景打开后一堆组件显示成Missing
• UI布局错乱、Inspector面板刷新不出来

这些问题的根源很多都指向Library里的缓存已经和Assets目录里的原始资源脱节。最常见的原因是编辑器非正常退出，比如电脑断电、Unity被强杀、系统蓝屏，导致Library部分文件写入到一半。还有一种情况是杀毒软件把Library里的某些缓存文件隔离或删除了，编辑器却还按旧状态判断数据完整。

我之前调一个材质时遇到过特别邪门的情况：法线贴图换了一版，但材质效果一会儿新一会儿旧，无论怎么点击Reimport都时好时坏。最后一怒之下关掉Unity删掉整个Library，重新打开后几乎立刻恢复正常。那次之后我对“奇怪但说不清原因的问题”的第一反应就变成了检查Library状态。

2.2 症状二：换Unity版本、换机器、迁移工程路径后问题不断

当你更换Unity编辑器版本时，导入管线的部分变化可能使旧的Library数据不兼容。Unity官方一般会自己处理一部分导入升级，但处理不干净的情况并不少见。升级后如果出现Prefab组件丢失、资源显示异常、编译通过但运行结果不对，最稳妥的方法就是在合适的节点删一次Library，做一次全新的干净导入。

同样的问题也会出现在工程迁移场景里。把项目从一台机器拷到另一台机器，或者从D盘移到E盘，虽然Assets里的资源引用跟路径无关，但Library里有一部分生成数据记录过机器的绝对路径信息，迁移后可能出怪问题。与其浪费时间去一个个查可疑路径，不如直接把Library删掉重新生成。

2.3 症状三：杀毒软件、云同步工具、意外断电把缓存搞坏了

很多人会把Unity工程放进OneDrive、iCloud、坚果云这类同步盘里，图个自动备份。但对Unity工程来说，这是个高风险习惯。Library目录会频繁读写大量零散文件，云同步工具一边上传一边下载，很容易产生部分旧文件残留，然后编辑器就认为缓存还“活着”，实际用的时候却疯狂报错。更极端的情况是同步工具把Library和Assets之间的对应关系弄乱，导致场景里大量引用断裂。

所以我的建议是：不要在云同步目录里放Unity工程，至少要把Library目录排除在同步规则之外。如果工程已经在同步盘里且出现了不明问题，可以先关掉同步、删除本地Library、重新打开项目。如果重启后正常了，再做一次干净导入，基本能定位是不是同步盘搞的鬼。

2.4 反面场景：这些问题真的不一定要删Library

删Library不是万能药，有些情况先别急着动刀：

• 你正在进行多分支切换或版本对比实验。删掉Library后每次切分支都要等全量重导入，原本的快速对比完全没法做了。
• 你只是想解决某个包在Package Manager里的下载报错。这种情况先试试重新解析包，或者从manifest.json里调整包版本，直接删PackageCache反而会让网络恢复后重新下载很长时间。
• 你马上要发布版本。如果你当前项目打开正常，只是觉得目录有点乱，千万别在发布前贸然删Library，触发大规模重导入可能让你错过发版窗口。
• 你只是觉得游戏运行时有点卡。这个和Library关系不大，先去做Profiler采样，别把优化问题上升到删库。

我自己的原则是：项目打开正常、能构建、没报错，就坚决不删Library；一旦出现“查不出原因、反复出现、常规手段无效”的问题，删库就排在排查顺序前面。

3. 一次标准的“删库”实操：从报错到恢复正常

3.1 删除之前必须确认的三件事

很多新手删完Library出问题，其实不是因为Library不能删，而是把别的东西也一起删了，或者在错误状态下删的。动手前请确认三件事：

第一，Assets目录完整性。确认工程的Assets、Packages、ProjectSettings目录都在，没有被误删。这三样是工程的本体。

第二，.meta文件是否存在。Assets里的.PNG、.FBX、.cs文件旁边应该有对应的.meta文件。如果meta文件丢了，Unity会认为它是个新资源，场景里所有引用都会断掉。所以如果assets目录里少了meta，先恢复版本库再删Library，顺序不能反。

第三，Unity编辑器已经完全退出。不只是关掉窗口，最好看一下任务管理器里Unity相关的进程是否还在。特别是用了批处理模式的自动化流程时，后台进程可能残留，这种情况下删Library容易出写入冲突。

3.2 完整可复制的删除重建步骤

按下面这套流程操作，基本不会出什么幺蛾子：

1. 关闭Unity编辑器，确认相关进程退出。
2. 打开工程根目录，找到Library文件夹。
3. 直接删除整个Library文件夹。建议用Shift+Delete彻底删除，避免进回收站占空间。
4. 顺手可以删除Temp和Logs目录，这两个也是可再生目录，删除能腾出一点空间，但不是必须。
5. 重新打开Unity，选择该工程。
6. 等待编辑器完成全量导入。

这一步最关键的是等待。启动时Unity往往不会一次把进度条走完，可能先弹一个“Importing Assets”的进度条，完了之后还会进入编辑器继续后台导入。后台导入期间项目看起来能操作，但场景里有些资源可能还是空的，需要等右下角进度提示完全消失。

3.3 重建期间的“假死”现象怎么看

大型项目重导入时，经常会遇到进度条卡在同一位置不动的情况，容易让人以为电脑死机了。绝大多数时候不是死机，只是Unity正在处理某个巨型资源，比如一个面数很高的FBX模型、一张分辨率为8192的贴图或者一个复杂的Shader Graph。这种资源单颗耗时经常是几十秒到几分钟。

如果实在不放心，打开Windows任务管理器或macOS活动监视器，看Unity进程是否还在消耗CPU、硬盘读写是否活跃。只要进程活着且有读写活动，就让它继续跑。有时候你看着界面很久没反应，其实只是进度条的刷新粒度太粗。

我在实测中发现，全量重导入过程中不要急着去动工程目录、不要切git分支、不要把某些文件手动复制进去，否则容易和导入过程产生竞争。可以趁这个时间去做点别的事情，比如查资料或者写文档，把电脑留给Unity就好。

3.4 重建完成后建议马上做五分钟检查

干净导入完成后，别急着开始改东西，先花五分钟确认下面几项：

• 随点开一个Prefab，看引用是否正常。正常状态下不会立刻报Missing。
• 检查几个关键材质球的Shader是否按预期显示。如果之前遇到的阴影和Shader问题，这一步就能验证是不是缓存作怪。
• 如果项目用了实时GI或烘焙GI，观察Lighting窗口是否有提示需要重新生成数据。删除Library后GI中间缓存没了，有些场景会要求重新烘焙或重新生成临时GI。
• 编辑器窗口布局可能会恢复默认，需要重新拖一下面板，这个不影响项目数据。
• 如果项目即将发布，建议先跑一次Build验证脚本引用和资源打包流程都正常。

走完这套检查，基本可以确定这次删库重建是干净的。

4. Library膨胀到几十个GB：谁是罪魁祸首，怎么治理

4.1 最常见的几个体积大户

Unity项目开发到中后期，Library轻松突破10GB是常态，我这边的项目高峰期到过40多GB。膨胀的关键原因主要有这几个：

很多开发者一看到ShaderCache几个GB就慌了，其实它是在帮你节省时间。如果你经常调整Shader或者切换渲染管线，保留ShaderCache能让编辑器启动和材质编译快很多，我觉得没必要为了省那几GB频繁去删。真正容易堆积、删了也没多少心理负担的是PlayerDataCache和PackageCache。

4.2 磁盘告急时的安全清理顺序

如果你磁盘空间真的很紧张，又不想承担全量重导入的时间成本，可以按下面的优先级进行“局部清理”：

1. 找出体积最大的子目录。直接在文件夹属性里看子目录大小，确认大头是谁。
2. 删除Library/PlayerDataCache和Library/PlayerScriptAssemblies。这两个是构建过程残留，删掉后下次Build会重新生成，对平时开发几乎无感。
3. 删除Library/ShaderCache。如果你的项目启动时着色器编译很耗时，删完第一次运行可能感觉明显变卡，之后会重新建立缓存。
4. 删除Library/PackageCache。这个需要谨慎，删除后编辑器重新打开时会根据Packages/manifest.json重新从包里解析和下载，网络状况不好时第一次打开会很慢，甚至可能打开失败。
5. 最后才考虑删除整个Library。把它当作“终极手段”，只用在空间严重不足且上述清理无效的时候。

注意，Library/GI不要为了省空间随手删，尤其项目里做了大量光照烘焙的情况下。删掉之后Unity可能不会自动重新烘焙，而是把部分GI中间数据变成缺失状态，等你下次打开场景后才发现灯光表现不对，到时候还得专门安排时间重新处理。

4.3 把GI缓存挪到别的盘，比删了更实用

当你的主盘空间吃紧，但又不希望删掉GI缓存导致光照工作流被破坏时，可以试着把GI缓存位置挪到其他磁盘。Unity编辑器偏好设置里有一个Cache相关的路径配置，GI缓存可以在Preferences下的GI Cache面板里指定路径。把缓存路径指到一块空间更充裕的硬盘，既能保留缓存，又不用纠结C盘爆红。

这个方法在大团队里特别有用。美术同学电脑上经常残留大量光照烘焙缓存，而他们基本都是用SSD做开发盘，空间本来就紧张。给美术机统一设置一个缓存路径到机械盘或者网络存储，项目主盘能轻松很多。

4.4 平台打包时的一个坑：别在发布前清理这些缓存

如果你正在做WebGL、微信小游戏或者Android发布，建议发布前不要碰PackageCache和PlayerDataCache。打包过程会用到对应平台的大量包缓存和已编译数据，你一旦为了“清理空间”把它们删了，下一次Build会从零开始准备，耗时可能从几分钟变成半小时以上。这在发布排期紧张的时候非常致命。

我给自己定的规矩是：清理Library只挑非交付节点的时间做，比如一个大版本功能合入后的开发间隙。临近打包的前一天，我绝对不会动Library里任何东西。

5. 团队协作时Library到底该不该进版本库

5.1 标准答案：不提交Library，但Assets和ProjectSettings必须提交

这个问题隔段时间就有人问一次。结论很清晰：Library不要纳入版本管理。你提交的应该是Assets、Packages和ProjectSettings三个目录。

Assets是项目本体，包含所有原始资源和.meta文件。Packages里的manifest.json记录了项目依赖了哪些包。ProjectSettings里保存了项目名称、公司名、版本号和一些项目级设置。这三个目录加在一起，才能让别人或者CI完全重建出你的项目。

对应的.gitignore配置可以参考下面这段：

# Unity 项目常用忽略规则 [Ll]ibrary/ [Tt]emp/ [Oo]bj/ [Bb]uild/ [Bb]uilds/ [Ll]ogs/ [Uu]ser[Ss]ettings/ [Mm]emoryCaptures/ [Rr]ecordings/ # 本地IDE与系统文件 .vs/ .vscode/ .idea/ .DS_Store

如果团队用的是SVN而不是Git，规则一样：Library目录加进忽略列表，不要提交。很多SVN团队在这个问题上吃过亏，因为SVN默认会把所有文件都加入版本库，用到Unity的SVN项目很容易把Library整个传到仓库里。

5.2 为什么Assets里的meta文件比Library里的缓存更值钱

很多人不理解，为什么一个那么小的.meta文件反而比几十GB的Library重要得多。因为所有场景引用、Prefab嵌套、脚本挂载关系，本质上都是通过资源的GUID来匹配的。meta文件记录了每个资源的GUID和导入参数，而Library只是把“GUID对应的导入结果”缓存起来。

只要Assets和meta齐全，任何人拿到代码之后都能在本地重建一份全新的Library。反过来，如果Library被提交了，但Assets里的某个meta和你本地版本库的状态对不上，依赖关系就乱了。这也是为什么我在删Library之前一定要确认meta文件都在，它们是整个引用体系的锚点。

5.3 一次糟糕的Library提交事故复盘

之前在外包项目组里碰到过一件印象很深的事。有个新同事第一天入职，觉得“把Library提交上去，团队其他人打开工程就不用等导入了”，于是一股脑把Library加进了git仓库。项目组所有成员pull下来之后，编辑器一个接一个报错，因为有人用的Unity版本和提交Library的人不一致，导入管线的版本差异让缓存直接失效。

最后全组的解决方法是：先把Library从版本库里清理掉，更新.gitignore，然后每个人都删一次本地Library，重新完整导入一次。那一次事故浪费了大半天时间，但从此全组养成了一个习惯：版本库里永远不允许出现Library。如果你发现团队仓库里已经存在Library，越早清理越好，不要等它变成常规依赖。

5.4 团队统一升级Unity版本时的“删库流程”

团队升级Unity大版本时，把流程标准化可以有效减少混乱。我建议走下面这几步：

1. 在主干分支上，由专人先用新版本Unity打开工程，处理升级提示和报错。
2. 确认没有明显问题后，关闭Unity，删除本地Library。
3. 再次打开Unity做一次干净导入，验证场景、脚本、资源都正常。
4. 把Assets、Packages、ProjectSettings的改动（包括meta变化）提交到代码库。
5. 通知团队其他成员拉取代码，并要求他们各自删除本地Library后再打开工程。

这套流程的核心思想是：升级版本带来的缓存不兼容问题，尽量在主干上解决，其他成员不要在旧的脏缓存上继续开发，否则会把低级错误混进新代码里。

6. 全量重导入慢到想骂人，怎么把时间压下来

6.1 确认你用的是Asset Database v2和可用的加速方案

Unity 2020.3之后，Asset Database v2基本是默认状态。相比老版本，它的导入速度和多线程利用率有明显提升。如果你的项目还跑在很老的Unity版本上，升级到带ADB v2的版本本身就是一次重导入速度优化。

另一个大杀器是Unity Accelerator，也就是很多人口中的缓存服务器。它的思路很简单：团队里某一台机器完整导入过某一份资源后，加速器就把这个导入结果缓存下来。其他机器删除Library重新导入时，如果发现缓存里有相同GUID、相同导入参数、相同源文件哈希的数据，就不再从零计算，而是直接从加速器拉取现成的产物。

对频繁删Library或者经常切换机器的开发者来说，Unity Accelerator是花小钱省大时间的典型方案。个人项目也可以在本地跑一个加速器进程，实测下来重导入时间能压缩不少。

6.2 现实向的加速手段：杀毒排除、SSD、别放同步盘

先讲一个最容易被忽略的问题：Windows Defender或其他杀毒软件扫描Unity工程目录时会拖慢大量的文件读写。尤其在Library全量重建阶段，成千上万个临时文件被反复读写，杀毒软件实时扫描会让导入速度严重下降。我建议把整个Unity工程目录加入杀毒软件的排除列表，或者至少把Library加入排除项。

硬件层面，项目一定要放在SSD上，机械硬盘全量导入大艺术工程会让你等到崩溃。内存方面，16GB是底线，32GB会更舒服，因为导入过程中Unity会同时开多个Worker进程。

还有一个现实经验：工程千万别放在OneDrive、坚果云这类自动同步的目录里。云同步工具的实时上传下载不仅拖慢磁盘IO，还可能把Library弄坏。这也是我在第2节提到的高风险行为，值得再强调一次。

6.3 重导入过程中还能顺手做什么

重导入的时候，编辑器虽然忙，但也不是完全不能碰。我个人建议先把代码和美术资源的版本固定在目标状态，避免导入途中有人提交新资源导致状态变化。如果你的项目比较大，可以在开始重导入之前通知队友暂时不要往公共分支上推送大批量资源，等导入完成后再继续。

另外，最好把系统的自动睡眠功能关掉。全量导入常常需要几十分钟，如果电脑中途睡着了，导入进程可能被挂起甚至失败。这个坑我踩过，开场半小时进度到80%，电脑一睡，醒来发现导入状态已经乱了。

6.4 给一个可参考的实测时间预期

不同规模的项目全量重导入时间差别很大。我这边以一个美术资源10GB左右的中型项目举例：在一台i7、32GB内存、SATA SSD的机器上，直接删Library重导入大约需要28到35分钟；加了杀毒排除和本地加速器之后，同样项目的第二次删库重导入能压到10到15分钟。如果你的项目全是程序生成的小资源，可能几分钟就好；如果项目里有十几个高模和大纹理，一小时以上也不稀奇。

所以，删Library之前最好预估一下时间成本，别在开会前十分钟手贱删库，这都是过来人用血泪换来的教训。

7. 长期养成的几个习惯，帮你少走弯路

写到最后，分享几个我自己长期坚持的习惯，可能比上面所有理论都更有实操参考价值。

第一个习惯是每次打开大型项目前瞄一眼磁盘剩余空间。Library这个目录是真的会无声无息膨胀的，尤其团队里有好几个美术在共用一个工程目录时，一段时间不看就能多出好几个GB。定期查看Library子目录体积，把过期的构建缓存清一清，比等到磁盘爆红再手忙脚乱删库要舒服得多。

第二个习惯是换Unity大版本那天，一定安排一次“删库仪式”。升级完、处理完报错、保存好一切之后，关掉编辑器删掉Library，让新版本做一次干净导入。虽然多花点时间，但能避开大量脏缓存导致的隐性bug。这个习惯帮我躲过了很多“为什么升级后场景显示不对”的疑难杂症。

第三个习惯是尽量不要在即将打包发布的前一天做任何Library清理。打包流程对缓存依赖很大，贸然清理缓存可能让构建时间翻倍，排期就被打乱了。清理工作放到版本稳定后的开发空窗期去做，才不会给自己添堵。

第四个习惯是团队里明确禁止提交Library目录，同时保证新成员入职时先执行一次干净导入。版本库里的Library一旦出现，立刻安排人清理，不要等它变成历史包袱。这个习惯救了我不止一次。

最后想说，Library目录本身不是怪物，它是一个生产环境里的正常缓存系统。理解它、尊重它、知道什么时候动它，比一味地害怕它或者无脑删它都要重要。希望这篇经验整理能让你下次再遇到Unity工程“很奇怪”的时候，多一个排查方向和应对思路。