《Cocos 游戏开发入门》附录 B：Cocos Creator 3.8 工程结构与 cc.d.ts 速查

附录 B：Cocos Creator 3.8 工程结构与 cc.d.ts 速查

附录 A 讲的是 mini2d——一套你能完整读懂的纯 TypeScript 运行时。本附录讲它的对照物：Cocos Creator 3.8.8 工程。它的很多文件由 GUI 编辑器生成和维护，命令行里既不能创建也不能运行，所以本附录的作用是把「打开工程会看到什么」讲清楚，并给出唯一能离线复现的一环——用 @cocos/creator-types 做类型检查。

先记住本附录最重要的一句话：工程文件与场景必须用 Cocos Creator 3.8 编辑器打开，命令行不可复现；能离线做的只有类型检查与结构阅读。 下面凡涉及 .scene / .prefab / .meta / settings 的代码块，都会再标注一次。

B.1 顶层目录一览

一个新建的 Cocos Creator 3.8 工程，顶层大致长这样：

一条贯穿始终的规则：你只在 assets/ 里创作，其余目录都是编辑器或构建系统的地盘。 这也是它和 mini2d 最大的区别——mini2d 里每个文件都是你手写的，Cocos 工程里大部分文件你只读不写。

B.2 assets/：唯一的源目录

assets/ 下每一个资源文件旁边都会有一个同名的 .meta 文件。它们成对出现：

assets/
├── scenes/
│   ├── main.scene
│   └── main.scene.meta
├── prefabs/
│   ├── coin.prefab
│   └── coin.prefab.meta
├── scripts/
│   ├── PlayerControl.ts
│   └── PlayerControl.ts.meta
└── textures/
    ├── player.png
    └── player.png.meta

不同扩展名对应不同的资源类型与导入设置，速查如下：

.meta 是编辑器给每个资源分配的稳定标识与导入设置：里面存着该资源的 UUID、导入参数（比如纹理的压缩格式、是否为图集）、以及它在资源库中的位置。它的作用是让「资源改名 / 移动位置」不会打断已有的引用——场景里引用的是 UUID，不是路径。

以下片段需 Cocos Creator 3.8 编辑器打开，本节不可命令行复现：

{
  "ver": "1.0.0",
  "uuid": "a1b2c3d4-0000-4000-8000-000000000001",
  "importer": "image",
  "type": "sprite-frame",
  "subMetas": {}
}

这是 player.png.meta 的示意：uuid 是编辑器分配的资源标识，importer 声明用哪个导入器处理（图片走 image），type 是导入后的资源子类型（切成了 sprite-frame），subMetas 存放子资源（如自动切分出的多个 SpriteFrame）。这些字段一律由编辑器生成，手写极易写错。

因此有三条铁律：不要手写 .meta（UUID 由编辑器分配）、不要在文件管理器里直接改名或移动资源（会让 .meta 与资源对不上）、不要提交 library/ 却漏掉 .meta（.meta 必须随资源一起进版本库）。用 Cocos Creator 打开工程时，编辑器会先扫描 assets/，为缺失的 .meta 补齐、为改动的资源重导。

B.3 settings/v2/packages/：项目设置

settings/v2/packages/ 下按「包」拆分项目设置，每个包一个 JSON 文件：

settings/
└── v2/
    └── packages/
        ├── project.json     # 项目级设置：引擎模块、分组、物理、渲染管线
        ├── builder.json     # 构建选项：平台、模板、MD5 缓存、分包
        └── engine.json      # 引擎裁剪：勾掉不用的模块以减小包体

这些文件的角色，是把编辑器面板里勾选的选项序列化下来。比如你在「项目设置 → 构建」里勾了「MD5 Cache」，builder.json 里就会出现对应字段。

以下片段需 Cocos Creator 3.8 编辑器打开，本节不可命令行复现：

{
  "general": {
    "designResolution": { "width": 960, "height": 640 },
    "fitWidth": true,
    "fitHeight": true
  }
}

