1. 从一次版本库膨胀事故说起
团队里新来的同事把整个library和temp目录一股脑提交进了 Git，两周之后仓库体积从 80MB 涨到 1.2GB，git clone一次要等好几分钟，CI 拉代码的时间直接翻倍。这件事之后，我把 Cocos Creator 工程的忽略规则重新梳理了一遍，也踩了不少坑——比如.meta文件到底该不该忽略、build目录要不要保留、不同 Creator 版本生成的目录结构差异等等。这些问题看起来琐碎，但一旦配错，轻则仓库臃肿，重则多人协作时资源引用错乱、场景丢失。
这篇内容就是围绕Cocos Creator 工程.gitignore的正确配置展开的。我会把 Creator 工程里每个目录和文件的角色讲清楚，说明哪些必须提交、哪些必须忽略、为什么这样取舍，再给出一份可以直接复制使用的完整配置，最后聊聊多人协作中那些容易翻车的细节。不管你是刚接触 Creator 的新手，还是带团队做中大型项目的负责人，这些内容都能帮你少走弯路。
需要先明确一个前提：Cocos Creator 的工程结构和普通前端项目差别很大，它有一套自己的资源管理机制，assets目录下的每个资源都会配套生成一个.meta文件，library目录里存放的是导入后的中间产物，build目录是构建输出。这些目录的性质完全不同，忽略策略也必须区别对待。很多人直接套用网上的通用 Unity 或前端.gitignore模板，结果就是各种诡异问题。
2. Creator 工程目录的角色拆解与提交取舍
2.1 assets 目录：唯一需要完整提交的源码区
assets是 Cocos Creator 工程的核心，你所有的场景、预制体、脚本、图片、音频、字体、动画都放在这里。这个目录必须完整提交到版本库，没有任何商量余地。但这里有个关键点：assets下的每个资源文件都会伴随一个同名的.meta文件，比如player.png旁边会有player.png.meta。
.meta文件记录的是这个资源的唯一标识符（uuid）、导入设置、依赖关系等信息。Creator 靠 uuid 来定位资源，而不是靠文件路径。如果你忽略了.meta文件，别人拉下代码后 Creator 会重新生成一套新的 uuid，导致场景里引用的资源全部丢失，预制体变成空壳，脚本挂载全部断开。这是新手最容易犯的致命错误。
所以结论很明确：assets目录下的所有内容，包括.meta文件，全部提交。不要试图用*.meta这样的通配规则去忽略它们，那等于自毁工程。
2.2 library 目录：导入缓存，坚决忽略
library目录是 Creator 导入资源后生成的中间缓存，里面存放的是压缩后的纹理、序列化后的场景数据、脚本编译产物等。这个目录的特点是完全可以从assets重新生成，而且体积巨大，动辄几百MB甚至上GB。
它的存在意义是加速编辑器打开工程的速度，避免每次启动都重新导入所有资源。但它对版本控制毫无价值，因为不同机器、不同 Creator 版本生成的library内容可能不一致，提交上去只会造成冲突和混乱。所以library必须整体忽略。
有人会担心：忽略library后，别人拉下代码打开工程会不会很慢？答案是第一次打开会重新导入，之后就有本地缓存了。这个代价完全可以接受，远比仓库膨胀和冲突要好。
2.3 temp 与 local 目录：临时文件，一并忽略
temp目录存放的是 Creator 运行时的临时文件，比如构建过程中的中间产物、日志等。local目录则保存的是本地的编辑器配置，比如窗口布局、最近打开的场景、本机特定的设置。这两个目录都是纯本地性质，不同开发者之间不应该共享，必须忽略。
特别是local目录，里面可能包含你本机的路径信息、偏好设置，提交上去对别人没有任何帮助，反而可能覆盖别人的本地配置。忽略它们是标准做法。
2.4 build 目录：构建输出，按需处理
build目录是执行构建后生成的发布产物，比如 web-mobile、android、ios 等平台的输出。这个目录是否忽略，取决于你的工作流。
如果你的构建产物是通过 CI 自动生成并部署的，那build应该忽略，因为它可以从源码重新构建。如果你需要把构建产物也纳入版本管理（比如某些发布流程要求），那可以选择性提交，但通常不推荐，因为构建产物体积大、二进制文件多、diff 无意义。
我的建议是默认忽略build，需要发布时通过构建流程单独处理。这样仓库保持干净，职责清晰。
2.5 settings 与 profiles 目录：项目配置，需要提交
settings目录存放的是项目级别的配置，比如物理系统设置、渲染管线配置、分组配置等。这些配置是团队共享的，必须提交。profiles目录则可能包含一些编辑器配置，需要根据具体内容判断，但通常项目相关的配置也应该提交。
这里要注意区分：settings是项目配置，local是本地配置。前者提交，后者忽略。很多人会把这两个搞混，导致团队成员的编辑器行为不一致。
3. 一份可直接落地的完整忽略配置
3.1 基础版配置与逐行说明
下面这份配置覆盖了 Cocos Creator 工程最常见的忽略需求，可以直接放到工程根目录的.gitignore文件中使用：
# ===== Cocos Creator 忽略规则 ===== # 导入缓存目录，体积大且可重新生成 /library/ /temp/ /local/ # 构建输出目录 /build/ /native/ # 编辑器与系统生成文件 .DS_Store Thumbs.db *.swp *.swo # 日志文件 *.log npm-debug.log* # 依赖目录 /node_modules/ # 编辑器配置（如果 profiles 中包含本地特定配置） /profiles/ # 发布产物 /release/逐行解释一下关键项。/library/前面的斜杠表示只忽略根目录下的library，不忽略子目录中可能存在的同名文件夹，这样更精确。/temp/和/local/同理。/build/和/native/是构建相关目录，native是原生平台构建时的中间目录。.DS_Store是 macOS 的系统文件，Thumbs.db是 Windows 的缩略图缓存，这些都不应该进版本库。
/node_modules/是针对使用了 npm 包管理的项目，比如你用了 TypeScript 或者一些构建插件。/profiles/这个需要根据实际情况判断，如果你的团队需要共享编辑器配置，可以把它从忽略列表中去掉，只忽略其中的本地部分。
3.2 不同 Creator 版本的目录差异
Cocos Creator 从 2.x 到 3.x，目录结构有一些变化。2.x 版本中，assets目录下还有resources等特殊目录，3.x 版本中资源管理更加统一。但核心的library、temp、local、build这几个目录的忽略策略是一致的。
3.x 版本新增了extensions目录用于存放扩展插件，这个目录通常需要提交，因为它是项目的一部分。但如果扩展是从商店安装的，可能包含大量第三方代码，这时候可以考虑忽略，通过文档说明让团队成员自行安装。
另外，3.x 版本的settings目录结构更复杂，包含了v2等子目录，这些都应该提交。不要因为看到settings里有local字样就整个忽略，要具体看内容。
3.3 忽略规则写错后的补救措施
如果你已经不小心把library或temp提交了，别慌，可以补救。首先在.gitignore中添加正确的忽略规则，然后执行以下命令把已跟踪的文件从索引中移除：
git rm -r --cached library git rm -r --cached temp git rm -r --cached local git rm -r --cached build注意--cached参数，它只从 Git 索引中移除，不会删除你本地的实际文件。执行完后提交一次，这些目录就不再被跟踪了。但历史记录中的大文件还在，如果仓库已经很大，可能需要用git filter-branch或 BFG 工具清理历史，这个操作风险较高，建议先备份。
提示：清理历史前一定要和团队沟通，因为这会重写提交记录，所有人需要重新克隆仓库。
4. 多人协作中 .meta 文件的那些坑
4.1 为什么 .meta 文件冲突如此棘手
.meta文件是 JSON 格式的，里面包含 uuid、导入设置、依赖列表等。当两个人同时修改了同一个资源，或者一个人重命名了资源而另一个人还在旧路径上操作，.meta文件就会产生冲突。这种冲突不像代码冲突那样容易手动合并，因为 uuid 是唯一的，合并错了会导致资源引用断裂。
我遇到过最典型的情况是：A 同学重命名了一张图片，B 同学在不知道的情况下继续引用旧名字，合并时.meta文件冲突，手动解决后场景里的图片变成了丢失状态。排查了半天才发现是 uuid 对不上。
避免这类问题的核心原则是：资源文件的移动和重命名尽量通过 Creator 编辑器操作，不要直接在文件系统里改。Creator 会自动更新.meta文件和所有引用，保证 uuid 不变。如果你在文件系统里直接改名，Creator 会认为是删除了旧资源、新增了新资源，uuid 就变了。
4.2 合并策略与沟通机制
即使操作规范，冲突仍可能发生。对于.meta文件的冲突，我的建议是：不要试图手动合并 JSON 内容，而是选择其中一方的版本，然后让另一方在 Creator 中重新导入或重新关联资源。具体做法是，先确定哪个版本的资源是最终想要的，保留对应的.meta，然后打开工程检查引用是否正常。
团队层面，可以约定一些规则来减少冲突：比如场景文件由专人负责，避免多人同时编辑同一个场景；资源目录按功能模块划分，每个人负责自己的模块；提交前先拉取最新代码，在本地验证无误后再推送。
4.3 场景与预制体的提交注意事项
场景文件（.scene）和预制体（.prefab）是 JSON 格式的文本文件，理论上可以 diff 和合并，但实际上非常困难，因为 Creator 生成的 JSON 结构复杂，包含大量嵌套引用。多人同时修改同一个场景几乎必然冲突。
实用的做法是：场景文件尽量保持精简，把可复用的部分做成预制体，不同的人负责不同的预制体。如果必须多人编辑同一个场景，可以约定时间段，或者使用 Creator 的分支功能（如果版本支持）。提交场景前，务必在编辑器里保存并确认没有报错，避免提交了损坏的文件。
5. 仓库瘦身与长期维护的实操建议
5.1 定期检查仓库体积与忽略有效性
配置好.gitignore不是一劳永逸的，随着项目推进，可能会有新的目录或文件类型需要忽略。建议定期用以下命令检查仓库中体积最大的文件：
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | sort -k3 -n -r | head -20这个命令会列出历史记录中最大的 20 个对象，帮你发现是否有不该提交的大文件混进来了。如果发现library或build里的文件还在历史中，说明之前的清理不彻底，需要考虑重写历史。
另外，可以用git count-objects -vH查看当前仓库的松散对象和打包对象大小，了解仓库的整体健康状况。
5.2 大文件存储的替代思路
如果项目中有大量二进制资源（比如高清纹理、音频、视频），即使正确忽略了缓存目录，assets本身也可能很大。Git 对二进制文件的处理效率不高，每次修改都会产生完整副本，导致仓库快速膨胀。
这种情况下可以考虑使用 Git LFS（Large File Storage）来管理大文件。Git LFS 会把大文件存储在单独的服务器上，仓库里只保留指针文件。配置方法是在工程根目录执行：
git lfs install git lfs track "*.png" git lfs track "*.jpg" git lfs track "*.mp3" git lfs track "*.mp4"执行后会生成.gitattributes文件，把它提交到仓库。之后这些类型的文件就会通过 LFS 管理。需要注意的是，LFS 需要服务器支持，而且团队成员都需要安装 LFS 客户端，否则拉取时会得到指针文件而不是实际内容。
5.3 新成员入职时的环境检查清单
为了让新同事快速上手，避免因为忽略配置不当导致的问题，可以准备一份简单的检查清单：
- 确认已安装与项目匹配的 Cocos Creator 版本
- 克隆仓库后，检查
library、temp、local、build目录是否为空（首次打开前） - 用 Creator 打开工程，等待资源导入完成
- 检查场景和预制体是否有资源丢失的警告
- 确认
.gitignore文件存在且内容正确 - 如果使用了 Git LFS，确认已执行
git lfs install
这份清单看起来简单，但能避免很多“为什么我这里跑不起来”的扯皮。特别是资源导入这一步，第一次打开工程可能需要几分钟到十几分钟，取决于资源数量，新人不知道的话容易以为卡死了。
6. 几个容易被忽略的边界情况
6.1 自定义构建模板与扩展目录
有些项目会自定义构建模板，放在build-templates目录下。这个目录是需要提交的，因为它包含了构建时的定制化配置。如果你在.gitignore里用了过于宽泛的build*规则，可能会误伤这个目录。正确的做法是明确写/build/而不是build，避免匹配到build-templates。
类似地，extensions目录如果包含项目自研的扩展，需要提交；如果是第三方扩展，可以考虑忽略并在文档中说明安装方式。关键是要明确每个目录的归属和用途，不要一刀切。
6.2 多平台构建产物的处理
如果你的项目需要同时构建 web、Android、iOS 多个平台，build目录下会有多个子目录。这些都应该整体忽略。但有时候原生平台构建会生成native目录，里面可能包含一些需要保留的配置文件。这种情况下，可以忽略native的大部分内容，但用!规则保留特定文件：
/native/* !/native/engine/ !/native/engine/config.json这种否定规则的用法需要小心，因为 Git 的忽略规则是从上到下匹配的，后面的规则可以覆盖前面的。但一旦某个目录被忽略，里面的文件就无法通过否定规则重新包含，除非父目录没有被忽略。所以更稳妥的做法是精确指定要忽略的子目录，而不是先忽略全部再排除。
6.3 忽略规则的作用范围与优先级
.gitignore文件可以放在多个层级，根目录的规则作用于整个仓库，子目录的规则只作用于该子目录。如果子目录的规则和根目录冲突，子目录的规则优先。这个特性可以用来做精细控制，比如在assets下放一个.gitignore来忽略某些临时资源，而不影响其他目录。
另外，.gitignore只对未跟踪的文件生效。如果一个文件已经被跟踪，后来才添加到.gitignore，它仍然会被继续跟踪。必须先用git rm --cached移除跟踪，忽略规则才会生效。这个机制经常让人困惑，以为改了.gitignore就万事大吉，结果发现文件还在提交列表里。
7. 我在实际项目中的几点体会
配置.gitignore这件事，说简单也简单，一份模板就能覆盖大部分场景；说复杂也复杂，因为每个项目的结构、团队的习惯、使用的工具链都不一样。我自己的经验是，不要盲目复制网上的模板，而是先花半小时把工程目录结构摸清楚，理解每个目录的用途，再针对性地写规则。
另外，.gitignore应该随着项目演进而更新。比如项目初期没有用 TypeScript，后来引入了，就要加上node_modules和编译产物的忽略；再比如接入了新的构建流程，产生了新的中间目录，也要及时补充。把它当成一份活的文档来维护，而不是一次性任务。
最后分享一个小技巧：在工程根目录放一个README或者在.gitignore里用注释说明每条规则的原因，这样新成员看到时能快速理解，也方便日后自己回顾。比如为什么忽略library、为什么.meta必须提交，写清楚原因比单纯写规则更有价值。团队里因为忽略配置不当引发的问题，往往不是规则写错了，而是没人知道为什么这么写。
