找资料：官方文档与示例库的正确用法

1.1 我曾经把官方文档翻了三遍，还是没解决问题

刚开始做 Cocos 的时候，我遇到一个 bug：物体穿过地面，没有被挡住。

我的第一反应是去搜索引擎，输入"cocos creator 物体穿过去了怎么办"。搜出来有 Cocos 2.x 的帖子，有 3.x 的帖子，有论坛回复，有博客。我点了十几个链接，关掉十几个标签页。问题没解决。

后来我老老实实打开官方文档，读物理系统那一章，发现是我把碰撞体设成了 Trigger，同时 RigidBody2D 的类型选了 Static，两个刚体之间根本不产生碰撞响应。

那件事之后我改了习惯。搜索引擎解决的是"这个 API 叫什么"，官方文档解决的是"这个东西该怎么用"。这两件事混在一起的代价是两小时。

现在我的资料获取流程有三条主线：官方文档、官方示例工程、官方论坛。三条各管一段。

1.2 官方文档该按什么顺序读，以及怎么在文档站里搜

官方文档不是用来"通读"的，它是用来查的。但刚开始你不知道查什么，得先知道它在讲什么。所以有一个粗读的阶段。

我的顺序是这样：

1. 先读新手入门和快速开始。大概知道工程怎么建、场景怎么开、脚本怎么挂、预览怎么跑。这一步别跳过，我见过有人直接跳到"脚本指南"，结果连脚本放在哪个目录、怎么被识别都不清楚。
2. 再读脚本指南。重点是组件的生命周期、属性装饰器、事件系统、TypeScript 的写法。这是我日常查得最多的部分。
3. 然后按系统读，每个系统花半天扫一遍目录，了解它解决什么问题、有哪些关键概念。物理系统、UI 系统、资源系统、动画系统、场景系统、构建发布系统。
4. 最后读构建发布和平台适配。这一块必须等你真的要做发布的时候再细读，早读记不住。

按这个顺序，我在两周内建立了一个"我该去哪个章节找答案"的心智模型。之后查东西就是查，而不是搜。

读的时候手里最好有一个具体问题。比如读物理系统，我手上就有"物体穿过地面"这个问题，读的时候专门盯碰撞体类型、刚体类型、碰撞矩阵这几节，读完立刻能对上。比从头顺读效率高很多。

文档站一般都有版本切换器。3.8 和 3.7 的文档在项目设置、物理部分差别不小。我这个项目全程用 3.8，看 3.7 的文档时会在心里打个折。

至于搜索，用文档站顶部的搜索框，别用搜索引擎。这个框跟搜索引擎最大的区别是它搜的是站内内容，站内内容版本是一致的。

我做的一个具体改进：浏览器书签栏里分了两组书签。一组是"Cocos 文档"，直接指到 3.8 手册的各个章节入口，比如脚本指南、物理系统、构建发布；另一组是"其他"，放搜索引擎。分组之后，"我要查 Cocos 的东西"这个动作就自动落到文档站上，不用每次做选择。

搜索词的选择也有讲究。我搜的时候用引擎里的真实类名和方法名，不搜中文描述。比如我搜 RigidBody2D type，不搜"怎么让物体不穿过地面"。中文描述搜出来的结果，大部分是别人翻译的博客，版本对不上。

搜到结果之后有个判断动作：这个页面顶部的版本号是不是我用的版本？3.8 文档页面左上角有版本标识，不是 3.8 的，我默认这条信息要重新验证一遍。

还有一个更省事的技巧：文档站里的 API 参考页面，通常在页面底部有"文档贡献"或者源码链接，点进去能直接跳到 GitHub 上的引擎源码。3.x 的引擎是开源的，源码在 cocos/cocos-engine 仓库，cocos/ 目录下按模块分文件夹。看到 API 文档写不明白的地方，直接去看源码里那个函数的实现，比看十篇博客都管用。

1.3 官方示例工程当活文档用

官方的示例工程不是"零散片段集合"，是完整的、可运行、结构清晰的项目。我把 2D 相关的示例工程整个下载下来，放在项目旁边的另一个文件夹里。

用法有三种：

1. 跑起来。看官方怎么组织一个完整项目：目录怎么分、脚本怎么放、资源怎么引、预制体怎么做。这比我看任何教程都有用，因为它是"正确答案"的形态。
2. 抄结构。我照着示例工程的做法改自己的目录。示例工程里脚本按模块分子目录、预制体和场景分开、公共代码单独放，我照着做了。
3. 查具体实现。想知道某个功能官方推荐怎么写，我不看博客，直接在示例工程里搜关键词，找到那个脚本读一遍。

举两个具体的例子。