上面的结构是 settings/v2/packages/project.json 中「设计分辨率」相关字段的示意。这个文件不该手改：字段名与默认值由编辑器版本决定，手改容易写出编辑器不认的组合。正确做法是在「项目设置」面板里调整，让编辑器回写。

B.4 library/、temp/ 与 build/

这三个目录经常被新手误当成「要维护的东西」，其实都是产物：

• library/：资源导入后的中间形态。编辑器把 assets/ 里的 .png、.ts、.scene 统一「导入」成引擎能直接加载的内部格式，放进 library/，并用 .meta 里的 UUID 做索引。它体积很大、内容随编辑器版本变化，不该进版本库。
• temp/：编辑器运行时的临时文件，其中就包括自动生成的 tsconfig.cocos.json（见 B.6）。删掉它不会丢东西，编辑器下次会重建。
• build/：点击「构建」后生成的产物，按平台分子目录（如 build/web-mobile/、build/wechatgame/）。它是要发布的东西，不是要编辑的东西。

判断一个目录该不该进 Git，可以用一句话：只有 assets/、settings/、package.json、tsconfig.json 和 extensions/ 属于源；library/、temp/、build/、profiles/ 属于产物。

B.5 .scene 与 .prefab 长什么样

.scene 是场景文件，.prefab 是预制体文件。两者都是编辑器序列化出来的结构数据，描述「有哪些节点、节点上挂了什么组件、组件的属性值是多少」。它们不是给手写的，但读一眼能帮你理解节点树。

以下片段需 Cocos Creator 3.8 编辑器打开，本节不可命令行复现：

{
  "__type__": "cc.Scene",
  "_name": "main",
  "_children": [
    { "__id__": 2 }
  ],
  "_globals": { "__id__": 10 }
}

这是 .scene 顶层的示意：__type__ 标明对象类型（cc.Scene），__children 用 __id__ 引用数组中的其他对象（此处指向索引 2 的节点），_globals 指向场景级配置。整个文件是一张用 __id__ 串起来的对象图——这正是编辑器里那棵节点树的磁盘形态。

预制体同理，只是根类型换成 cc.Prefab：

{
  "__type__": "cc.Prefab",
  "_name": "coin",
  "data": { "__id__": 1 },
  "optimizationPolicy": 0
}

coin.prefab 被实例化时，引擎按这份数据克隆出一棵节点子树。你在代码里用 instantiate(prefab) 得到的就是它。

B.6 接入 @cocos/creator-types 做离线类型检查

这是本附录唯一能真做的验证。@cocos/creator-types 是一个纯类型声明包，提供了 cc 模块的类型定义，因此哪怕没有安装 Cocos Creator，也能让 import { Node } from 'cc' 通过 tsc --noEmit。

接入方式是在工程的 tsconfig.json 里声明 types 入口：

{
  "compilerOptions": {
    "target": "ES2021",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "experimentalDecorators": true,
    "types": ["@cocos/creator-types/engine", "@cocos/creator-types/editor"]
  },
  "include": ["assets/**/*.ts"]
}

两个 types 入口分工明确：@cocos/creator-types/engine 提供运行时类型（Node、Component、director、resources 等，即 import ... from 'cc' 能拿到的一切）；@cocos/creator-types/editor 提供编辑器扩展类型（写 extensions/ 下的编辑器插件时才会用到）。

注意：真实 Cocos 工程里的 tsconfig.json 通常 extends 到 temp/tsconfig.cocos.json，由编辑器生成后再叠加这些选项。本附录给出的是最小可离线复现的版本，适合在无编辑器的环境里单独做类型检查。

配好之后，下面这段 L2 片段就能通过类型检查（Node 已在 cc.d.ts 中确认为 export class Node extends CCObject implements ISchedulable, CustomSerializable）：

import { Node, Component, _decorator } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('PlayerControl')
export class PlayerControl extends Component {
  @property
  speed = 260;

  private target: Node | null = null;

  setTarget(node: Node): void {
    this.target = node;
  }
}

Component（export class Component extends CCObject）是组件基类，_decorator（export namespace _decorator）提供 ccclass / property 等装饰器。这里用到的每个符号都先查过 cc.d.ts，不是凭记忆写的。

