CocosCreator 2.4.13 .gitignore 配置详解：从入门到避坑

做 Cocos 项目最让人头疼的场景之一，就是同事推了一版代码上来，你拉下来一运行，编辑器直接报错，或者不同人的电脑上打开同一个项目，场景层级完全对不上。排查半天，问题往往不在 assets 里的脚本和资源，而是一个大部分人压根不会打开的文件——.gitignore。

CocosCreator 2.4.13 作为 2.x 系列的最后一个维护版本，至今仍被大量上线项目使用。它的目录结构、缓存逻辑和构建方式与 3.x 差异很大，网上一搜能找到一堆 .gitignore 模板，但很多是抄来抄去的残废版，丢了 settings，忽略了 profiles，甚至有人把 assets 一并忽略，拉完代码打开项目只剩一个空场景。所以我把在 2.4.13 上长期维护项目时沉淀下来的 .gitignore 内容整理成文，逐行说明用途，也分享几个版本控制上的实操经验。

1. 版本管理事故的常见源头：不是代码，是没配好的忽略规则

1.1 一次让团队半天无法开工的 library 目录事故

有次新同事加入项目，按教程初始化仓库后没有正确配置忽略规则，就把整个项目目录提交了。当时还没人发现，因为团队大多数人已经有了本地缓存。直到另一个同事用 Git 重新拉取后打开 CocosCreator，编辑器卡在"导入资源"界面，进度条停到 40% 不动，日志刷了一大堆 UUID 校验失败。后来发现原因很简单：新同事在首次打开编辑器时，本地 library 目录已经生成，里面存的是本机缓存过的资源元数据。他把 library 一起提交了，仓库里混入了一批带着绝对路径和本机 UUID 索引的缓存文件。其他人拉下来之后，Cocos 的资产数据库直接错乱。

这种事故在 2.4.x 里特别容易发生，因为 library 目录的默认路径就在项目根目录下，不像 3.x 那样有更明显的隔离。只要 .gitignore 没写「library/」这一行，一步操作失误就可能污染整个仓库。

1.2 2.4.13 的目录布局决定了 .gitignore 不是随便抄的

CocosCreator 2.4.13 的项目根目录下有这些关键内容：

从这张表能看出，2.4.13 的仓库里，真正需要提交的其实就 assets、settings、build-templates 和几个配置文件。但难点在于 settings 目录内部既有项目级配置，也有本机相关的内容，不能一刀切。我在下文会给出具体判断办法。

2. 逐目录拆解：哪些必须忽略，哪些千万不能加进去

2.1 temp、library、local：编辑器"影子三件套"

这三个目录是 2.4.13 里最容易混淆的。

temp 是脚本编译缓存，编辑器每次编译脚本都会往里写，属于过程产物。即使你删掉，下次打开编辑器也会自动重建。所以 temp/ 必须忽略，没有争议。

library 是资源导入缓存。第一次把一个资源放进 assets 后，编辑器会在 library 里生成对应的 .json、.meta 索引和 uuid 映射。这里有个很重要的细节：library 里的 .meta 文件和你放在 assets 里的 .meta 文件是两回事。assets 下的 .meta 是资源的重要元数据，必须提交；library 下的 .meta 是缓存索引，不能提交。很多新手分不清，看到 .meta 就以为是垃圾文件，结果把 assets 里的 .meta 也加了忽略，协作时 UUID 直接乱掉，场景引用全部丢失。

local 是编辑器自身的窗口布局、最近打开场景等本地状态。这个目录不同人之间同步毫无意义，甚至会因为界面差异导致打开项目时卡顿。忽略即可。

2.2 profiles 和 settings：机器相关与项目相关的边界

这里需要细说。

profiles 在 2.4.x 里存放的主要是构建相关的本机配置，比如选择过的构建平台、上一次的输出路径等。这部分属于个人偏好，团队之间不需要同步，建议忽略。

settings 更微妙。2.4.13 的 settings/v2/packages/ 下面会生成多个配置文件，比如 project.json、builder.json、engine.json 等。其中 builder.json 保存了构建面板里各平台的配置，包括包名、AppID、启动场景。project.json 保存了项目模块设置。这些内容属于项目级配置，换了电脑应该保持一致，否则会出现你本地构建出来的包名是 com.foo.game，到同事机器上变成 com.foo.test 这种事故。