Bundle 的用法。我在博客上看 bundle 的介绍，看了三篇还是不太懂分包和按需加载怎么配合。后来在示例工程里找到用 bundle 的项目，翻它的加载脚本，看到 loadBundle 的实际调用链，还有加载进度回调怎么传给 UI。比文字描述直观得多。

ScrollView 列表性能。官方示例里有个长列表的例子，注释提到复用 item 节点的做法。我照着改了订单列表，滚动明显不卡了。后来我才知道那叫对象池思路，但我是先在示例里看到代码才有的概念。

不过示例工程也有坑。为了讲清楚某个功能，示例代码写得比生产代码啰嗦，有些地方甚至故意简化。我抄结构，不抄实现细节。

还有一个提醒：示例工程的版本要和编辑器版本对齐。用 3.7 的示例在 3.8 里打开，会有一堆 API 差异要处理。我下载的时候专门挑了标注 3.8 的那批。

1.4 论坛和社区怎么问，才有人回

我在 Cocos 论坛上问过大概二十次问题，回帖率一半。收到回答的提问和不收到回答的提问，差别很明显。

收到回答的提问长这样：

• 标题写具体的现象和版本。"Cocos Creator 3.8.6，RigidBody2D 的 Static 刚体与另一个 Static 刚体不产生碰撞回调"
• 正文给最小复现步骤。我做过一个专门的复现工程，删到只剩一个场景、一个脚本、一个按钮，点按钮就出 bug。整个工程打包上传，几十 KB。
• 贴完整的报错日志。整段，不是我眼里的"重点"。我贴日志时把时间戳也留着，因为时间戳能看出是加载时还是运行时报的。
• 说明我试过什么。写了"我试过把 Type 改成 Dynamic，还是穿过"。这一句能省掉对方一半的提问。

没收到回答的提问长这样：

• 标题写"物理系统有问题，求助"
• 正文写"我的物体穿过地面了，大佬们看看"
• 不给版本，不给日志，不给复现

还有个细节，我觉得挺重要：先在论坛搜一遍同样的关键词。很多问题已经被问过并解决了，答案就在帖子中间某一条回复里。我有一次问了个关于 resources.load 路径的问题，翻到一个三个月前的帖子，里面写的答案和我踩的坑一模一样。

我还养成了一个习惯：看到有用的帖子，收藏到本地笔记文件里，标注问题、答案、日期、当时的版本号。记版本号很关键，半年前的一条答案你现在照着做可能就不行了，因为引擎改过。

1.5 自己排查的顺序，以及怎么判断看的是不是旧文档

等回复是最慢的路径。我自己的排查顺序是：

第 1 条治好了我大部分的"玄学 bug"。多数时候打印一次就现形，比如我以为是碰撞问题，实际上是坐标算错了。

第 2 条的核心是把问题缩到最小。一个完整场景里出的问题，缩到一个场景、一个节点、一个脚本。缩到最后往往会发现问题在很蠢的地方。

第 4 条要提前准备。我在项目旁边建了个放最小复现工程的目录，出 bug 就复制一份过去删到只剩骨架，之后直接当提问附件用。

第 5 条很实用，但前提是你知道自己的代码在旧版本里能不能跑。升级编辑器之前，先在旧版本上把功能做出来留个底，出问题好对照。

关于怎么判断自己看的是不是旧文档，我有几个具体的检查动作：

1. 看页面顶部的版本标识。文档站右上角有版本切换，页面里也可能标注适用版本。
2. 看 URL 里的版本号。官方文档站的地址路径里通常带版本号，比如 3.8、3.6。搜出来的链接如果是 3.6 的，那就是旧文档。
3. 看发布日期和更新日期。页面底部有"最后更新时间"。
4. 用引擎源码对照。最可靠的一招：文档说某个类有某个方法，去引擎源码的 cocos/ 目录里搜这个类，看有没有这个方法。有，就是新文档；没有，或者签名不一样，就是旧的或者写错了。

第 4 条我认为是终审手段。文档会过时，源码不会。引擎开源这件事给独立开发者的实惠就在这儿。

一个具体例子。3.8.7 引入了 Sorting2D 组件，同时在项目设置里加了排序图层配置。我在旧文档里找不到这个面板，就知道旧文档对不上了。3.8.7 的正式发布说明里专门讲了多场景和预制体并行编辑、脚本组件标记、Sorting2D 这几项，还有从 3.8.4 之后升级上来的项目需要把 Bloom 强度参数从 2.3 改回 1.0 这条变更。发布说明这个东西要养成看的习惯，它是判断"我用的版本和我知道的东西差在哪"的最直接来源。

1.6 相关阅读

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