@cocos/creator-types/editor 则用于写编辑器扩展。它提供的不是 cc 模块，而是一个全局命名空间 Editor（editor.d.ts 里用 declare global 声明），因此扩展脚本不需要 import 就能用它。例如扩展入口里的常见写法（同样是 L2 片段）：

// 编辑器扩展入口：Editor 是全局命名空间，由 @cocos/creator-types/editor 提供
export function load(): void {
  Editor.Message.broadcast('build-finished', 'web-mobile');
}

Editor.Message 提供了 send / request / broadcast 三个方法：send 发消息不等返回、request 发消息并等返回（返回 Promise）、broadcast 广播给所有插件。编辑器 API 只在编辑器进程里存在，所以它天然不会被打进游戏运行时——这也解释了为什么两个 types 入口要分开声明：引擎类型进游戏包，编辑器类型只服务扩展。

一个常见的坑：如果 tsconfig.json 里写了 types: [...]，它会限定可用的全局类型包，某些工具自带的全局声明可能因此消失。稳妥做法是把 @cocos/creator-types 的两个入口都列进去，并把 include 限定在 assets/**/*.ts 与 extensions/**/*.ts，避免把 library/ 里的生成代码也拖进检查。

B.7 用 cc.d.ts 反查 API

写 Cocos 代码时最高频的错误就是「API 名记错」。cc.d.ts 是引擎的完整类型声明（3.8.8 版本约 3.3 MB），把它当字典查是唯一可靠的做法。三种查法：

grep -nE 'export (declare )?(abstract )?(class|interface|type|function|const|enum|namespace) Node\b' cc.d.ts  # 查符号的声明行
grep -nE 'export.*\btween\b' cc.d.ts  # 查任何含关键字的导出行
grep -nE 'export namespace _decorator' cc.d.ts  # 查命名空间成员

查一个类时，export class X 能直接告诉你它继承谁、实现了哪些接口，这是判断「它是不是组件」「它挂不挂在节点上」的最快途径。查 _decorator 这类命名空间时，则要打开命名空间块，逐个看里面的 export const（每个装饰器都是 export const ccclass: ClassDecorator 这样的常量），而不是猜成员名。

两个实用习惯：先查名字存在，再查签名——先用方式 1 或 2 确认符号真实存在，再打开该行附近看方法签名；不要用 IDE 的自动补全代替查证——补全来自同一份声明，但它不会告诉你「这个 API 在这个版本里是不是废弃了」。3.8.8 是本套书锁定的版本，跨版本差异必须以这份 cc.d.ts 为准。

B.8 离线能做什么、不能做什么

把三层可运行性口径落到「工程」这件事上，边界就很清楚了：

这就是本套书为什么把运行验证全部放在 mini2d（L1）、把 Cocos 侧限定在类型检查（L2）与结构阅读（L3）的原因：能跑的部分做到极致，不能跑的部分如实标注。 你手边没有编辑器也能读完前 17 章并跑通全部 mini2d 代码；要真正打开工程、拖节点、点构建，才需要装 Cocos Creator 3.8。

B.9 常见问题

B.10 一页速记

• 源只有 assets/ + settings/ + package.json + tsconfig.json；library/、temp/、build/ 都是产物，不进版本库。
• assets/ 里资源与 .meta 成对出现，引用走 UUID 而非路径；不要手改 .meta。
• .scene / .prefab 是用 __id__ 串起来的对象图，对应编辑器里的节点树与预制体。
• 离线类型检查：tsconfig.json 声明 types: ["@cocos/creator-types/engine", "@cocos/creator-types/editor"]，然后 import { Node } from 'cc' 可检查。
• 查 API：grep cc.d.ts 的 export class / export namespace，先确认存在再写。
• 工程与场景需 Cocos Creator 3.8 编辑器打开，命令行不可复现；只有类型检查可离线做。

本附录与附录 A 互为左右两栏：左边是你能完整读懂的 mini2d，右边是它对应的 Cocos 工程体系。把两栏对着看，第 18 章的迁移清单会好读很多。