跳转到内容

40. 坏了怎么办,调试的思路

约 45 分钟 内容:进阶 动手章

如果按钮没有响应、门没有打开或显示状态不正确,可以从事件、数据和组件调用三个位置检查。没有看到错误不等于没有错误:过滤器、运行环境和日志收集设置都会影响可见信息。

在 Unity 打开 Window → General → Console。Log、Warning、Error 三类消息可以分别显示或隐藏;搜索框还会过滤消息。排查时先确认所需类别已开启,搜索条件没有隐藏相关记录。

记录已有错误后,点击 Clear,执行一次复现操作,再查看新增消息。编译错误不会因为清空显示就得到修复。

Collapse 开启时合并重复消息并显示计数;关闭后按条列出。需要区分每次调用的顺序时关闭,需要减少重复消息占屏时开启。

例如:

NullReferenceException: Object reference not set to an instance of an object
DoorController.Interact () (at Assets/Scripts/DoorController.cs:18)

异常类型说明发生了什么;调用栈中的文件名和行号帮助定位调用。选择消息可看完整文本,带源文件定位时可以双击跳转。

NullReferenceException 表示代码试图通过空引用访问对象。检查该行涉及的每个引用:Inspector 是否赋值、GetComponent 是否找到组件、对象是否仍有效。不能只凭异常名称确定是哪一个字段。

日志可以回答:事件是否收到、分支条件是什么、组件调用是否完成。以下是本地门开关的调试示例:

DoorDebugExample.cs
using UdonSharp;
using UnityEngine;
public class DoorDebugExample : UdonSharpBehaviour
{
public Animator doorAnimator;
private bool isOpen;
public override void Interact()
{
Debug.Log("[Door] Interact received");
if (doorAnimator == null)
{
Debug.LogError("[Door] Missing doorAnimator reference");
return;
}
isOpen = !isOpen;
Debug.Log($"[Door] isOpen = {isOpen}");
doorAnimator.SetBool("IsOpen", isOpen);
Debug.Log("[Door] SetBool completed");
}
}

可以按铰链和门板与Animator Controller 配置建立测试门。在副本中用 DoorDebugExample 替换按钮原有的门控制脚本,保留按钮的 Box Collider,避免两份脚本同时写门状态。把铰链对象上的 Animator 拖到 doorAnimator,确认存在 IsOpen Bool 参数、初始值为 false,默认状态是关闭姿态。这段代码只切换本地状态,不包含多人同步。

观察结果检查方向
没有第一条日志交互条件、对象与脚本是否启用、是否有更早的停止执行记录
出现 Missing referenceInspector 引用或对象生命周期
isOpen 正确,画面不变Animator 参数名、过渡条件、动画控制的对象
调用前有记录、调用后没有中间调用是否抛出异常,是否进入其他分支

日志缺失只能缩小范围,不能单独证明某个结论。异步事件、日志过滤和对象被禁用也可能影响结果。

排错后删除高频输出,或保留少量带统一前缀的关键日志。日志本身有运行和存储开销,测性能时也要记录是否启用了调试。

下面按官方调试文档中的视频调用错误保留关键层次,省去了时间戳和地址。这是阅读日志的样本,不是本章门脚本的实测输出:

[UdonBehaviour] ... this UdonBehaviour will be halted.
VRC.Udon.VM.UdonVMException: ... EXTERN ...
'VRCSDK3VideoComponentsBaseBaseVRCVideoPlayer.__GetTime__SystemSingle'
---> System.NullReferenceException: ...

读这段时分三步:

  1. halted 指出对应 UdonBehaviour 已停止执行,不能只追查后一次没有响应的点击。
  2. EXTERN 后的名称包含 VRCVideoPlayer、GetTime,把范围缩到脚本读取视频时间的调用。
  3. ---> 后的内部异常是空引用。回到该调用检查播放器引用与实际对象;有源文件映射时再结合行号定位。

样本中的方法名不是所有异常都会出现的固定字段值。换成灯、Animator 或其他组件时,应按自己的日志核对调用,不能把所有 halted 都归因于视频播放器。

在客户端日志中搜索 halted,找到最早的相关记录,再检查内部异常。EXTERN 表示 Udon 调用外部 API 的指令;函数名有助于确定失败发生在哪类组件调用。