所以我的建议是：settings/ 默认提交，不忽略。只有在明确发现某个子文件记录了本机绝对路径时，才针对性地把它加入忽略。在一份 .gitignore 里直接写 settings/ 而把整个项目设置丢掉，是我见过最糟糕的模板之一。

2.3 build 目录的取舍：从构建产物到自定义模板

build/ 目录放的是构建后的发布包，包括微信小游戏、字节跳动小游戏、原生平台工程等。这些产物理论上都能通过构建流程重新生成，不应该进仓库。但是要注意，如果你在项目根目录下放了 build-templates，那是自定义构建模板，是开发人员手工维护的，必须提交。

还有一类特殊情况：如果你的项目在 2.4.13 上做了原生插件集成，比如接入了某个 SDK，需要对原生工程做少量改动，有人会把 build/android 下的原生工程直接提交。我不推荐这种做法，因为 build 目录随时可能被覆盖，正确做法是把改动挪到 build-templates 中，通过模板方式让每次构建自动带上这些改动。

2.4 assets、package.json 等核心内容为什么必须提交

assets/ 是整个项目的灵魂，不提交等着丢资源吗？但有些 AI 生成的 .gitignore 会犯一个可怕的错误：因为 assets 被某种模板里的「静态资源目录」关键词匹配到，把它一并忽略了。如果你发现仓库里没有 .png、.prefab、.scene 文件，立刻检查忽略规则是否把 assets 拉下了水。

.meta 文件必须提交，这是 Cocos 资源引用关系的核心。还有 package.json，如果项目装了 npm 插件或者使用了某些命令行构建脚本，这个文件必须入库。

3. 一份带注释的 CocosCreator 2.4.13 .gitignore 完整配置

3.1 实际配置全文

下面这份配置是我在线上项目里用了挺久的内容，适用于 2.4.13，也基本兼容 2.4.x 全系列：

gitignore复制# 编辑器缓存与临时产物
library/
local/
temp/

# 构建产物
build/
native/

# 本机构建配置
profiles/

# 日志
*.log
logs/

# Node 依赖
node_modules/

# IDE 个人配置
.idea/
.vscode/
*.swp
*.swo
.attach_pid*

# 操作系统文件
.DS_Store
Thumbs.db
Desktop.ini

# 单元测试与覆盖率
coverage/

# Cocos 编辑器自动生成的备份
*.backup
backup/

注意，我没有写 settings/。这个目录建议保留在仓库中，原因前面已经说过了。如果你团队里确有某台机器的 settings 出现了本机路径，可以单独对特殊文件做忽略：

