游戏引擎 / 系统课时
按日志和断点定位运行时异常
按日志和断点定位运行时异常
第三人称动作关卡出现受击报错、敌人不生成或重载后 HUD 不更新时,先固定触发步骤,再从 Console 的第一条异常追到调用堆栈和运行时引用。本课用可复现的空引用案例练习断点检查,并把故障症状、触发条件和实际原因分开记录。
学习目标
- 从 Unity Console 的异常类型、堆栈和脚本行号缩小定位范围。
- 通过 IDE 断点检查 Prefab、场景引用与事件调用时序。
- 用相同触发步骤完成修复回归,避免只消除报错文本。
先抓住第一条异常和触发条件
以 Unity 6(6000.x)为例,在编辑器打开 Window > General > Console。点击 Clear 清除旧日志,勾选 Clear On Play 后重新进入 Play 模式;先关闭 Collapse,以免把连续出现的异常误认成一次。
- 只做一次触发操作,例如在关卡中击中敌人或点击重开。
- 选中最早出现的红色异常,看异常名、报错脚本和调用堆栈。双击项目脚本对应的堆栈行,跳到源码。
- 如果堆栈缺少有用帧,在 Console 右上菜单选择
Stack Trace Logging > Exception > ScriptOnly;排查托管 C# 错误通常不必使用开销更大的Full。 - 记录操作前的场景、对象是否激活、是否为第二次进入关卡,以及第一条异常时间点。后续报错可能只是前一次初始化失败的连锁反应。
Error Pause 可在调用 Debug.LogError 时暂停 Play;它不等同于 IDE 的逐行断点。异常行指明“在哪儿出错”,并不能直接证明“为什么该引用变空”。