第 12 章说明了 UdonSharp 的运行限制。不能用一般 C# 的 try-catch 写法假定所有异常都可在 Udon 中恢复。对可能缺失的引用、数组范围和有效玩家对象先检查条件;修复后重新运行相同流程。

第四节:客户端日志与调试视图

Section titled “第四节:客户端日志与调试视图”

Unity 编辑器执行的日志在 Console;VRChat 客户端执行的日志写入客户端日志文件。UdonSharp 的异常监听器可把客户端异常映射到 Unity Console,但这不等于所有客户端日志都自动出现在编辑器。

可在 VCC 的 Tools 中使用 VRC Quick Launcher 配置调试。Windows 批处理示例为:

debug.bat
VRChat.exe --no-vr --enable-debug-gui --enable-sdk-log-levels --enable-udon-debug-logging

把文件放在 VRChat.exe 所在目录,或改用正确的可执行文件路径,保存后双击启动。SDK 的 Build & Test 会启用相关调试功能。

  • --no-vr:桌面模式。
  • --enable-debug-gui:启用调试菜单快捷键。
  • --enable-sdk-log-levels:增加 SDK 等详细日志,可能明显增大文件并影响性能。
  • --enable-udon-debug-logging:启用客户端中的 Udon 堆、栈转储,便于调查异常;它不是把普通 Debug.Log 自动显示到屏幕的开关。

Steam 版也可在库中右键 VRChat,打开 属性 → 常规 → 启动选项,填入需要的参数后重新启动。这里只填参数,不填 VRChat.exe。该设置影响之后从 Steam 启动的客户端,排错结束后删除不再需要的调试参数。

客户端日志视图的快捷键是右 Shift + Backtick 键 + 主键盘数字 3。标准美式键盘上 Backtick 与 ~ 同键;其他布局以官方说明的键位为准。当前客户端也有 Quick Menu Settings 中的 Debug UI 入口。

Windows 日志位置:

C:\Users\<用户名>\AppData\LocalLow\VRChat\VRChat\

查找本次运行生成的 output_log_*.txt。分享日志前检查并移除不必要的玩家信息、私密实例信息或令牌;保留与问题相关的错误及上下文。不需要调试时关闭额外日志收集。

第五节:复现、缩小范围、修复和复测

Section titled “第五节:复现、缩小范围、修复和复测”

写出世界版本、平台、人数、操作顺序、预期结果和实际结果。偶发问题也可以调查:记录发生和不发生时的条件差异,而不是等它变成必现才开始。

例如:“两个客户端进入;A 开门;B 后加入;A 看见门开,B 看见门关。”这比“同步有问题”包含更多可检查的信息。

  • 沿事件和关键分支增加日志,检查执行到了哪里。
  • 在备份或独立测试场景里禁用一项功能,比较问题是否仍存在。
  • 保留依赖关系,制作只含必要对象和脚本的最小复现场景。

对已经确认会经过的一段顺序代码,可在入口、出口和中点分别放不同前缀的日志,先复现一次。确认中点没有被分支或提前 return 跳过,再在最后一条已出现日志与第一条未出现日志之间加点,重复缩小范围。若过滤器、回调时序或执行路径还不明确,先查这些条件,不能仅凭“中点没日志”断言错误在前半段。

可选效果可以用本地开关隔离。例如在本章 DoorDebugExample 类中增加 public bool enableDoorAnimation = true;,把 SetBool 及其后的完成日志两行替换为下面这段,保留前面的引用检查和状态日志:

替换 Interact 末尾两行
if (enableDoorAnimation)
{
doorAnimator.SetBool("IsOpen", isOpen);
Debug.Log("[Door] SetBool completed");
}
else
{
Debug.Log("[Door] Animation call skipped");
}

在副本中只改变这个开关,每次从相同初始状态运行,比较报错和状态输出;画面不动且出现 skipped 是关闭动画调用的预期,不应记作新的故障。

禁用某项后问题消失,只能说明它与触发条件相关;不能直接证明该组件本身有缺陷。反复改变多项设置会使结果难以归因。

修复具体原因,例如补充引用、修正对象、修改参数名或状态条件。回到原始复现步骤验证,再检查相邻流程:重复按按钮、离开后返回、重生、第二客户端加入等。

