《Cocos 游戏开发入门》前言：本书怎么读

前言：本书怎么读

这一篇是给全书做「使用说明」的：这本书怎么来的、写给谁、按什么版本口径写、四卷怎么分布、本卷处在什么位置、哪些内容明确不写，以及不同的人该怎么读。如果你只有五分钟，读完这一篇就能判断该从哪一页开始。

这本书是怎么来的

先说一个事实：这套书稿诞生的直接原因，是站内缺少 Cocos 的内容。

本站的游戏开发主题已经积累了一千多篇文章，覆盖客户端、服务端、发行与行业等方向，另外还有若干套围绕自研引擎与图形学的书稿。但 Cocos 是一个空白：既没有系统的教程，也没有一本从零讲起的书稿。与此同时，Cocos Creator 又是国内 2D 小游戏生态里被用得最多的引擎之一。这个缺口，就是这套书的起点。

第二个原因是方法上的。市面上的 Cocos 教程大多从「怎么用编辑器」讲起，读起来很快，但读者往往停在「照着做能做出来，换个需求就不会了」的位置。我们想换一种讲法：先让你自己写一遍引擎的机制，再看 Cocos 怎么封装它。 这条路线慢，但换来的理解更扎实。

第三个原因是诚实的约束。Cocos Creator 是 GUI 编辑器，它的运行时不在 npm 上，命令行里既装不了也跑不起来。既然如此，与其假装「所有代码都能一键复现」，不如把能跑的部分做到极致、把不能跑的部分如实标注。这套书的三层可运行性口径，就是从这个约束里长出来的。关于这三层口径的由来，序 里讲得更细，这里不再重复。

写给谁：四类读者

这本书假定你会写 TypeScript（或 JavaScript），了解基本的面向对象与异步（Promise）。数学只需高中水平——向量、矩阵、一点点三角函数。你不需要图形学基础，也不需要先装好 Cocos Creator 编辑器就能读前十七章。

如果你属于下面四类人之一，这本书就是为你写的：

反过来说，如果你只想找一本 Cocos Creator 的 API 速查手册，或者指望读完就能独立上线一款商业游戏，这本书可能不是最合适的选择。它的目标更朴素：让你扎实地走通一条从零到能交付的路。

前置知识与动手准备

具体来说，你最好已经具备：

• 能读写 TypeScript 的类、接口、泛型与类型标注；
• 知道什么是 npm 与 package.json，能在终端里切换目录、执行命令；
• 大致理解模块（import / export）与异步（async / await），能读懂最基础的英文报错信息。

如果你完全没写过 Canvas，也不必担心。本卷用到 Canvas2D 的地方集中在第 2 章，正文会从「怎么拿到绘图上下文、怎么画一个矩形」讲起。如果你完全没接触过游戏开发，那就更合适了——这本书从零开始，不预设任何游戏工程经验。

技术栈与版本口径

这是全书唯一集中交代版本的地方，请留意它，因为后面每一节都会默认你已经知道这些口径。

关于「可擦除语法」：Node 26 直接运行 TypeScript 时，只剥离类型、不做语法转换。所以 enum、namespace、构造函数参数属性这些「需要生成运行时代码」的写法不能用。本书一律用 const 对象 + as const 代替 enum，用模块导出代替 namespace。这不是限制，而是一种更贴近现代 TS 的写法。

mini2d 侧的依赖只有 typescript、vitest、vite 和 playwright；渲染用浏览器原生的 Canvas2D，不引入任何游戏库。这一点是刻意的：如果引入现成的渲染或物理库，你就看不到那些机制是怎么实现的，而它们正是本书要讲的东西。

需要特别说明的是 Cocos 版本。全书锁定 Cocos Creator 3.8.8，不写任何其他版本号。 引擎的小版本之间 API 偶有变动，为了让你抄下来的每一段脚本都能对上号，本书在 L2 的每个 cc 符号落笔前，都会先查该版本的 cc.d.ts，而不是凭记忆或凭旧文档。

环境自检

在动手之前，先用下面几条命令确认你的环境版本对齐。版本对不上不一定会报错，但可能让你在某个诡异的地方卡住。