gitignore复制# 仅在出现本机绝对路径时添加
settings/v2/packages/*.local.json

3.2 针对不同 OS 和编辑器的补充项

如果你的团队里有人用 macOS，.DS_Store 不写的话，Finder 生成的垃圾文件会混进仓库，虽然不致命但很烦。Windows 上 Thumbs.db 和 Desktop.ini 同理。

如果你用 VS Code，.vscode/ 目录我建议忽略，但不是必须。因为团队里每个人的调试配置、插件推荐可能不同，强制同步反而增加冲突。如果确实需要共享调试配置，可以用一个名为 .vscode/extensions.json 的文件来声明推荐插件，然后把其他部分忽略。CLion 或 Visual Studio 用户就需要分别补充 .idea/、*.suo 等规则。

3.3 配置完怎么验证：两条命令 + 一个误区

配好 .gitignore 后，先在项目根目录执行查看忽略状态：

bash复制git status

如果某个被忽略的目录还出现在未跟踪列表里，说明它之前已经被 git add 过，或者它的内容已经进了索引。不要急，先看是否已经被跟踪：

bash复制git ls-files library/ | head

如果这命令输出了文件路径，说明 library 已经被 Git 跟踪，此时 .gitignore 对它不生效。解决办法：

bash复制git rm -r --cached library/

--cached 只从索引中移除，不删除本地文件。很多人一上来就 git rm -r library/，把同事的本地缓存目录整个删掉，这是另一个灾难。

4. 多人协作、CI/CD 和 AI 辅助开发下的 .gitignore 进阶实操

4.1 ".gitignore 不生效"的真正原因

.gitignore 不生效，99% 是因为对应的目录或文件已经被 Git 跟踪过。Git 的忽略规则只对未跟踪文件生效，一旦文件进了版本库，后面再写忽略规则就晚了。

这个情况常发生在项目初期：团队一开始没配 .gitignore，把所有文件都提交了，后面再补规则，发现怎么加都不管用。处理方式就是用 git rm -r --cached 把目标从索引中移除，提交这次变更，之后再看效果。注意团队其他人拉取时，Git 会认为这些文件被删除，但 --cached 不会删本地内容，所以实际效果只是"停止跟踪"，并不影响本地文件存在。

4.2 团队分支模型和构建机上的 .gitignore 差异

如果你的团队使用 release 分支直接从仓库构建发布包，那 CI 机器上 build/ 的忽略规则和本机没有区别，CI 会自己创建构建目录。但在 2.4.13 上跑命令行构建时会自动生成 build 目录，所以 CI 工作区里同样不需要提交这个目录。

有一点需要特别提醒：如果 CI 脚本里执行了 git clean -fdx（删除所有未跟踪文件），但 .gitignore 漏配了某些编辑器生成目录，会导致每次构建前都做一次全量资源导入，构建时间从 3 分钟变成 15 分钟。我习惯在 CI 脚本里先跑一遍：

bash复制git clean -ndx

-n 是 dry-run，先看看会被删掉哪些文件，确认忽略了 library、temp、local 之后再移除 -n 真正执行。

4.3 AI 生成代码后，版本管理里新增的坑

现在很多团队已经用 AI 辅助写 Cocos 脚本，比如生成自定义组件、编辑场景 JSON、写构建插件。AI 代码入驻项目后，出现了一些以前没有注意过的问题。

最常见的是 AI 生成的临时文件被放在项目根目录或 assets/ 下。比如某些 AI 工具会在当前目录生成 .bak、.tmp、output/ 之类的文件。我遇到过一个项目，AI 补全脚本时自动生成了一份 project.bak/project.json，结果 Cocos 编辑器把它当成了第二个项目配置，导致各个开发者打开后看到的场景不一致。版本控制层面，我在 .gitignore 里加了这几行：

gitignore复制# AI 工具生成的临时目录
.ai/
*.bak
*.tmp
ai_generated/

更重要的一点：AI 写的代码里经常出现路径拼接，如果在本地用绝对路径测试过，生成的文件可能记录了 C:/Users/xxx/Documents/... 这样的内容。我在 Code Review 时一旦看到这种路径，会直接要求改成 editor 内置变量或相对路径。

4.4 关于启动画面与 Logo 配置同步的一次小提醒

2.4.13 时代有一个大家初期容易忽略的点：构建时项目设置里的启动画面和 Cocos 相关标识开关，很多配置都存放在 settings/v2/packages/builder.json 里。如果团队把 settings/ 整个忽略掉，那么每台机器构建出来的小游戏包，启动画面和标识相关配置都会回到默认状态。

有团队当时为了图省事，只提交 assets，结果换台电脑构建后，原本自定义的启动文案没了，美术同学一度以为资源丢失。实际上资源都在，只是 builder.json 没有同步。现在的 2.4.13 的构建设置项中，切换"是否使用默认启动界面"这类选项后，配置会写回 settings。所以，如果你们对启动画面有要求，一定保留 settings/ 在仓库里，并且别把这几个文件加入忽略规则。

5. 维护了快三年 2.4.x 项目之后的 .gitignore 建议

5.1 保持忽略规则的"最小必要"原则

我见过一种反面写法，是从某个大项目里复制过来，几百行忽略规则，涵盖了各种不可能用到的目录。忽略规则写得越多，误伤风险越大。你根本分不清哪条规则把某个新的资源目录给屏蔽了。.gitignore 应该遵循最小必要原则：只忽略确实不需要跟踪、且会反复生成的内容。

5.2 每次升级引擎小版本后，检查一次忽略规则

就算你的项目停留在 2.4.13 不升级，团队里如果有人使用 Cocos Dashboard 更换过版本，编辑器可能生成新的缓存目录，比如 profiles/v2 在不同版本间结构不同。我每次调整构建配置后，都会用 git status 看一眼有没有莫名新增的目录，有则判断是否忽略，没有就继续。

5.3 个人长期使用的一条补充经验

最后分享一条偏个人的习惯：在 .gitignore 头部写一段简短注释说明这个仓库适用的引擎版本和是否保留 settings/，比如：

gitignore复制# CocosCreator 2.4.13 - 保留 settings/ 提交

这个注释看起来简单，但在团队新人加入、或半年后你自己回来看这份文件时，能少踩很多坑。版本控制的意义不在于把规则写得多全，而在于后看你写的规则时，能一眼想明白当时为什么把某类文件排除在外。