Cocos Creator项目目录结构详解：从核心文件夹到团队协作规范

1. 项目概述：为什么目录结构是项目的基石

刚接触Cocos Creator，尤其是从其他引擎（比如Unity）或者前端框架（比如Vue）转过来的朋友，打开项目文件夹的第一眼，可能会有点懵。assets、settings、packages、build……这些文件夹都是干嘛的？为什么我的脚本要放在assets下面？为什么打包出来的东西在build里，而它又好像不能提交到代码仓库？如果你曾有过这些疑问，或者你希望自己的项目从一开始就有一个清晰、可维护的“家”，那么理解Cocos Creator的项目目录结构，就是你必须要迈出的第一步。

这不仅仅是一个“说明书”式的罗列。一个良好的目录结构，直接决定了团队协作的效率、资源管理的清晰度、版本控制的友好性，以及项目长期迭代的可维护性。它就像建筑的蓝图，代码的交通规则。混乱的目录会导致资源重复、依赖丢失、构建失败，以及新成员上手时无尽的“踩坑”时间。相反，一个规划得当的目录，能让你的开发过程行云流水，无论是添加新功能、定位BUG，还是进行资源优化，都能事半功倍。

本文将基于Cocos Creator 3.x版本，为你彻底拆解默认项目目录的每一个角落，并结合实际开发中积累的经验，分享如何在此基础上，构建一套适合中大型项目、团队协作的目录规范。我们会从“是什么”深入到“为什么”，并给出“怎么做”的具体建议，让你不仅能看懂目录，更能用好目录。

2. 核心目录深度解析：从默认结构到设计意图

当你通过Dashboard新建一个空白项目后，在资源管理器中打开项目根目录，你会看到类似下图的结构。我们逐一拆解，并理解Cocos Creator这样设计的深层逻辑。

MyCocosProject/ ├── assets/ ├── library/ ├── local/ ├── packages/ ├── settings/ ├── temp/ ├── build/ ├── creator.d.ts └── package.json

2.1/assets：你的创意与逻辑仓库

这是整个项目的核心，也是你作为开发者最常打交道的文件夹。所有需要被引擎识别、管理和使用的资源，都必须放在这个目录或其子目录下。

设计意图：assets目录是Cocos Creator资源系统的入口。引擎会监控这个文件夹下的所有变化（增删改），并自动导入、处理资源，生成对应的meta文件（存储资源的导入设置和UUID）。它保证了资源管理的统一性和实时性。

必须放在assets下的内容：

• 场景（.scene）：游戏关卡、UI界面等。
• 预制体（.prefab）：可复用的节点模板。
• 脚本（.ts/.js）：所有的TypeScript/JavaScript脚本。
• 静态资源：图片（.png, .jpg）、声音（.mp3, .wav）、字体（.ttf）、Spine骨骼动画（.json, .atlas）、粒子文件等。
• 配置数据：JSON、文本文件等。

重要提示：任何你希望出现在Cocos Creator资源管理器面板中的文件，都必须位于assets目录下。直接放在项目根目录或其他非assets目录的文件，引擎将无法识别和管理。

关于assets目录的组织：引擎本身没有强制规定子目录结构，但这恰恰是体现项目架构水平的地方。一个混乱的assets（比如所有图片、场景、脚本都扔在根目录）是灾难的开始。我们会在第4章详细探讨如何科学地规划它。

2.2/library与/local：引擎的“后台”与本地缓存

这两个目录通常不需要手动操作，也绝对不能提交到版本控制系统（如Git）。

• /library：这是引擎根据assets目录下的资源生成的本地资源库。你可以把它理解为一个“编译后”的缓存和数据库。里面存储了资源导入后的中间格式、序列化后的场景数据、脚本编译后的信息等。当你在编辑器中修改资源并保存时，引擎会更新这个目录。

  • 为什么不能提交？因为它完全由assets目录的内容衍生而来，且可能因操作系统、引擎版本、甚至本地路径不同而不同。提交它毫无意义，且会导致团队成员之间的冲突。
  • 什么时候可以删除？当遇到一些诡异的资源引用错误、编辑器显示异常时，可以尝试关闭编辑器，删除整个library文件夹，然后重新打开项目。引擎会基于assets重新生成它，这能解决很多缓存导致的玄学问题。

