游戏引擎 / 系统课时
从报错定位具体脚本问题
从报错定位具体脚本问题
角色进入关卡后突然停止响应时,反复修改脚本容易掩盖最早的异常。本课用可复现的数组越界问题,串起 Godot 4 的运行时报错、调用栈、断点与变量检查,找到错误参数的来源,并验证修复后的交互逻辑。
学习目标
- 区分错误发生的位置与错误数据的来源。
- 使用 Debugger 的 Errors、Stack Trace 和断点检查运行状态。
- 为数组访问加入边界校验,并用相同场景验证修复。
先复现第一条运行时错误
新建一个根节点为 Node3D 的场景,将以下 GDScript 挂到根节点,运行当前场景。代码故意只保存一个目标,却要求读取索引 1;数组索引从 0 开始,因此第二个元素不存在。
extends Node3D
var target_names: Array[String] = ["Door"]
func _ready() -> void:
inspect_target(1)
func inspect_target(index: int) -> void:
# 故意访问不存在的第二个目标,观察调试器反应。
print("读取索引:", index)
print("目标:", target_names[index])预期输出(Output 面板先出现):
读取索引:1随后底部 Debugger > Errors 会报告数组索引越界。错误文字可能随 Godot 小版本变化,重点记录脚本路径、出错行和首次出现的异常;后续连锁错误不应抢先处理。这里的出错行是数组读取,但尚不能仅凭这一行判断是谁传来了 1。
通过调用栈与断点追溯参数
为了在越界之前观察现场,点击脚本中 print("目标:", target_names[index]) 所在行左侧的边栏,设置红色断点,再重新运行场景。
- 程序暂停后,打开底部 Debugger > Stack Trace。当前帧位于
inspect_target(),上层调用来自_ready();切换栈帧可以追溯调用链。 - 在 Stack Trace 的变量区查看局部参数
index,或打开 Evaluator 检查index与target_names.size()。本例分别为1与1,合法索引只有0。 - 使用 Step Over 继续执行当前访问语句,观察错误;使用 Continue 继续运行。不要在未保存现场前反复点击继续执行。

调用栈回答的是“如何走到这里”,断点变量回答的是“当时传入什么”。两者合起来,才能把排查范围从整个关卡缩到 _ready() 传参处。真实项目中,上层也可能是信号回调、计时器或交互方法,不能默认报错函数本身负责产生异常数据。
加入校验并重新运行
将原脚本整体替换为以下版本。保留无效索引的调用,是为了确认程序能安全处理错误输入;再访问有效索引,验证正常流程没有被提前阻断。
extends Node3D
var target_names: Array[String] = ["Door"]
func _ready() -> void:
inspect_target(1)
inspect_target(0)
func inspect_target(index: int) -> void:
# 在读取数组前同时检查下界和上界。
if index < 0 or index >= target_names.size():
print("无效索引:", index, ";目标数量:", target_names.size())
return
# 只有通过校验,才执行真正的目标读取。
print("目标:", target_names[index])预期输出:
无效索引:1;目标数量:1
目标:Door移除断点后再次运行,确认 Errors 不再出现该索引异常。若目标数量来自动态生成的关卡对象,还应检查对象尚未创建、已被删除及数组为空的情况;仅把 1 改成 0 虽能消除这次报错,却没有修复不可靠的输入假设。
遇到其他报错时如何缩小范围
提示空引用或访问已释放对象时,先核对节点是否存在、是否在运行中被释放,再借助场景树的 Remote 视图检查实际节点。提示类型不匹配时,检查传入值和函数声明;脚本解析错误则应先修复语法,不能靠运行时调用栈定位。
诊断顺序始终是:稳定复现、记录第一条错误、暂停并查看调用链、核对关键变量、修复根因、以原操作回归。断点会暂停游戏时间,不适合直接用来判断联机延迟或连续物理运动的真实性能。