Cocos Creator 2.4.x 项目 .gitignore 配置与仓库瘦身实战

做过 Cocos Creator 2.4.x 项目的人应该都有体会：真正让仓库变得难维护的，往往不是美术资源，而是那个不起眼的 .gitignore。尤其是 2.4.13 这个版本，项目里目录结构多而杂，library、temp、build、local 这些目录每天都会变，如果没在项目初期就配好忽略规则，用不了多久 Git 仓库就会膨胀到几百兆，同事每次 clone 都要等半天。这篇文章我就结合自己实际维护 2.4.13 项目的经验，给出一份可以直接抄的 .gitignore 配置，并逐个目录解释为什么这么写。适合刚接手 Cocos Creator 项目、或者被仓库体积问题困扰的开发者参考。

1. 为什么 Cocos Creator 项目必须优先处理 .gitignore

1.1 一次误提交 library 引发的仓库灾难

我印象最深的一次：项目做到第二个版本时，新同事用 IDE 的 Git 面板直接点提交，把 library、temp 一起推上去了。当天仓库体积从 200MB 涨到 800MB，之后每次拉代码都提示“看起来像大文件变更”，编辑器却报各种资源找不到。

为什么会有这个后果？因为 Cocos Creator 的资源导入过程是“所见即所得”的：你放的每张图、每个 Prefab、每个音频，编辑器都会在 library 里生成对应的缓存版本、uuid 映射关系，temp 里则是脚本编译和场景预览的中间产物。这些文件是编辑器本机环境的“自留地”，换个机器、换个版本就会重建，根本没有提交的意义。普通同事拉下来后还经常遇到缓存冲突——同一份资源，你机器上缓存是 A 版本，同事机器是 B 版本，两个人的 assets 内容明明一样，但 Git 状态却五花八门，排查成本极高。

所以我的经验是：新项目从 git init 那一刻起，就必须把 .gitignore 写好；老项目如果发现仓库体积异常，第一件事也是检查有没有把缓存目录提交上去。

1.2 Cocos Creator 2.4.x 目录结构：哪些是源码，哪些是缓存

要配置好 .gitignore，先得把项目根目录里那一堆文件夹认清楚。Cocos Creator 2.4.x 项目打开后，典型目录大致是这些：

这里面最容易踩坑的是 assets 和 settings 不能忽略，而 library、temp、build、local 这四个几乎是“铁定忽略”。我见过有人图省事，把整个项目“除了 assets 全忽略”，结果 settings 没提交，新同事打开项目后构建面板配置完全不同，场景运行效果和本地有差异，排查了半天才发现是设置不同步。

1.3 版本控制的核心原则：只提交不可再生的内容

目录结构看明白了，规则就一句话：凡是编辑器能自动生成的，一律不提交；凡是人工创作的、删了就没法的，必须提交。放到 Cocos Creator 2.4.x 里就是：assets 是命根子，settings 和 package.json 等配置文件是团队的共同约定，build-templates 这种自定义模板算源码；library、temp、local、build、profiles 这些，都是“可再生垃圾”，一个都别要。

这个原则听起来简单，但实际操作中很多人会被干扰。比如“这个 build 包我要发给测试，是不是提交一下方便下载”——没必要，构建产物应该走独立的产物管理渠道，而不是塞进代码仓库；再比如“library 总是导致我打开项目很慢，提交上去同事就快了”——不可能，library 是跟着本机资源状态走的，提交上去不但不会加速，反而会污染别人的本地缓存。

2. Cocos Creator 2.4.13 完整 .gitignore 配置与逐行解读

2.1 可直接复制的完整 .gitignore 文件

下面这份配置是我在 2.4.13 项目里实际在用的，直接复制到项目根目录即可，文件名为 .gitignore：

bash复制# ===== Cocos Creator 2.4.x 通用缓存 =====
library/
temp/
local/
build/
profiles/

# 如果发现根目录有 .creator 本地状态目录，也建议忽略
.creator/

# ===== 原生构建产物 =====
native/
native/engine/

# ===== 依赖与插件 =====
node_modules/

# ===== 编辑器与 IDE =====
.idea/
*.iml
.vscode/
*.code-workspace

# ===== 系统文件 =====
.DS_Store
Thumbs.db
*.log

# ===== 临时与备份 =====
*.tmp
*~

注意，这里面有两个地方可以根据团队情况调整：一个是 native/，如果你团队确实在原生工程里改过东西并且想纳入版本管理，就不要整段忽略，我建议单独开一个原生工程仓库来管理，而不是和主仓库混在一起；另一个是 .vscode/，如果团队想统一调试配置，可以把 .vscode/launch.json 单独排除出来再提交，比如写成：