• /local：存储项目的本地设置。例如，每个编辑器窗口的面板布局、你最近打开的文件、编辑器的一些个性化配置等。这些设置只对你本地生效。

  • 为什么不能提交？这是纯粹的个性化数据，提交它会强制覆盖团队其他成员的编辑器布局和习惯，造成困扰。

2.3/packages：扩展项目的功能模块

这个目录用于存放项目依赖的自定义扩展包或从Cocos Store安装的插件。

• 自定义扩展包：如果你自己开发了一个可复用的功能模块（比如一套通用的UI组件、一个网络管理模块），可以将其制作成一个扩展包，放在packages目录下。这样，它就能被项目引用，并且便于在不同项目间共享。
• Store插件：从Cocos官方资产商店安装的插件，也会被放置在这里。
• 与package.json的关系：项目根目录的package.json定义了项目的基础npm依赖（更多用于构建层面）。而packages文件夹内的每个子包，通常也有自己的package.json，用于管理该扩展包自身的依赖。

实操心得：对于中小型项目，你可能暂时用不到自定义扩展包。但当你发现某些功能（如音频管理器、配置加载器）在多个项目中重复开发时，就应该考虑将其抽离成扩展包，放入packages。这能极大提升代码的复用性和项目结构的清晰度。

2.4/settings与/temp：项目配置与临时空间

• /settings：存放项目的全局配置。这些设置是项目级别的，需要纳入版本控制，以确保所有团队成员有一致的开发环境。

  • settings/builder.json: 不同平台（如Web Mobile, Android, iOS）的构建配置。
  • settings/project.json: 项目基础设置，如默认场景、目标平台、模块裁剪设置等。
  • settings/settings.json: 项目相关的其他编辑器设置。
  • 必须提交：这个文件夹下的配置，定义了项目的构建和行为，必须提交到版本库。

• /temp：编辑器运行时的临时文件目录。用于存储编译过程中的临时文件、日志等。可以随时安全删除，编辑器会在需要时重新创建。

  • 绝对不能提交。

2.5/build与 根目录文件

• /build：构建输出目录。当你点击“构建”按钮后，生成的用于发布到各平台（如Web、Android APK、iOS Xcode工程）的代码和资源都会放在这里。每次构建，该目录下对应平台的文件夹会被清空并重新生成。

  • 为什么不能提交？构建产物是派生文件，体积巨大，且完全由源码和资源生成。提交它只会污染版本库。
  • 常见问题：有时构建后出现白屏或资源加载错误，可以尝试清除build目录并重新构建，以排除缓存问题。

• package.json：这是Node.js项目的标准配置文件，在Cocos Creator中主要用于：

  1. 声明项目名称、版本、描述。
  2. 管理项目依赖的npm包（例如一些用于构建过程的工具链插件）。
  3. 定义构建脚本（scripts字段）。
  • 必须提交。

• creator.d.ts：TypeScript的类型定义文件。它提供了Cocos Creator引擎所有API的TypeScript类型提示，是你在编写.ts脚本时获得智能补全和类型检查的基础。引擎在创建项目或升级时会自动维护这个文件。

  • 建议提交，以确保团队成员有一致的类型提示。

3. 构建高效的项目资源组织规范

理解了默认结构后，我们需要在assets目录内建立一套清晰的“子目录法”，这是项目可维护性的关键。以下是一种经过大量项目验证的、层次清晰的目录组织方案，你可以根据项目规模进行调整。

