企业官网建设流程全解析

要我先说一个很多人没意识到的事实：绝大多数 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 项目里到底哪些目录需要进 Git

1.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 逐条解释：每条规则到底在挡什么

用一张表来看更清晰：

这里有一个值得展开的细节：为什么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里写一行.gitignore，Git 就会把这个仓库的.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 全局忽略文件与团队模板：两层规则各管各的

除了项目里的.gitignore，Git 还支持全局忽略文件，通过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 工程，我都会第一件事把这份规则放进去，然后在编辑器完成首次导入后再确认一遍状态。这用不了几分钟，但换来了后面几个月甚至更久不被打扰的开发节奏。