游戏引擎 / 系统课时

从控制台定位脚本异常

从控制台定位脚本异常

当 Cocos Creator 场景预览突然停止更新,问题往往不在画面本身,而是某个组件在运行时访问了不存在的对象。本课制造一次可重复的 TypeScript 空引用异常,用浏览器控制台读取报错与调用堆栈,再用断点检查变量并完成修复验证。

学习目标

  • 区分脚本日志、运行异常与 TypeScript 编译错误。
  • 从调用堆栈定位到自己编写的脚本与出错语句。
  • 使用浏览器断点检查变量,并验证修复是否生效。

复现一个可控的运行时错误

准备一个 Cocos Creator 3.8 场景,在 Canvas 下创建名为 DemoRoot 的节点,确保它没有直接子节点 Target。将下列 CrashDemo.ts 保存到 assets/scripts/ 并挂在 DemoRoot 上。

ts
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 类型检查,不会生成运行时保护。

预期输出(不同浏览器的错误前缀和堆栈展示方式可能不同):

text
[CrashDemo] 查找 Target: false
TypeError: Cannot read properties of null (reading 'name')

若没看到这两项,先确认脚本已挂载、DemoRoot 处于激活状态、组件被启用且预览已刷新;编译错误应先在编辑器的编译信息中处理,尚未成功执行的代码不会产出上述运行日志。

从错误消息追到业务代码

先找到第一条红色异常,再展开它附带的调用堆栈。TypeError 说明访问对象类型不符合预期,reading 'name' 指向属性读取;结合上一条 false 日志,可推断 target 实际为 null。

点击堆栈里首先指向项目脚本的栈帧,优先检查 CrashDemo.start 中 target!.name 一行,而不是先修改 Cocos 引擎内部代码。路径、行列号和打包后的脚本名称随预览方式变化;如果只看到转换后的 JavaScript,就结合源码映射或搜索该日志文本定位。

浏览器控制台中的 TypeScript 异常、调用堆栈和定位入口

在断点处确认变量

切换到 Chrome 开发者工具的 Sources,找到项目脚本或对应的生成代码,在访问 target!.name 前一行设置断点,然后刷新预览。程序暂停时,在作用域变量列表中查看 target,应为 null;再查看 this.node.name,确认脚本确实挂在 DemoRoot 上。

Call Stack 用来确认是哪个生命周期入口调用了这段逻辑,单步执行则可观察从查找节点到错误发生的顺序。若断点无法匹配 TypeScript 行,确认打开的是当前预览页,并检查源码映射是否可用;在构建后调试时,可在构建面板启用 Debug Mode 和 Source Maps 以便定位源代码。

修复空引用并回归验证

如果 Target 是可选节点,应先判断是否存在,再决定跳过初始化还是使用备用逻辑。下面是片段示例:保留原文件导入及 CrashDemo 类,只将其中的 start 方法替换为以下内容。

ts
start(): void {
  const target = this.node.getChildByName('Target');
  if (!target) {
    // 可选节点缺失时安全退出,而不是强行断言非空。
    console.warn('[CrashDemo] Target 不存在,跳过初始化');
    return;
  }
  console.log('[CrashDemo] 子节点名称:', target.name);
}

预期输出(仍未创建 Target 时):

text
[CrashDemo] Target 不存在,跳过初始化

随后在 DemoRoot 下创建名字完全一致的直接子节点 Target,刷新预览。预期输出:

text
[CrashDemo] 子节点名称: Target

如果业务规定 Target 必须存在,除了增加空值检查,还应修正节点层级或名称;不能仅通过静默 return 掩盖错误配置。验收时同时确认异常消失、组件执行到预期分支、游戏画面和交互恢复正常。以后遇到相似问题,沿着“最早的错误消息→首个项目栈帧→断点变量→复现验证”定位,通常比直接猜测是哪段脚本出错更有效。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

从控制台定位脚本异常

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通