node --version                          # v26.5.0
./node_modules/.bin/tsc --version       # Version 7.0.2
./node_modules/.bin/vitest --version    # vitest/5.0.3 darwin-arm64 node-v26.5.0
./node_modules/.bin/vite --version      # vite/8.3.4

如果这几行输出的版本与上表一致，环境就算就绪了。Cocos Creator 3.8.8 是 GUI 编辑器，需要单独安装，但它不是读前十七章的前提——第 1 章 1.1 会带你接通对 cc.d.ts 的类型检查，这不需要编辑器本身。

四卷结构：180 篇的布局

这套书按难度分为四卷，卷一《Cocos 游戏开发入门》是起点，另外三卷在它之上叠加能力。

四卷合计 180 篇。它们围绕同一个项目《方块冲刺》推进：卷一在自研运行时上把它从小方块养成完整小游戏，卷二用引擎重做一遍，卷三讲引擎内部，卷四给它加上联机。

本卷在四卷中的位置

这一卷是全书的地基，也是唯一一卷要求你亲手写引擎的。它的 18 章分五个部分：

卷一刻意在某几处停住，把更深入的内容留给后三卷：引擎内部机制（留给卷三）、Cocos 工程的工程化细节与多端发布实操（留给卷二）、客户端侧联机（留给卷四）。如果你读完卷一觉得「还不够深」，那正是设计如此——先走通一条完整的路，再回头补深度，比一上来就啃引擎源码要有效得多。

本书的三个刻意取舍

在动笔之前，我为这套书定了三条规矩。它们决定了每一节的样貌，也决定了这本书不适合谁。

第一，讲「引擎怎么转」，而不只是「API 怎么调」。 比如讲到渲染，重点不是背下 Sprite 组件有哪些属性，而是理解「把一张纹理的某个区域画到某个位置」这个动作背后发生了什么。理解了机制，换个引擎你也能立刻上手。

第二，示例必须可验证。 书里出现的每一段 mini2d 代码，都保持为可以复制进编辑器、稍作调整就能运行的最小完整片段，并且尽量配有可断言的测试或截图。

第三，不回避难点，但也不炫技。 固定步长、引用计数、宽相这些概念都会认真讲，但反复提醒「能简单就别复杂」：能用 AABB 解决的碰撞，就不要上 SAT；能把逻辑写清楚的，就不要过早抽象。

本书不写什么

说清楚不做什么，往往比说清楚做什么更有助于建立正确的预期。这套书不会：

• 写服务端实现。 网关、AOI、匹配、裁决这些属于服务端视角，站内已有大量专题文章；卷四的联机也只讲客户端侧，服务端只给接口约定。
• 写 Steam 发行全流程。 商店页、成就、创意工坊、平台对接，是另一条独立的线，不在本书范围。
• 写行业与商业化。 团队管理、买量投放、变现模型，这些内容与「怎么写游戏」是两件事。
• 写 Godot / Phaser / Defold 教程。 卷三第 11 章只做一次横向引擎对照，不展开任何一个竞品的用法。
• 写图形学底层 API。 Vulkan、OpenGL、WebGPU 的细节不在本书范围；本书停在 Canvas2D 与引擎的渲染管线这一层。

三条阅读路径与阅读建议

目录页 给出了三条读法，这里只做一点补充：

• 路径 A（约 10 周）：按顺序走完 18 章，每章代码亲手敲一遍。最完整，也最费时间。适合想真正吃透 2D 引擎机制、或打算自研小引擎的读者。
• 路径 B（约 6 周）：只读每章末节的「Cocos 对照」，把 mini2d 当注解。适合时间紧、目标是尽快上手引擎的读者。建议至少完整读第 4 章与第 7 章。
• 路径 C（随时）：不打算通读，只在遇到具体问题时翻对应章节。目录页的「常见问题速查表」就是为这条路准备的。

无论走哪条路径，都建议你把代码敲一遍，而不是只读。游戏开发尤其容易制造「我明白了」的错觉——看着别人写好的循环，每一步都合理，合上书却写不出来。

给不同起点的读者

同一本书，不同背景的人应该读出不同的重点。

如果你完全没写过游戏，请按顺序读，把每一节的代码都敲一遍。不要因为第 1 章「只是一个会动的小方块」就跳过——那个方块里包含了主循环、时间与坐标的全部约定，后面所有的章节都在它的基础上生长。

