游戏引擎 / 系统课时
运行并调试第一个场景
运行并调试第一个场景
本课用一个可见的 Label 和一条可搜索的日志,确认 Cocos Creator 3.8 场景已经真正运行,再在 Chrome 中给 TypeScript 脚本设置断点,检查组件引用和执行顺序。完成后,你能区分场景显示问题、脚本挂载问题与运行时报错。
学习目标
- 使用浏览器预览确认场景画面和脚本日志。
- 用 Console 与 Sources 定位组件运行位置并设置断点。
- 按可见现象排查空白画面、缺失引用和断点未命中。
准备可见且可记录的测试场景
打开一个已保存的 2D 场景;没有 Canvas 就先创建。接着在 Canvas 下创建一个 UI Label 节点并命名为 Status,保持它位于画面可见区域;再创建一个空节点 Probe。两者分别承担显示测试结果和运行脚本的职责。
在资源管理器中右键选择 TypeScript → NewComponent,创建 SceneProbe.ts,写入以下代码。statusLabel 是可在属性检查器中拖拽绑定的 Label 组件引用。
import { _decorator, Component, Label } from 'cc';
const { ccclass, property } = _decorator;
@ccclass('SceneProbe')
export class SceneProbe extends Component {
@property({ type: Label })
public statusLabel: Label | null = null;
start(): void {
const message = '场景运行正常';
// 先输出日志,便于区分未执行与未显示。
console.log(`[SceneProbe] ${message}`);
if (!this.statusLabel) {
console.warn('[SceneProbe] Status Label 未绑定');
return;
}
// 修改的是场景中已绑定的 Label 组件。
this.statusLabel.string = message;
}
}预期输出:将 SceneProbe 挂到 Probe,把 Status 节点拖进组件的 Status Label 属性并预览后,浏览器 Console 出现:
[SceneProbe] 场景运行正常同时,画面中的 Status 文字显示为“场景运行正常”。如果忘记绑定,日志仍会输出,另有 [SceneProbe] Status Label 未绑定 警告,但标签文字不会更新。这正好能区分“脚本没执行”和“节点引用没配置”。
要完成绑定,需要在层级管理器选中 Probe,确认属性检查器中已经挂载 SceneProbe 组件,再把 Status 节点拖到 Status Label 字段中。因为属性声明使用的是 Label 类型,编辑器会引用该节点上的 Label 组件,而不只是保存一个节点名称字符串。
通过浏览器预览核对场景
保存脚本与场景,等待编辑器完成编译;在顶部工具栏选择 浏览器 预览方式,场景选择 当前场景,再点击预览。浏览器会打开当前场景对应的运行页面。
第一次验证时,重点观察三个结果:
- 浏览器页面能否正常显示场景中的 Label。
- Label 内容能否从原始文字变成“场景运行正常”。
- 控制台能否找到
[SceneProbe] 场景运行正常。
在打开的预览浏览器页面按 F12,或使用 Ctrl+Shift+I 调出该页面的开发者工具,切换到 Console,搜索 [SceneProbe]。
浏览器的开发者工具负责调试网页预览。不要误把 Cocos Creator 编辑器自身的开发者工具当成预览页面的 Console,因为两者的执行上下文不同。
场景画面正确但没有日志时,先检查控制台过滤条件。已经出现日志但画面不变时,优先检查 Status Label 绑定是否完整,以及 Label 是否被其他 UI 遮挡、处于不可见状态。
在 Sources 中设置并命中断点
控制台日志只能告诉我们代码是否执行过,断点则可以让运行中的程序停在指定语句前,直接检查当时的变量、组件引用和调用位置。
本次把断点设在修改 Label 文字的语句上,目的是确认引擎已经运行到 start(),并且 statusLabel 在赋值之前确实引用了场景中的组件。
- 保持预览页面及其开发者工具打开,切换到 Sources。用文件搜索查找
SceneProbe.ts;若显示的是编译后代码,可搜索SceneProbe并在对应的运行代码处定位。 - 在
this.statusLabel.string = message;所在行左侧单击设置断点。若脚本在页面打开时已经执行过,刷新预览页面以重新触发start()。 - 暂停后在 Scope 查看
message和this.statusLabel。在当前暂停调用帧的求值上下文中检查this.node.name,应得到Probe;同时确认statusLabel不为null。 - 使用单步越过该赋值语句,再继续运行。若赋值已执行,屏幕文字应更新;调试结束后移除断点,避免后续刷新反复暂停。

首次进入 start() 时,message 应为字符串“场景运行正常”。如果在执行赋值前检查画面,Label 仍可能显示原始文字;单步执行赋值后,组件中的 string 属性就会变成新值。渲染画面通常需要在继续运行后才刷新,因此不要把断点暂停期间尚未重绘的画面误判为赋值失败。
如果 Sources 没有显示原始 TypeScript 文件,可能是源码映射尚未生效。可以先在 Sources 中定位到包含 SceneProbe 的实际执行脚本,再对对应的 JavaScript 语句设置断点。此时仍能调试执行逻辑,只是源码展示位置可能不同。
按现象缩小故障范围
| 现象 | 优先检查 | 验证动作 |
|---|---|---|
| 浏览器画面空白 | 当前场景、Canvas、Label 可见性 | 在编辑器中选中 Status,确认启用并保存后刷新 |
无 [SceneProbe] 日志 |
组件是否挂载、Probe 是否激活、脚本编译状态 |
检查组件启用勾选和编辑器错误信息 |
| 有日志但文字没变化 | Status Label 是否绑定、Label 是否被遮挡 |
拖入 Status 后重新预览 |
| 断点未命中 | DevTools 是否属于当前预览页、代码映射是否正确 | 设置断点后刷新,必要时在生成的脚本中设断点 |
排查时先保持场景和脚本尽量简单。不要同时改动相机、UI 布局、组件生命周期和预览配置,否则很难判断哪项修改真正修复了问题。
如果控制台出现错误,应先阅读第一条与自己脚本有关的异常,查看对应文件、行号和调用栈,再定位到代码处理。对于本例,statusLabel 未绑定已经通过空值检查转换成明确警告,比直接访问空引用后抛出异常更容易判断原因。
可以再做一次故意失败的验证:清空 Probe 上的 Status Label 属性并重新预览,确认 Console 输出未绑定警告;随后恢复引用,确认画面重新显示正确文字。这样就形成了“制造问题 → 观察证据 → 修复配置 → 再次验证”的完整调试过程。
在这次测试中,看到画面只能证明渲染链路可用;同时获得预期日志和可命中的断点,才说明场景加载、组件运行与调试入口全部贯通。