assets/ ├── [1_Scenes]/ # H2.1 场景：按功能模块划分 │ ├── 0_Entry/ # 启动、加载场景 │ ├── 1_Login/ # 登录注册场景 │ ├── 2_Main/ # 主城/主界面场景 │ ├── 3_Battle/ # 战斗场景 │ └── 9_Demo/ # 示例、测试场景 ├── [2_Prefabs]/ # H2.2 预制体：按实体类型划分 │ ├── UI/ # UI预制体 (Button, Window, HUD) │ ├── Characters/ # 角色预制体 │ ├── Props/ # 道具、机关预制体 │ └── Effects/ # 特效预制体 ├── [3_Scripts]/ # H2.3 脚本：按架构分层 │ ├── Core/ # 核心框架、管理器 (GameManager, AudioManager) │ ├── Data/ # 数据模型、配置表加载 │ ├── Logic/ # 游戏逻辑 (角色控制、战斗计算) │ ├── UI/ # 界面逻辑与控制 │ └── Common/ # 通用工具类、常量、枚举 ├── [4_Resources]/ # H2.4 静态资源：按类型和用途细分 │ ├── Textures/ # 纹理图片 │ │ ├── UI/ # UI用图 (按钮图标、背景) │ │ ├── Backgrounds/ # 背景图 │ │ └── Sprites/ # 精灵、角色图 │ ├── Audio/ # 音效音乐 │ │ ├── BGM/ # 背景音乐 │ │ └── SFX/ # 音效 │ ├── Animations/ # 动画相关 (非Spine) │ ├── Fonts/ # 字体文件 │ └── Spine/ # Spine骨骼动画文件 ├── [5_Config]/ # H2.5 配置与数据 │ ├── Json/ # JSON配置表 (关卡、道具) │ └── Localization/ # 多语言文本 └── [6_External]/ # H2.6 外部原生插件/资源 (可选) └── [PlatformName]/ # 按平台存放原生代码或资源

3.1 目录命名与编号的玄机

你可能注意到了，我给顶级目录加上了[1_Scenes]这样的前缀。这不是必须的，但强烈推荐，原因如下：

1. 强制排序：资源管理器默认按字母排序。1_、2_这样的前缀能让你最重要的目录（如场景、脚本）始终排在前面，提高查找效率。
2. 逻辑分组：方括号[]让目录在视觉上成为一个清晰的组块，与子目录区分开，一目了然。
3. 团队共识：这是一种显式的约定，新成员一眼就能看懂资源组织的优先级和逻辑。

3.2 脚本目录(3_Scripts)的架构思考

脚本的组织直接反映了你的代码架构。上面示例是一种简单的分层架构：

• Core/: 放置单例模式的管理器。例如GameManager.ts（游戏总控）、AudioManager.ts（音频播放）、AssetManager.ts（自定义资源加载）等。这些是游戏的“大脑”。
• Data/: 定义数据结构和加载逻辑。例如PlayerData.ts（玩家数据模型）、ConfigLoader.ts（读取JSON配置的类）。
• Logic/: 纯粹的 gameplay 逻辑。例如PlayerController.ts（角色移动控制）、EnemyAI.ts（敌人行为树）、SkillSystem.ts（技能释放逻辑）。这部分应尽量独立，不直接依赖UI。
• UI/: 所有与界面交互相关的脚本。例如LoginView.ts、ShopPanel.ts。它们负责调用Core/中的服务，并更新界面显示。
• Common/: 存放全局常量、通用工具函数（如格式化时间、随机数生成）、自定义枚举等。

注意事项：避免在Logic脚本中直接findUI节点，也避免在UI脚本中编写复杂的游戏状态判断。通过事件系统或管理器进行通信，保持模块间的低耦合。

3.3 资源目录(4_Resources)的优化细节

纹理资源是项目体积的大头，良好的组织能方便后期进行图集打包（Auto Atlas）和压缩优化。

• 按用途细分：将UI图片和游戏内精灵图片分开。因为它们的压缩策略可能不同（UI需要保持清晰，精灵可能可以接受一定压缩）。
• 图集策略：对于大量小图（特别是UI图标），应该使用Cocos Creator的“自动图集”功能。建议为UI目录下的图标单独创建一个图集设置，为Sprites下的角色素材创建另一个。这样可以有效减少Draw Call。
• 音频管理：将背景音乐（BGM）和音效（SFX）分开。BGM通常文件较大，循环播放；SFX文件小，播放频繁。在脚本中引用时，路径清晰也便于管理。

4. 版本控制（Git）的精准配置

哪些该提交，哪些该忽略，是团队协作的命门。这里提供一个强化版的.gitignore配置，适用于Cocos Creator 3.x项目。

# Cocos Creator 3.x 核心忽略项 /library/ /local/ /temp/ /build/ /settings/launch-log.json # 启动日志，本地临时文件 # 操作系统自动生成的文件 .DS_Store Thumbs.db *.swp *.swo # 编辑器个性化文件 (VSCode, WebStorm等) .vscode/ .idea/ *.suo *.ntvs* *.njsproj *.sln *.sw? # Node.js 依赖目录 (通常使用`npm ci`或`yarn install`重新生成) node_modules/ # 构建产物和日志 *.log npm-debug.log* yarn-debug.log* yarn-error.log* # 可选：如果你将某些大资源或中间文件放在assets外，也需忽略 # external_large_assets/