如果你用过 Unity 或 Godot，可以加快前几章的速度，但别跳过第 2、3 章：Cocos 的坐标系与节点体系有自己的约定，直接套旧经验容易踩坑。真正的差异集中在节点树、组件生命周期与资源管理这三处。

如果你时间很紧，请走路径 B：只读每章末节的 Cocos 对照，把 mini2d 当注解。但请至少完整读第 4 章与第 7 章——这两章的内容是引擎里最容易「用错了也不知道」的部分。

如果你只是想查一个具体问题，直接翻目录页 的「常见问题速查表」，它会告诉你该去哪一节。

学习时间估算

为了让「按需跳读」这条路径可执行，这里给出一份粗略的时间参考（按每天投入一小时计）：

总计约 8 到 10 周可以完成一遍系统学习。如果你的目标是「两周内做出一个能动的小游戏」，那么集中读第 1 到 4 章就够了——只是后面遇到碰撞、资源与打包问题时仍需要回来补课。

每一节的组织方式

为了让 54 节保持一致的节奏，正文的每一节都按同样的结构组织：开头一段说明本节目标与前置，主体用 ## X.Y 作节标题、其下用 ### X.Y.n 细分，末尾用几句话收束、点明本节最值得记住的判断标准。每一章的末节是「Cocos 对照」，把同一件事在 mini2d 里怎么做、在 Cocos 3.8 里怎么做摆在一起。

需要说明的是，本页（前言）以及序、目录和四篇附录并不遵循上面的正文结构——它们不是「一节正文」，因此没有开头的目标段，也没有末尾的「上一节 / 下一节」链接行，而是以正常段落收尾。翻到附录时不必觉得奇怪。

怎么判断自己真的学会了

学完一章之后，怎么知道自己是真懂了还是「读懂了」？这个问题比它看起来更重要，因为游戏开发特别容易制造「我明白了」的错觉。

下面这份清单可以用来自查。每一项都对应一种可以被观察的行为，而不是一种感觉：

• 能预判一段代码的效果。 看到一个速度值和 deltaTime，你心里已经知道角色这一帧会移动多远。
• 能解释现象背后的原因。 面对「角色怎么穿墙了」，你答得出是固定步长、碰撞响应还是宽相漏检的问题。
• 知道什么时候不该自己写。 能判断某个功能用引擎现成组件就够，还是真的需要自己实现。
• 能读懂报错并决定怎么改。 看到一个 cc 类型错误，你知道是符号用错、参数不对，还是版本不符。
• 能写可断言的测试。 你能用 vitest 断言一段逻辑的确定性结果，而不是靠肉眼观察画面。
• 能读懂一段引擎源码。 打开 cc.d.ts 查一个 API，你能判断它大致是怎么实现的。

反过来，下面这些信号说明你可能还停在「读过」的阶段：一遇到画面不对就凭感觉调参数；能看懂书里的例子但自己写不出来；分不清「画面看着对」和「逻辑真的对」的区别；写完主循环之后才回头补测试。

如果你发现自己中了几条，不必沮丧。游戏开发的能力本来就是靠「写—跑—改」的循环长出来的，回到对应章节，把示例亲手敲一遍，往往比再读一遍有效。

关于排版与术语约定

为了让全书读起来一致，这里约定几个术语，后面会一直用：

• mini2d：本卷从零手写的那个 2D 运行时，纯 TypeScript，零 cc 依赖。
• 《方块冲刺》：贯穿四卷的示例游戏，2D 横版跑酷。
• L1 / L2 / L3：三层可运行性口径，分别指 mini2d 代码、Cocos 组件脚本、Cocos 工程文件。
• cc.d.ts：Cocos Creator 3.8.8 的类型声明文件，是 L2 类型检查的依据。
• 可擦除语法：Node 26 能直接运行的 TypeScript 子集，不含 enum / namespace / 构造函数参数属性。

代码块的语言标注也有约定：ts 表示可运行的 TypeScript，json 表示配置文件，sh 表示命令行。Cocos 工程文件片段（.scene / .prefab / .meta）会额外标注「需编辑器，不可命令行复现」。

代码获取方式

