参考教程与站内书单

5.1 官方文档的正确路径

Cocos Creator 3.8 的中文手册在 docs.cocos.com/creator/3.8/manual/zh/ 下。这个地址里能直接切换版本号，2.x 和 3.x 的文档组织方式完全不同，看的时候一定要确认左上角选的是 3.8。

我一般按这个顺序翻手册的章节，很少从头读到尾：

这里有个我踩过的坑：API 文档和用户手册是两个站点。手册在 /manual/zh/，API 文档在 /api/zh/。手册讲「怎么用」，API 文档讲「这个类有哪些方法和属性」。刚开始那两个月我一直在手册里找 API，找不到就以为这功能不支持，结果在 API 文档里发现签名早就改了。

手册的左上角版本切换器很容易被忽略。你搜到一篇 2.4 时代的文章，地址里是 /creator/2.4/，内容跟 3.8 差得很远。做笔记时把版本号一起记上，我现在的笔记标题格式是「问题 | 3.8.x | 章节路径」，过三个月还能搜到。Skyline Courier 这一路的笔记就是这么攒下来的，搜「碰撞分组 3.8.5」比搜「碰撞分组」准得多。

路径本身也有三个容易记错的：编辑器扩展在 editor/extension/，不是 editor-extension/；2D 物理在 physics-2d/，不是 physics/2d/；热更新在 advanced-topics/hot-update.html，不在 asset/asset-manager 下面。搜「2D 物理」结果跳到 3D 物理那几页去，是很多人第一反应走错的原因。

5.2 官方示例仓库怎么用

3.x 之后，范例工程不再随引擎安装包分发，全部搬到了 GitHub 上。这几个仓库我基本都会 clone 一份：

• github.com/cocos/cocos-example-projects：案例工程集合，最常用。
• github.com/cocos/cocos-test-projects：测试工程，适合看边界情况。
• github.com/cocos/cocos-example-render-pipeline：渲染管线示例，做特效和后处理时看。
• github.com/cocos/cocos-example-materials：材质与着色器效果集合。

主分支对应最新版本，旧版本有对应的 tag 或分支。clone 下来先看分支，我一般切到 3.8 对应的那个再看。

怎么读示例工程，我摸索出一套流程。第一步不是打开它，而是读 README 和目录结构，看看这个例子想演示什么功能、用了哪些资源。官方示例工程通常把美术资源分得很清楚，找起来不费劲。第二步，找那个功能的最小示例，不要通读整个工程。物理范例集合里有几十个小场景，你要找的是碰撞分组那个，不是把整个仓库都看一遍。

第三步是跑起来对比。我会把示例工程和我自己的工程并排放，示例里能跑、我这里跑不通，那就是我这边环境或者版本的问题，不是示例的错。这个对比法比读代码有效得多。

还有个细节值得提一句：示例工程里的资源可能用了引擎内部的测试用素材，导入时会产生大量警告，这是正常的，别被警告吓到。

另外还有一个仓库不在上面这四个里，但我做性能问题的时候翻它最多：github.com/cocos/cocos-awesome-tech-solutions。官方技术支持团队把疑难问题和技术方案都整理在里面，性能优化、包体瘦身这类问题基本都能在里面找到现成的思路。我做卡顿定位时，一半的方案是从这上面抄的。

5.3 论坛和中文社区

forum.cocos.org 是最该常去的地方。它分几个板块，技术问题在问答区，官方和引擎团队的人会回。发帖之前先搜一下，很多问题已经被回答过。提问时把 Creator 版本号、平台、复现步骤、报错原文贴全，能省掉来回三轮。

搜索技巧是搜错误码而不是搜描述。比如报「Cannot read property 'xyz' of undefined」，直接搜这一句，比搜「undefined 报错」命中率高得多。中文搜索命中低很多，优先用英文错误信息搜。