用一段脚本复现空引用
创建 SpawnDiagnostic.cs,将下面完整脚本挂到场景中新建的启用对象 ProbeHost。先不要设置 Spawn Point 和 Enemy Prefab,并确认场景中没有名为 MissingSpawnPoint 的对象。示例不依赖旧输入系统,使用 Inspector 中的组件右上角菜单触发诊断。
using UnityEngine;
public sealed class SpawnDiagnostic : MonoBehaviour
{
[SerializeField] private Transform spawnPoint;
[SerializeField] private GameObject enemyPrefab;
private void Awake() => Debug.Log($"[SpawnDiagnostic] Awake {name}", this);
private void OnEnable() => Debug.Log($"[SpawnDiagnostic] OnEnable {name}", this);
private void Start() => Debug.Log($"[SpawnDiagnostic] Start {name}", this);
[ContextMenu("Reproduce NullReference")]
private void ReproduceNullReference()
{
if (!Application.isPlaying) return;
// 模拟按名称查找失败后仍访问对象的错误写法。
GameObject missing = GameObject.Find("MissingSpawnPoint");
Vector3 position = missing.transform.position;
Debug.Log($"[SpawnDiagnostic] Position {position}", this);
}
[ContextMenu("Validate And Spawn")]
private void ValidateAndSpawn()
{
if (!Application.isPlaying) return;
// 防御检查必须覆盖生成点和 Prefab 两种依赖。
if (spawnPoint == null || enemyPrefab == null)
{
Debug.LogError(
$"[SpawnDiagnostic] Missing: point={spawnPoint == null}, prefab={enemyPrefab == null}",
this);
return;
}
GameObject instance = Instantiate(enemyPrefab, spawnPoint.position, spawnPoint.rotation);
Debug.Log($"[SpawnDiagnostic] Spawned {instance.name}", instance);
}
}进入 Play 后,通过 SpawnDiagnostic 组件右上角菜单选择 Reproduce NullReference。预期 Console 依次出现以下关键消息(其他 Unity 日志及实际脚本行号可能不同):
[SpawnDiagnostic] Awake ProbeHost
[SpawnDiagnostic] OnEnable ProbeHost
[SpawnDiagnostic] Start ProbeHost
NullReferenceException: Object reference not set to an instance of an object打开最后一条异常的堆栈,应能找到 SpawnDiagnostic.ReproduceNullReference。此处的直接原因是 GameObject.Find 没找到对象而返回 null,随后代码仍访问 missing.transform;不是 Instantiate 或生成算法的问题。Reproduce NullReference 是故意构造的反例,交付项目时应删除。
用断点确认值从哪里变错
以下以 Windows 上装有 Visual Studio Tools for Unity 的 Visual Studio 2022 为例。在 Unity 的 Edit > Preferences > External Tools > External Script Editor 选择 Visual Studio;将编辑器的 Code Optimization 切为 Debug Mode,再使用 Visual Studio 的 Debug > Attach Unity Debugger 连接当前 Unity Editor。macOS 的首选项入口为 Unity > Settings > External Tools,可使用 Rider 或安装 Unity 扩展的 VS Code,其附加操作入口不同。
- 在
Vector3 position = missing.transform.position;这一行设置断点;返回 Unity,保持 Play,重新触发Reproduce NullReference。 - 断住时在
Locals或Watch检查局部变量missing,预期为null;也可观察未绑定的spawnPoint,同时看this.name是否为ProbeHost,确认命中的不是另一个脚本实例。 - 使用
F10逐过程、F11逐语句进入调用,F5继续。此案例在解引用前已经有充分证据,无须通过反复抛异常判断。 - 如果断点始终不触发,确认已附加到正确的 Editor 进程、脚本无编译错误、代码优化是
Debug,且操作确实进入了该方法。
分清引用丢失与事件顺序问题
| 表面症状 | 优先确认的根因 | 对应修复 |
|---|---|---|
NullReferenceException |
普通 C# 引用为 null,或 GetComponent<T>() 没找到组件 |
给序列化字段赋值,检查组件挂载和初始化路径 |
UnassignedReferenceException |
脚本序列化字段未在 Inspector 中赋值 | 检查场景实例与 Prefab 的对应字段 |
MissingReferenceException |
之前引用的 UnityEngine.Object 已被销毁 |
停止继续访问已销毁对象,追踪销毁与回调执行先后 |
| 只在场景重载后报错 | 事件监听器未解绑、旧实例仍被回调,或新实例初始化尚未完成 | 检查 OnEnable 订阅、OnDisable 解绑及重新绑定流程 |
Inspector 中 None (Transform) 表示当前没有设置目标;Missing (Transform) 提示原序列化目标已经失效。若同一 Prefab 只在某个关卡报错,必须选中 Hierarchy 里的实际实例 检查字段和 Overrides,不能只看 Project 中的 Prefab 资产。
对于事件回调报错,再查两件事:是谁发出的事件、回调运行时目标对象还在不在。同一个启用组件的初次生命周期一般依次经历 Awake、OnEnable、Start,但不能假定不同对象的 Start 已在另一对象的 OnEnable 前执行。若监听回调依赖 Start 才取得的引用,应提前建立依赖或显式控制初始化顺序,而不是靠反复添加判空掩盖时序缺陷。
按相同路径修复并验收
退出 Play 模式,通过 GameObject > Create Empty Child 在 ProbeHost 下建立 SpawnPoint 子物体,将其 Transform 拖到 Spawn Point。再用 GameObject > 3D Object > Capsule 新建并命名 Enemy,把它从 Hierarchy 拖到 Project 的 Assets 中制作 Prefab,删除场景内原本的 Enemy,把 Prefab 资产拖到 Enemy Prefab。重新进入 Play,选择 Validate And Spawn。预期输出:
[SpawnDiagnostic] Spawned Enemy(Clone)同时 Hierarchy 应出现 Enemy(Clone) 实例。如果保持字段为空而调用 Validate And Spawn,则得到 Missing: point=True, prefab=True 的错误日志,程序提前返回,不会再次发生 .position 空引用。确认回归时关闭 Error Pause 或手动继续播放,以免把主动记录的错误误认成运行卡死。
复现用的 Reproduce NullReference 方法不会因设置了 Spawn Point 而自动修好;正式修复应消除无校验的按名称查找,并使用已绑定引用的安全路径。
最后按“首次进入关卡→触发生成→重开关卡→再次触发”跑两轮:Console 不再出现新增异常、生成数量符合每次一次的预期、重载后的监听器不重复响应。故障单分别记录 症状(重开后生成失败)、触发条件(第二次进关卡)、根因(例如旧事件订阅指向已销毁实例);只有根因经过断点和复测证实后,才将“怀疑”改为结论。