判空可以避免无效调用,但如果该引用是功能必需的,只跳过代码仍不算完成修复。保留清晰错误提示,并补齐配置。

消息片段含义或检查方向
NullReferenceException查当前行使用的引用和返回值
UdonBehaviour will be halted查同一段日志中的原始异常和外部调用
MissingReferenceException查对象是否已销毁,旧引用是否仍被使用
Cannot find method查事件目标、方法名、可见性和编译结果
not exposed in Udon在 Class Exposure Tree 与当前 SDK 文档中核对 API
script class cannot be found先处理编译错误,再查类名、文件名和资源引用

事件名拼写与 nameof 的实际检查步骤见事件方法未找到。不要把删除缓存作为所有错误的第一处理方式。缓存重建不能修复脚本语法、缺失源文件或错误的 GUID 引用。

Inspector 赋值和代码查找都可能拿不到需要的组件。以下脚本用于独立测试 Cube;Cube 自带 Box Collider,再给同一个对象添加 Rigidbody,关闭 Is Kinematic,关闭 Use Gravity,避免观察时直接落下:

ComponentLookupTest.cs
using UdonSharp;
using UnityEngine;
public class ComponentLookupTest : UdonSharpBehaviour
{
public override void Interact()
{
Rigidbody body = GetComponent<Rigidbody>();
if (body == null)
{
Debug.LogWarning("[Lookup] No Rigidbody on this object");
return;
}
body.AddForce(Vector3.up, ForceMode.Impulse);
Debug.Log("[Lookup] Force requested");
}
}

挂上脚本后交互,观察 Cube 的运动与日志。停止运行,在副本中移除 Rigidbody,再重新运行并交互:应出现缺少组件的提示,而不执行 AddForce。随后恢复组件。GetComponent 查的是脚本所在对象;父物体上的 Rigidbody 不会因为层级相邻就被这一行找到。

这段也可以写成 if (body != null) { body.AddForce(Vector3.up, ForceMode.Impulse); },把动作包在条件内。早退写法则在条件不满足时结束本次方法,使余下主流程不用逐层嵌套。若组件是功能必需的,判空后还要修正配置,不能把“没有异常”当成功能已恢复。

在场景副本中使用本章示例:

  1. 清空 doorAnimator 引用,执行交互,确认出现明确日志且不调用 Animator。
  2. 填回引用但故意写错 Bool 参数名,比较日志和画面,确认“调用完成”与“动画按预期播放”不是同一件事。
  3. 恢复正确参数,分别在 ClientSim 与客户端执行,记录日志出现的位置和结果。

只在独立测试场景或工程副本里建立一个带 Box Collider 的 Cube,挂下列脚本。不要改正式门脚本,也不要把故障版本上传到正式世界。代码中的未保护调用专门用于这次对照:

ControlledFault.cs(仅用于故障实验)
using UdonSharp;
using UnityEngine;
public class ControlledFault : UdonSharpBehaviour
{
public Light target;
public bool protectReference;
public override void Interact()
{
Debug.Log("[Fault] Interact entered");
if (protectReference && target == null)
{
Debug.LogWarning("[Fault] Missing target; skipped");
return;
}
target.enabled = !target.enabled;
Debug.Log("[Fault] Light changed");
}
}
  1. target 留空,protectReference 关闭。重新 Build & Test,交互两次;在本次客户端日志找第一条异常、对应 halted 与两次入口日志的数量。预期第一次在访问 Light 时停止,之后同一 UdonBehaviour 不再响应;若观察不同,保留实际日志及版本,不补写预期结果。
  2. 退出这次运行。在 Unity 打开 protectReference,重新构建后进入,再交互两次。预期每次都有入口与 Missing target 提示,没有执行 Light changed;与第一次的 halted 区分。
  3. 退出运行,给 target 拖入一个真实 Light,保持保护开启并重新构建。交互两次,检查灯恢复切换且两次都有完成日志。
  4. ClientSim 的同类操作在 Unity Console 查看;真实客户端以 output_log_*.txt 为准。异常监听器映射到编辑器的记录另作标注,不把没有映射误判成客户端没有错误。

每次只改变说明中的一个条件,重新构建而非运行 Last Build。保存对照记录后,将故障脚本留在测试场景,检查正式发布场景不包含它。