bash复制.vscode/*
!.vscode/launch.json

2.2 逐行拆解：library、temp、build、local 各自的作用

很多新手只知道“要忽略”，但不清楚每个目录到底做了什么，导致遇到问题不敢改。我逐个说一下。

library/ 是编辑器导入资源后的缓存中心。Cocos Creator 会扫描 assets 下的所有资源，生成 UUID、压缩纹理、预编译的脚本索引等，都存在这里。如果删掉，编辑器会自动重建，只是重建过程会花一点时间。我之前试过删掉整个 library 后重新打开项目，首次加载确实慢，但完成后一切正常，所以它有完全的“可再生”属性。

temp/ 是临时目录，包含脚本编译生成的 js 文件、场景预览数据等。它的产生非常频繁，有时候你在编辑器里跑一下场景，temp 就会更新几十个文件。如果不忽略，Git 每次都会产生大量无意义的变更记录，而且这些变更极容易和同事的本地文件冲突。

local/ 存储的是编辑器 UI 状态，比如你拖拽过哪个面板、最近打开过哪些场景，甚至包含一些和本机路径相关的缓存。它和项目本身没有任何逻辑关系，纯粹是“编辑器记住你的使用习惯”的地方，忽略它是毫无疑问的。

build/ 是构建产物目录，包括 web-mobile、web-desktop、原生工程等所有输出。这个目录不仅体积大，而且每次构建都会覆盖大量文件。团队的构建包应该走专门的产物管理流程，比如上传到内部平台或用网盘分发，而不是通过 Git 来回传。

profiles/ 存的是构建 profile，其中可能包含个人电脑的绝对路径，如 Android SDK 路径、NDK 路径等。如果提交上去，不同开发者的机器环境不一样，拉下来后反而会导致构建配置错乱。2.4.x 的团队统一构建配置建议放在 settings 里管理，profiles 直接忽略。

2.3 容易遗漏的隐藏文件与跨平台配置

除了 Cocos 自己的目录，跨平台协作时还有一批“隐形垃圾”必须处理。

.DS_Store 是 macOS 下 Finder 自动生成的目录元数据文件，几乎每一个 macOS 用户打开目录都会产生，忽略它是标配。Thumbs.db 对应 Windows 系统，Windows 用户浏览图片文件夹时可能生成，团队里只要有一个 Windows 同事，就必须把它加进去。

.idea/ 是 IntelliJ 系列 IDE 的本地配置目录，*.iml 是模块配置文件，这两项如果团队不是统一用 IDEA，强烈建议忽略。*.code-workspace 是 VS Code 的工作区文件，通常包含个人打开的文件列表、窗口布局等，如果你们用 Cocos Creator 内置的 VS Code 调试，建议忽略。

这些都是“不加就会后悔”的条目。尤其是当你和同事一个用 macOS、一个用 Windows，如果不提前处理 .DS_Store 和 Thumbs.db，每次合并都可能在文件列表里看到一堆完全不相关的系统文件，干扰你对真实变更的判断。

3. 实操：从零配置 .gitignore 并清理已误提交的缓存

3.1 新项目 5 分钟配置 .gitignore 的完整步骤

如果你是从头开始一个新项目，操作很简单。项目创建完后，在根目录新建 .gitignore，把上面那份配置粘贴进去，然后执行：

bash复制git init
git add .
git status

这时候重点看 git status 的输出。正常情况下，应该只有 assets、settings、package.json、project.json 等文件出现在待提交列表里。如果发现还带着 library、temp、build，说明你的 .gitignore 没有生效，最常见的原因是文件名拼写错误，或者文件放在了子目录。注意 .gitignore 是一个隐藏文件，前面有一个点，不要写成 gitignore 或者 .gitignore.txt，Windows 下尤其容易踩这个坑。

还有一个小建议：在 git add . 之前，先手动确认 assets 目录里的资源是否齐全。有些项目会用外部工具批量生成资源，如果这些资源还没来得及放进 assets 就提交了，同事拉下来后会缺资源。这一步虽然简单，但能省掉后面大量沟通成本。

3.2 历史仓库清理：git rm --cached 的正确打开方式

老项目已经误提交了缓存目录，怎么办？不要直接在 Git 面板里一个个删除，那样会把本地的 library 文件也删掉，重新打开项目又得等编辑器重建。正确方式是只删除 Git 缓存，保留本地文件。

bash复制git rm -r --cached library temp build local profiles .creator

执行完这行命令后，再执行：

bash复制git add .
git commit -m "chore: remove generated directories from git tracking"

这里的 --cached 参数是关键，它表示只把文件从索引中移除，不碰工作区文件。我试过直接 git rm -r，结果后悔了几分钟，本地缓存被删掉后重新打开项目，编辑器花了很长时间重新导入资源，虽然最终能恢复，但没必要自找麻烦。

清理之后，还要顺手做一件事：检查仓库里是否还有漏网的大文件。可以用下面的命令找出当前仓库中体积最大的文件：

bash复制git ls-files | xargs -I{} du -h {} | sort -rh | head -20

如果看到某个 assets 下的美术资源体积巨大，那是正常的；但如果看到 library 或者 build 下的文件，说明清理没彻底，再检查一下 .gitignore 的路径是否写对。

3.3 不修改 .gitignore 也能单独屏蔽文件：.git/info/exclude

有时候你会遇到这种情况：.gitignore 是团队统一管理的，不适合为了你个人本机的临时文件去改动；但你确实有一个文件不想提交，也不想让它出现在 git status 里。这时候可以用 .git/info/exclude。

这个文件位于 .git/info/ 目录下，它的语法规则和 .gitignore 完全相同，但只对当前仓库当前本地生效，不会提交到远端，不会影响其他同事。我的使用场景是：本机有一个用于调试的临时脚本，例如 assets/scripts/test_debug.ts，我不希望它被误提交，但团队其他人不需要这个文件，所以我直接把它写进 .git/info/exclude：

bash复制assets/scripts/test_debug.ts

这样它在我的本地就是“不存在”的状态，但文件本身还在项目里。不过要提醒一句：.git/info/exclude 只对未被跟踪的文件有效，如果这个文件已经被提交过了，它还是会出现在变更列表里。对于已经被跟踪、又想让它在本地保持“永不更新”的文件，可以用：

bash复制git update-index --skip-worktree assets/scripts/test_debug.ts

这条命令的原理是告诉 Git：这个文件我已经“冻结”了，你在本地不要检查它的变更。很多 Cocos 团队用这种方式管理本地化的配置差异，比如不同开发者的 API 地址不同，又不想每次都改公共配置。但要注意，这种方式容易造成“我改了文件却看不到提交”的困惑，用之前一定要有团队约定，最好在 README 里写清楚。

3.4 团队协作时同步 .gitignore 的注意事项

多人协作时，.gitignore 不是“谁先建谁说了算”，而是需要团队达成一致的公共约定。我建议在项目初期就开一次会，把“哪些目录不提交、哪些配置必须共享”说清楚，然后把这份配置提交到仓库里。

新成员加入项目时，很多人会因为本机环境不同而修改 .gitignore，比如他用的 IDE 生成了不同命名的配置文件，就顺手加一行忽略规则。这本身没问题，但要注意：不要加太“个性化”的规则进去，否则会导致某些文件在同事那里被忽略、在另一些同事那里没被忽略，出现“代码为什么在我这没问题，在他那就报错”的诡异现象。

还有一点是关于全局配置的。有些开发者会在自己的 ~/.gitignore_global 里配置一套全局忽略规则，比如忽略所有 .DS_Store，这没问题。但 Cocos 项目里的 library、temp、build 是项目特有的，必须写在项目级 .gitignore 里，不能依赖全局配置，因为每个队友的全局配置不一定一样。

4. 常见问题与排查技巧实录

4.1 明明写了 ignore，文件还是被提交了

这个问题我遇到不下十次。最常见的原因是：该文件在加入 .gitignore 之前就已经被 Git 跟踪了。Git 的规则是“先来后到”，一旦一个文件被跟踪，后续的 .gitignore 规则对它是无效的，只能先执行 git rm --cached 把它从索引里移除。

排查方法很简单：

bash复制git ls-files | grep library

如果输出里有 library 相关的文件，就说明它还在被跟踪，需要清理。第二个常见原因是大小写问题，比如你把规则写成 Library/，但实际目录名是小写 library/；Git 对路径大小写非常敏感，特别是在 Linux 和 macOS 上。第三个原因是在规则的末尾加了 / 导致匹配方式变化，或者路径写错了层级。遇到问题的时候，可以用这个命令检查 Git 到底是怎么解释忽略规则的：

bash复制git check-ignore -v path/to/your/file

这个命令会告诉你具体是哪一条规则匹配了这个文件，以及规则来自哪个文件，排查效率会高很多。

4.2 协作者拉下仓库后场景丢失、组件引用异常

这是一个和 .gitignore 本身无关、但常常被误会的坑。项目协作者拉完代码，打开场景发现预制体上的组件引用失效，或者脚本显示缺少，很多人第一时间怀疑“是不是 .gitignore 把 meta 文件忽略了”。

Cocos Creator 的每个资源旁边都有一个同名 .meta 文件，里面记录了资源的 UUID、导入选项等关键信息。只要这个项目的任何脚本、场景、预制体涉及资源引用，就必须提交 .meta 文件。我见过有人为了“让目录更干净”，在 .gitignore 里写了 *.meta，结果项目瞬间报废，所有资源引用全部断裂。

正确的做法是：.meta 文件必须全部提交，绝不忽略。检查方法是执行：

bash复制git ls-files | grep -c ".meta$"

看看数量是否和 assets 中的资源数匹配。如果发现大量资源没有对应的 meta 文件被提交，基本就是某个版本的 .gitignore 或者清理操作误删了 meta。恢复的方式是让持有正确 meta 文件的人重新提交，不要依赖编辑器自动重建，因为重建的 UUID 会变，已经存在的场景引用会全部失效。

4.3 Cocos Creator 2.4.x 构建相关配置的版本管理边界

Cocos Creator 2.4.x 的构建配置通常涉及两处：一个是你每次点构建时面板里的选项，如包名、屏幕方向、初始场景；另一个是 settings 目录下的项目级配置。版本管理的边界在于：可共享的配置要提交，机器相关的配置要忽略。

有些团队为了统一构建配置，会把 settings 提交到仓库里，这样队友拉下来后，构建面板里的选项会保持一致。但如果里面某个文件记录了本机 SDK 的绝对路径，则会导致不同开发者构建时互相覆盖路径。我建议提交前先打开 settings 目录检查一遍，看是否存在绝对路径，有的话应该在 .gitignore 里单独屏蔽那个文件，或者用变量替代。

另外还有一类常见需求是自定义启动页和 Logo 展示。很多团队会通过 build-templates 定制启动页面，或者在构建配置里调整启动图片、Logo 相关的开关。这里要注意：build-templates 属于源码，必须提交；而最终生成到 build/ 目录里的页面和模板文件，属于构建产物，不该提交。我发现不少人把这两个搞混，把 build-templates 加进了 .gitignore，结果队友拉下来后构建时模板文件缺失，打包出来的包体完全不是预期效果。Cocos Creator 2.4.x 中，这类定制模板的入口在项目根目录的 build-templates 文件夹下，如果你在构建面板调整过启动 Logo 相关选项，对应的修改要么在 settings 设置里，要么在 build-templates 里，搞清楚各自的提交策略，团队协作才会顺畅。

4.4 补充：AI 辅助生成 .gitignore 时要注意什么

现在很多同学习惯让 AI 帮忙写配置或代码，比如“用 TypeScript 获取节点子对象个数”这种片段，AI 可以秒出结果。用 AI 生成 .gitignore 也一样，但这里有一个明显的坑：Cocos Creator 版本不同，目录结构差异非常大，2.4.x 和 3.x 的缓存目录、配置文件位置都不完全一样。

如果你直接让 AI 生成“Cocos Creator 的 .gitignore”，它给的可能是最新 3.x 的模板，里面会有 temp/、library/ 这样的通用项，但可能缺少 2.4.x 特有的 profiles/、.creator/ 目录。所以我建议把 AI 当成辅助，生成之后对照项目实际目录结构一条条核对，重点看 build、native、library 这类体积大户是否都被覆盖到。

同理，AI 辅助写脚本也可能存在类似问题，比如获取子对象个数的代码在 2.4.x 里通常是 this.node.children.length，但在某些旧版本或特殊组件里还有别的写法。AI 工具可以帮你减少重复劳动，但最终还是要靠人来做版本判断和结果验证，尤其是在团队协作相关的配置上，稳定比效率更重要。

我个人在实际操作中的体会是：.gitignore 是一件“前期越省事，后期越麻烦”的事。踩过几次坑之后，我现在的新项目流程基本固定了——项目创建完的第一件事不是写第一个场景，而是把 .gitignore 确认好，在 git init 之后立刻查看一次 git status，确认没有生成目录被跟踪，然后才让团队开始往仓库里推内容。最后再分享一个小技巧：如果你发现仓库体积又开始变大，先别急着怀疑美术资源，第一件事就是跑一下 git ls-files | grep -E "library|temp|build|local"，这个命令能帮你快速定位 90% 的仓库膨胀问题。版本管理这件事，把基础规则定明白了，后续开发才能真正省心。