做 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 的项目根目录下有这些关键内容:
| 目录/文件 | 作用 | 是否应该提交 |
|---|---|---|
assets/ |
游戏资源、脚本、场景、预制体 | 必须提交 |
library/ |
编辑器生成的资源缓存和导入数据 | 忽略 |
local/ |
本机编辑器布局、最近打开记录 | 忽略 |
temp/ |
脚本编译和构建临时文件 | 忽略 |
profiles/ |
部分本机相关配置 | 建议忽略 |
settings/ |
项目级构建设置、模块配置 | 需要甄别 |
build/ |
各平台构建产物 | 通常忽略 |
build-templates/ |
自定义构建模板 | 必须提交 |
package.json |
插件和 npm 依赖声明 | 必须提交 |
从这张表能看出,2.4.13 的仓库里,真正需要提交的其实就 assets、