除了论坛，还有几个地方值得看。官方 GitHub 的 cocos/cocos-engine 仓库，issue 区能搜到很多已知问题，遇到引擎级的怪问题（比如某个组件莫名不刷新），在这里搜往往有结论。Creator 的更新日志和已知问题列表也在这里。

B 站和微信公众号上的官方账号发过不少实操内容，3.8 版本的新特性（比如可定制渲染管线、角色控制器）有一些官方讲解视频。视频适合建立整体印象，但不适合查具体参数，查参数还是回手册和 API 文档。

社区教程这块要提一个具体例子：indienova 上有一套《从零开发 ARPG 地下城》的文字版教程，内容覆盖 Tiledmap 绘制、键盘控制、碰撞、对话框、逐行文字、摄像机跟随、战争迷雾和随机地图生成。它的对应 B 站视频也是同一套。有意思的是它有文字版，看文字比看视频慢，但能跳、能搜、能反复读同一段。我做 Skyline Courier 的迷宫关卡时，把它的地图生成那部分改成了「按包裹投递点生成风区」。

论坛还有个「社区教程汇总」的帖子值得翻，那是官方整理的第三方教程入口。不过要注意一点：这类教程的版本可能落后，教程里写的路径和现在的 3.8 未必一致，遇到对不上的以手册为准。

5.4 站内书单：什么时候该读哪本

站内 Cocos 分类下的书，我按「什么时候需要翻开它」来排，而不是按新旧。

具体的引擎文档类书建议直接当工具书放在手边，遇到问题查；框架类书适合通读一次；算法和练手类书适合动手抄一遍。

有一点要说明：书里的版本和线上的文档站是同一套内容，不是快照。书给你的是可以离线翻、可以划线、可以带着走的形式，文档站给你的是永远最新的。日常翻书，遇到书里没有的新问题去搜文档站。

微信小游戏开发参考这类平台文档要单独提一句。它成文比较早，具体的接口签名早就变了，但平台侧的运行机制、审核规则的思路、开放能力的边界，这些底层逻辑没怎么变。看的时候要区分「机制」和「接口」：机制拿来理解，接口去查当下的官方文档。

5.5 遇到问题的查资料顺序

第一章写过一遍我刚上手时怎么找资料，那是从零建立习惯。这一节说的是项目做到一半、问题越来越具体之后，我用的顺序。

第一步，先缩小范围。 是编辑器里就复现不了，还是运行时才出问题？是所有资源都这样，还是只有某一个？编辑器里就不复现的问题，八成是资源导入配置或者脚本编译的事，先看 Console 和浏览器控制台的报错。

第二步，看报错原文。 报错信息里通常带文件名和行号，直接跳到那一行。别只看中文提示，英文原文里的信息更全。

第三步，按症状查手册。 这一步我后来做了一张索引表，比凭印象翻目录快得多：

第四步，搜官方示例仓库。 用 git grep 在 cocos-example-projects 里搜关键词，能搜到实际用法，比文档示例更贴近真实工程。

第五步，搜论坛和 GitHub issue。 搜英文报错原文。找到别人的帖子，重点看他怎么解决的。

第六步，做最小复现。 新建一个空工程，把出问题的那个功能单独搬进去。如果最小工程里不复现，说明是你的工程配置问题，去比对 settings、packages、prefab 的差别。这个步骤经常直接解决问题，但很多人懒得做。

第七步，才是自己读源码。 前六步都没结果，再去引擎仓库里翻实现。

我把这套顺序写成了一张卡片贴在显示器边上。关键是不要跳步：很多人一遇到问题就跳到第七步去啃源码，啃两小时发现答案在第三步就能查到。

还有一点要提醒：搜到答案之后要验证版本。同一个报错在 3.6 和 3.8 的处理方式可能不同，答案对得上版本才能用。

5.6 相关阅读

• Cocos Creator 3.8 用户手册
• Oops Framework
• libGDX v1.10 Documentation