本书不附带独立的代码仓库，原因很简单：mini2d 的每一节代码都保持为自包含、可复制的最小片段。与其维护一份可能随时间腐坏的仓库，不如让每一段代码都能就地跑起来。

真正值得你准备的只有两样：一个装好 Node 26 的本机环境，以及一个能运行 TypeScript 的编辑器。附录承担了「速查」的角色——附录 A 汇总 mini2d 的核心 API，附录 B 汇总 Cocos 工程结构与 cc.d.ts 反查方法，附录 C 汇总环境与离线复现步骤，附录 D 汇总常见错误。它们不按教学顺序组织，而是按查阅顺序组织，适合在你写代码卡住时随手翻。

与站内既有专题的分工

本站的游戏开发主题已经积累了一千多篇文章，另有若干套围绕自研引擎与图形学的书稿。它们质量不低，但有一个共同的特点：每一篇都假设你已经理解某个机制是什么，然后带你在一个点上钻深。

这本书与它们的分工，靠的是从零手写 + 可验证的分层。本卷的每一节都以 mini2d 的推进为主线，概念服务于可运行代码；站内专题则负责就一个问题钻到底。两者是互补关系：本书负责按顺序搭起一台引擎，专题负责在某个方向上深挖。

需要特别说明的是引擎内部机制：卷一只讲到「够用」。若正文提到 Cocos 内部实现，只作「卷三会展开」的预告，不深挖源码——内部机制的实证留给卷三。

关于代码风格与验证

因为 Node 26 只做类型剥离，本卷所有 TypeScript 代码都遵守同一条风格约束：只写可擦除语法。落到具体写法上有三条：

• 不用 enum，改用 const 对象配 as const。这样既有类型收窄，又不会生成运行时代码。
• 不用 namespace，改用模块（文件）导出。现代 TS 里，模块本来就是更自然的组织单位。
• 不用构造函数参数属性（constructor(private x: number)），改用显式声明字段再在构造函数里赋值。

这不是风格偏好，而是运行环境的要求：写了这些语法，Node 26 直接跑 TS 时会报错。本卷的验证也据此分层——L1 的代码真跑、真测，L2 的代码真做类型检查，L3 的工程文件显式标注不可命令行复现。附录 C 会给出完整的离线复现步骤。

读这本书之前，常见的问题

把读者最常问的几个问题集中回答一下，省得你在读的过程中反复分心：

这些问题有一个共同点：它们关心的都是「值不值得投入」。我的回答是——如果你想要的是一份能长期迁移的底层理解，而不是一个速成的框架用法，那这条路值得走。

关于这套书的一句话定位

如果只能用一句话概括这套书，我会说：它教你的是「怎么理解一台 2D 引擎」，而 Cocos 只是这台引擎的一个具体实例。

这句话决定了三件事。第一，书里的重点永远放在机制上，API 只是机制的一个名字。第二，验证方式永远服务于「证明机制真的成立」，而不是「证明这段代码能跑」。第三，读者的收获应当是可迁移的——你今天用 Cocos，明天可能换引擎，但「一帧怎么开始、坐标怎么换算、资源怎么释放」这些问题不会变。

也正因如此，本卷才选择先写 mini2d：它让你在没有引擎帮助的情况下，把那些机制亲手搭一遍。搭过之后，你再打开 Cocos，看到的不再是「一堆要记的组件」，而是「一堆你已经理解、只是别人帮你写好了的实现」。

勘误与反馈

技术书难免有疏漏，尤其是涉及引擎版本演进的细节。如果你在阅读中发现示例无法运行、表述有歧义，或者某个知识点讲得不够清楚，欢迎在站点相应页面留言指出。对于确认的问题，我会在后续修订中更新正文。

需要说明的是，本书面向的是「长期有效的判断力」，而不是「某个版本的 API 清单」。引擎在迭代，版本号在变，具体的类名、参数名、默认行为都可能过时；但帧循环、坐标变换、合批条件、资源生命周期这些内容，保质期要长得多。如果某一天你发现书里的某个 API 已经改了，但其中的设计仍然有用，那这本书就达到了它想要的效果。

现在，让我们从第 1 章 开始。先回答那个最朴素的问题：一帧，到底是怎么开始的。