必须提交的文件和目录：

• /assets(你的所有心血)
• /packages(自定义扩展包)
• /settings(项目配置)
• package.json(项目依赖)
• creator.d.ts(类型定义)
• .gitignore(忽略规则本身)
• tsconfig.json(如果有，TypeScript配置)

一个关键技巧：在项目根目录创建一个README.md文件，简要说明项目名称、运行方式（npm install后如何构建）、以及目录结构说明。把这个文件也提交上去，它能极大降低新成员的接入成本。

5. 从目录到构建：全流程实操与问题排查

理解了静态结构，我们来看看目录是如何在动态的开发流程中发挥作用的，并解决一些常见问题。

5.1 资源引用与UUID系统

当你在Cocos Creator编辑器中，将一个图片拖到场景中，或者将一个预制体拖到另一个预制体里时，编辑器并不是记录文件的路径，而是记录一个UUID（通用唯一标识符）。这个UUID就存储在对应资源的.meta文件中。

为什么用UUID而不是路径？

1. 稳定性：即使你移动了资源在assets内的位置（重命名文件夹或文件），只要.meta文件跟着一起移动，UUID不变，所有已有的引用都不会断裂。
2. 唯一性：UUID是全球唯一的，避免了重名文件导致的引用错误。

实操现场：当你从外部复制资源到assets时，一定要在操作系统的文件管理器中，将资源文件连同它的.meta文件一起复制。如果只复制了资源文件，引擎会为它生成一个新的UUID，导致所有原有引用失效，出现“粉红色丢失资源”的错误。

5.2 构建发布流程中的目录角色

点击“构建”按钮后，引擎会进行一系列操作，目录们各司其职：

1. 读取/assets和/settings：获取所有源资源和项目配置。
2. 查询/library：利用其中已处理好的中间数据，加速构建过程。
3. 使用/temp：作为编译和打包的临时工作区。
4. 输出到/build：生成最终的可发布内容。对于小游戏平台，build目录下会生成一个game.js（或game.ts编译后的代码）和资源包；对于原生平台，则会生成Xcode或Android Studio工程。

一个常见的构建问题：构建后，真机上图片显示错乱或丢失。

• 排查思路：
  1. 检查build目录下的对应平台文件夹，看图片资源是否正常存在。
  2. 检查图片资源的.meta文件，确认其uuid是否在构建后的配置文件中被正确引用。
  3. 最常见原因：图片存放路径过深或文件名包含特殊字符（中文、空格等），在某些平台（尤其是小游戏平台）的打包过程中可能出现问题。最佳实践：资源路径使用英文、数字和下划线，避免过深的嵌套。

5.3 多团队协作下的目录冲突解决

当多人使用Git同时修改项目时，可能会遇到两类目录冲突：

1. 场景/预制体文件冲突（.scene, .prefab）：这是二进制文件，无法直接合并。预防胜于治疗：建立团队规范，尽量避免多人同时编辑同一个场景或复杂预制体。如果必须协作，可以将其拆分为多个小的预制体，由不同人员负责。
2. .meta文件冲突：.meta文件是JSON文本格式，理论上可以合并，但合并风险极高，因为其中的uuid和subMetas等字段必须保持绝对正确。
   • 安全策略：在.gitignore中，通常不需要特殊处理.meta，因为它们必须被提交。当发生.meta冲突时，最安全的做法是： a. 备份自己本地有冲突的资源文件。 b. 采用“ theirs”或“ ours”策略完全接受某一方的版本（通常接受远程仓库的版本更安全）。 c. 重新打开项目，如果资源引用丢失，用备份的文件覆盖回来，让引擎重新生成正确的.meta。

我个人在实际操作中的体会是，目录结构的清晰和团队规范的明确，能减少90%以上的协作问题。花一个小时和团队统一目录命名和资源存放规范，在项目后期能节省数百个小时的沟通和排错成本。最后再分享一个小技巧：定期利用Cocos Creator编辑器菜单中的“资源管理器 -> 查找重复资源”功能，可以帮你清理assets中无意间引入的冗余文件，保持项目整洁。