游戏引擎 / 系统课时
从控制台定位脚本异常
从控制台定位脚本异常
当 Cocos Creator 场景预览突然停止更新,问题往往不在画面本身,而是某个组件在运行时访问了不存在的对象。本课制造一次可重复的 TypeScript 空引用异常,用浏览器控制台读取报错与调用堆栈,再用断点检查变量并完成修复验证。
学习目标
- 区分脚本日志、运行异常与 TypeScript 编译错误。
- 从调用堆栈定位到自己编写的脚本与出错语句。
- 使用浏览器断点检查变量,并验证修复是否生效。
复现一个可控的运行时错误
准备一个 Cocos Creator 3.8 场景,在 Canvas 下创建名为 DemoRoot 的节点,确保它没有直接子节点 Target。将下列 CrashDemo.ts 保存到 assets/scripts/ 并挂在 DemoRoot 上。
import { _decorator, Component } from 'cc';
const { ccclass } = _decorator;
@ccclass('CrashDemo')
export class CrashDemo extends Component {
start(): void {
const target = this.node.getChildByName('Target');
console.log('[CrashDemo] 查找 Target:', target !== null);
// 故意误用非空断言:它不会在运行时检查 null。
console.log('[CrashDemo] 子节点名称:', target!.name);
}
}用 Chrome 打开浏览器预览,再按 F12 打开开发者工具的 Console。由于 getChildByName 找不到节点会返回 null,而 ! 只影响 TypeScript 类型检查,不会生成运行时保护。
预期输出(不同浏览器的错误前缀和堆栈展示方式可能不同):
[CrashDemo] 查找 Target: false
TypeError: Cannot read properties of null (reading 'name')若没看到这两项,先确认脚本已挂载、DemoRoot 处于激活状态、组件被启用且预览已刷新;编译错误应先在编辑器的编译信息中处理,尚未成功执行的代码不会产出上述运行日志。
从错误消息追到业务代码
先找到第一条红色异常,再展开它附带的调用堆栈。TypeError 说明访问对象类型不符合预期,reading 'name' 指向属性读取;结合上一条 false 日志,可推断 target 实际为 null。
点击堆栈里首先指向项目脚本的栈帧,优先检查 CrashDemo.start 中 target!.name 一行,而不是先修改 Cocos 引擎内部代码。路径、行列号和打包后的脚本名称随预览方式变化;如果只看到转换后的 JavaScript,就结合源码映射或搜索该日志文本定位。

在断点处确认变量
切换到 Chrome 开发者工具的 Sources,找到项目脚本或对应的生成代码,在访问 target!.name 前一行设置断点,然后刷新预览。程序暂停时,在作用域变量列表中查看 target,应为 null;再查看 this.node.name,确认脚本确实挂在 DemoRoot 上。
Call Stack 用来确认是哪个生命周期入口调用了这段逻辑,单步执行则可观察从查找节点到错误发生的顺序。若断点无法匹配 TypeScript 行,确认打开的是当前预览页,并检查源码映射是否可用;在构建后调试时,可在构建面板启用 Debug Mode 和 Source Maps 以便定位源代码。
修复空引用并回归验证
如果 Target 是可选节点,应先判断是否存在,再决定跳过初始化还是使用备用逻辑。下面是片段示例:保留原文件导入及 CrashDemo 类,只将其中的 start 方法替换为以下内容。
start(): void {
const target = this.node.getChildByName('Target');
if (!target) {
// 可选节点缺失时安全退出,而不是强行断言非空。
console.warn('[CrashDemo] Target 不存在,跳过初始化');
return;
}
console.log('[CrashDemo] 子节点名称:', target.name);
}预期输出(仍未创建 Target 时):
[CrashDemo] Target 不存在,跳过初始化随后在 DemoRoot 下创建名字完全一致的直接子节点 Target,刷新预览。预期输出:
[CrashDemo] 子节点名称: Target如果业务规定 Target 必须存在,除了增加空值检查,还应修正节点层级或名称;不能仅通过静默 return 掩盖错误配置。验收时同时确认异常消失、组件执行到预期分支、游戏画面和交互恢复正常。以后遇到相似问题,沿着“最早的错误消息→首个项目栈帧→断点变量→复现验证”定位,通常比直接猜测是哪段脚本出错更有效。