要我先说一个很多人没意识到的事实绝大多数 Cocos Creator 项目的“仓库事故”不是代码写崩了而是把library/、temp/这种编辑器自动生成的目录塞进了 Git。CocosCreator 3.8.x 项目的.gitignore文件看起来只是几行路径但它决定了你的仓库是清爽耐看还是每天打开都有几十个莫名其妙的改动。我在这篇文章里给出的.gitignore文件内容是以 3.8.x 从新建工程、日常开发到构建打包的完整链路为基准整理的适合游戏客户端开发者、和美术策划协作的程序员也适合那些刚接触 Cocos Creator 3.8、还没养成版本控制习惯的新人。下面先讲清楚哪些目录该进仓库再给文件内容最后把“修改了 .gitignore 不生效”这类高频问题一次说透。1. 先分清楚Cocos Creator 3.8.x 项目里到底哪些目录需要进 Git1.1 assets/ 是仓库主干.gitignore 绝不能把它忽略Cocos Creator 3.8.x 项目里最不能动的东西就是assets/目录。场景、预制体、脚本、美术、音频、图集、动画所有需要团队成员共享的资源都在这一个目录下。.gitignore里如果写上assets/等于把整个项目的灵魂挡在版本库之外其他成员拉下来只能得到一份空壳工程编辑器里什么都打不开。这个道理看起来简单但我在实际维护项目时真的见过有人为了“让仓库变小”把 assets 做了忽略结果美术资源全部丢失只能靠本地备份恢复。更值得注意的是一类容易被误伤的文件.meta文件。Cocos Creator 3.8.x 在导入每个资源时都会生成一个同名.meta文件里面保存资源的 uuid 和导入选项。比如一个player.png旁边一定会有一个player.png.meta。预制体引用图片、脚本挂载组件靠的都是这个 uuid。一旦.meta缺失或者被错误修改引用的资源就会显示为缺失。所以.gitignore里绝对不能出现*.meta这个模式assets 下所有文件都应该原样提交。1.2 settings/ 与 package.json建议提交但要清楚里面有什么Cocos Creator 3.8.x 的项目根目录下有一个settings/文件夹里面保存的是项目级设置比如模块配置、物理引擎选择、屏幕适配方案、构建选项等。这类设置属于“团队应该保持一致”的内容我建议纳入版本控制。否则每个成员打开项目时都会用自己的本地设置最后构建出来的产物可能各不相同排查问题时会非常痛苦。package.json也应当提交它记录的是项目描述、扩展依赖、脚本命令等信息和 Node 生态里的语义一致。如果你在项目里使用了扩展插件extensions/目录下的源代码和插件配置也应提交但扩展安装时拉下来的依赖文件比如node_modules/不需要进库应该在.gitignore里明确排除。这里有个容易混淆的地方项目根目录下的profiles/不属于项目设置它存的是编辑器布局、面板位置等个人偏好团队提交它没有意义反而容易产生无意义的 diff建议忽略。1.3 library/、temp/、local/典型的“机器产物目录”Cocos Creator 3.8.x 打开项目后会自动生成library/、temp/、local/这三个目录它们共同的特点是“编辑器自动维护随时可以重建”。library/是资源导入后的缓存库。你放入 assets 的图片、模型、音频编辑器会把它们导入并生成对应的缓存数据放在这里。每次启动编辑器、切换分支、改变插件状态library 都可能发生变化。temp/是编辑器运行时的临时数据包含各种中间文件和编译缓存。local/则存放本机会话信息比如最近打开的文件记录、编辑器布局偏好。这三个目录放进 Git 会带来典型的“无意义波动”明明没人改任何代码仓库里却出现几百个文件变化合并分支时成片冲突都集中在 library 下的 JSON 文件里而且这些冲突手工解决完全没有价值因为重新打开编辑器就全变了。正确的做法是全部忽略让每个成员在本地自行生成。1.4 build/ 与 native/构建产物和原生工程生成目录构建相关的内容是 3.8.x 项目里另一块需要严格隔离的区域。build/目录存放的是网页端或桌面端的构建产物native/目录则是构建原生平台Android、iOS、Windows、Mac时自动生成的完整原生工程。这两者都属于“由构建流程产出的文件”不是源文件也不该被当作代码来维护。提交构建产物的问题很直观归档体积大、二进制文件多、每次构建都会整体变化而且构建结果和编辑器版本、平台环境强绑定。哪怕你只是换了一台机器重新构建产物都可能和上次不一致。合理的方案是只保留构建配置产出物交给 CI 流程或发布分支去管理。原生开发中如果团队需要在native/下维护自定义代码正确做法是单独建一个原生源码工程而不是让生成目录成为团队版本的源头。2. 可直接复制的 .gitignore 内容以及每条规则背后的逻辑2.1 完整文件内容下面这份.gitignore文件我以 Cocos Creator 3.8.x 默认工程结构为基准去掉注释大概就是最终落地文件。你可以直接复制到项目根目录# 系统级杂项 .DS_Store Thumbs.db *.log *.tmp # Cocos Creator 自动生成的资源库 library/ # 编辑器临时数据 temp/ # 编辑器本地会话配置 local/ # 编辑器个人设置 profiles/ .creator/ # 构建产物 build/ # 原生构建生成的中间工程 native/ # 扩展插件安装的依赖 node_modules/ # 备份文件 bak/注意这份文件默认忽略的是“不需要进仓库”的内容而不是“有效文件”。把它放进仓库之后团队成员拉取项目Cocos Creator 3.8.x 依然会自动生成 library、temp、local 等目录并不影响任何正常开发流程。2.2 逐条解释每条规则到底在挡什么用一张表来看更清晰规则作用背后的原因.DS_Store、Thumbs.db屏蔽操作系统生成的隐藏文件这类文件只在本机有意义提交后只会制造无意义的 diff*.log、*.tmp屏蔽日志和临时文件编辑器、构建过程偶尔会产出但都不需要长期保存library/忽略资源导入缓存库编辑器启动时自动重建和本机环境强相关temp/忽略临时数据中间态数据随时可丢弃local/忽略本机会话设置属于个人环境不是团队共享信息profiles/、.creator/忽略编辑器个人布局和偏好不同成员的界面习惯不同提交会导致冲突build/忽略页端构建产物构建产物应由构建流程生成不应做手工版本管理native/忽略原生构建中间工程原生平台工程文件巨大且随构建更新node_modules/忽略扩展依赖可通过package.json重新安装bak/忽略临时备份目录防止有人把备份文件顺手提交进仓库这里有一个值得展开的细节为什么library/、temp/这些目录名后面都带斜杠斜杠表示只匹配目录不匹配同名文件。如果写library不带斜杠那么任何名为 library 的文件或目录都会被忽略范围过宽容易误伤。加了斜杠后匹配逻辑更精确也更符合直觉。2.3 两个极端动作忽略 *.meta 和整个 assets 都是高危操作围绕.gitignore的配置有个最基本的红线*.meta不能忽略。前面提过.meta文件里存放资源 uuid 和导入配置是 Cocos Creator 3.8.x 资源引用体系的地基。有人觉得.meta文件多且小忽略掉可以让仓库更“干净”但后果是其他人拉下项目后所有资源关联断裂场景加载直接报错美术资源全部需要重新导入和引用损失很难估算。另一个极端动作是忽略整个assets/这基本等于把一个 Cocos 项目最核心的部分拒之门外。我见过少数新手会为了节省仓库空间而这样做他们通常随后就会发现资源无法共享预制体无法协作最后只能灰溜溜地把规则删掉。维护 Cocos Creator 3.8.x 项目正确的心态是把assets/当作不可妥协的资产把生成目录当作可随时抛弃的垃圾这两者之间的边界就是.gitignore存在的意义。3. 修改 .gitignore 之后不生效这三个原因基本覆盖了 90% 的现场3.1 要忽略的文件其实已经被 Git 跟踪了.gitignore文件里有一个最容易被人忽略的底层机制它只影响“未被 Git 跟踪的文件”对“已经跟踪的文件”完全不起作用。换句话说如果你之前把library/提交过现在才在.gitignore里加上library/这个新规则并不会让 Git 自动停止跟踪它。Git 依然会显示library/下的修改因为你已经把它纳入了版本库的对象模型。判断一个文件是否已被跟踪可以先执行git ls-files library/ | head -n 20如果命令输出了一串路径说明library/里的文件还在 Git 的索引中。再配合git status查看状态就会发现这些文件仍然是“已跟踪”状态和.gitignore无关。此时你需要在.gitignore规则生效之前手动把这些文件从 Git 的索引中移除。3.2 用 git rm --cached 把已跟踪文件移出索引而不是直接删文件处理已经跟踪的生成目录标准操作是git rm --cached。它做的事情是从 Git 索引中移除文件记录但保留本地工作区的文件。比如git rm -r --cached library/ git rm -r --cached temp/ git rm -r --cached local/ git rm -r --cached build/ git add . git commit -m chore: 移除已被 Git 跟踪的生成目录这组命令执行完后工作区里的library/等文件夹都还在编辑器打开项目后照样能正常生成内容但 Git 不再把它们作为版本对象追踪。新克隆仓库的成员也不会再看到这些目录被提交的记录。实际操作中我建议分两步走先确认.gitignore已经加上对应规则再做git rm --cached否则下次git add .时这些目录又会被重新加入索引。这里还有个容易踩的坑git rm --cached之后如果你直接提交其他人拉取更新时会看到这些被移除的目录变成“删除”状态这是预期的。如果你不希望删除记录出现在大家的仓库历史里就需要和团队沟通好约定一次专门的清理提交。3.3 模式写错了斜杠差异、大小写、以及子目录 .gitignore 的生效范围.gitignore改完不生效的第二类常见原因是模式本身写得有问题。先说斜杠。文件里的build/表示匹配任意层级下名为 build 的目录而/build/只匹配根目录下的 build。如果你把构建输出目录改到了build/xxx之外比如release/web-mobile而规则只写了/build/必然不会生效。团队项目里我倾向于写不带前导斜杠的宽匹配因为生成目录通常分布在多个层级。再说大小写。Git 的路径匹配区分大小写而 Cocos Creator 3.8.x 生成的目录名基本都是小写。如果在.gitignore里误写了Library/那真正的小写library/就不会被忽略。Windows 和 macOS 的默认文件系统不区分大小写容易让你产生“反正大小写无所谓”的错觉一旦换到 Linux 环境立即暴雷。还有多层.gitignore的问题。.gitignore是支持嵌套的子目录里的.gitignore只会影响该子目录及其下级。如果你把规则写在assets/下的某个.gitignore里它管不到项目根目录的library/。排查不生效问题时先确认规则写在了哪个层级再确认该层级是否真的会被 Git 读取。3.4 只想在本地临时忽略不想动团队规则用 .git/info/exclude有些情况下你并不想把规则写进团队的.gitignore比如只是本机多了一个文件夹或者你想临时忽略某个文件而不打扰别人。这时候可以用.git/info/exclude它的语法和.gitignore完全一致但它只对当前仓库当前机器生效不会进入版本控制。# 编辑本地仓库排除文件 .git/info/exclude比如你的工作目录里有个只在本机存在的local_backup/写了.git/info/exclude后Git status 就会对它视而不见。这个方法很适合个人临时使用但不要拿它替代团队的公共.gitignore因为团队成员各自维护一份本地排除文件很快就会失控。话题顺势落到一个网上经常有人搜的问题能不能忽略未跟踪的.gitignore文件本身答案是可以比如在.git/info/exclude里写一行.gitignoreGit 就会把这个仓库的.gitignore排除在跟踪范围之外。但我不建议这样用。.gitignore文件是团队协作的基础约定它应该被提交、被评审、被统一维护。如果一份规则只存在于某台机器上那它对于团队来说等于不存在。真正需要保留本地盘设置时用.git/info/exclude或git update-index --skip-worktree会更合适。4. 让 .gitignore 真正服务于团队的几个配套习惯4.1 .meta 文件的合并底线冲突时不要轻易选“our”或“their”团队协作里.meta文件会被多人同时修改尤其是预制体和场景文件。一旦合并冲突Git 会让你选择保留哪个版本很多人图快就选了ours或者theirs。但这种处理方式风险很高.meta里的 uuid 如果被覆盖另一个分支上引用它的资源就会失效。正确的做法是打开冲突文件优先确认 uuid 字段是否变化如果 uuid 没变只是导入参数不同那就逐个字段合并如果 uuid 真的变了需要同步检查整个项目里还有哪些资源引用旧 uuid。我在项目里给团队定过一个底线.meta文件冲突时不许用git checkout --ours这种粗暴操作必须人工确认后再合。宁愿多花五分钟也别为了一时痛快制造一批“显示为丢失”的资源。4.2 构建产物不要进开发分支有需要就单独开 release 分支.gitignore里忽略build/意味着构建成果不进开发仓库但这不代表你不需要保存构建产物。常规做法是搭建 CI/CD 流水线把构建产物上传到对象存储或独立的附件平台没有 CI 条件的小团队也可以把产物放在独立的 release 分支或者单独建一个存放二进制的仓库。这里的关键思想是开发分支保持“源码可运行状态”任何机器拉下来都能通过编辑器直接进入开发构建产物是临时的、可再生的它们只服务发布环节。这样做之后Git 仓库体积会明显减小成员拉取速度更快合代码时的噪音也更少。维护 3.8.x 项目两年多的经验告诉我构建物混入主仓库是仓库膨胀最快的路径之一早治理早轻松。4.3 全局忽略文件与团队模板两层规则各管各的除了项目里的.gitignoreGit 还支持全局忽略文件通过core.excludesFile配置指向一个位于用户目录的文件。比如git config --global core.excludesFile ~/.gitignore_global这个全局文件适合放一些“任何项目都不想见到”的内容比如自己常用的编辑器临时文件、压缩包、备份目录。它和项目.gitignore互不干扰两层规则叠加使用。团队层面则应该维护一份统一的.gitignore模板。每开一个新项目直接把模板复制进去再根据项目实际目录做微调。微调时先看编辑器生成的目录结构不要凭记忆写规则。Cocos Creator 3.8.x 的构建输出位置是可以配置的如果团队有人把构建路径改到了项目根目录之外项目里的.gitignore就不需要再管它但要在文档里说清楚避免有人误以为构建产物永远不会出现在项目目录中。4.4 清理之后的再确认步骤以及我知道了重要小的血泪教训把.gitignore配置好、把已经被跟踪的生成目录移出索引之后还有一个步骤值得做重新用干净的方式验证仓库状态。做法很简单删除本地的library/、temp/、local/目录然后用 Cocos Creator 3.8.x 重新打开项目让编辑器完整导入一遍资源。此时再看git status正常情况下应该只有 assets、settings、package.json 等源码文件。多花这几分钟能确认你的.gitignore规则真的覆盖了所有生成物而不是只把当前这一份本地状态清理掉。按我自己的经验最稳妥的做法是在项目创建当天就把.gitignore放进去。这个文件虽然叫“仅供参考”但它对团队效率的影响一点也不小。我之前接手过一个已经跑了大半年的项目仓库里积累了上万条 library 相关的提交记录清理起来费了很大力气。现在每次新建 Cocos Creator 3.8.x 工程我都会第一件事把这份规则放进去然后在编辑器完成首次导入后再确认一遍状态。这用不了几分钟但换来了后面几个月甚至更久不被打扰的开发节奏。