Debug

自动关联目录:Debug

调试能力的价值在于缩短"现象 → 原因"的距离。UE 提供了很丰富的手段,关键是知道什么时候用哪个。

本目录

笔记内容状态
崩溃与 Dump崩溃类型、符号与栈还原、平台工具、稳定性工具已补充
日志与断言体系UE_LOG、check/verify/ensure 的选择、日志分类与级别已补充
Visual Logger 与 Gameplay Debugger事后回放与实时状态,UE_VLOG 打点已补充
Debug.md(本页)分层定位、绘图调试、控制台命令、可视化工具总览已补充

阅读顺序与优先级

顺序笔记什么时候读
1本页的"分层"任何问题先分层
2日志与断言体系写代码时就要用对(尤其是 check vs ensure)
3Visual Logger 与 Gameplay Debugger逻辑"没按我想的做"时
4崩溃与 Dump崩溃时

只有十分钟:stat unit 分层 + ensure 代替 check 处理可恢复错误。

分层:先定位在哪一层

现象先看
帧率低Profile:stat unit 判断是 Game / Draw / GPU
逻辑不对断点 + 日志
客户端看到的不对网络复制:判断是没复制还是算错了
崩溃调用栈 + 崩溃符号
视觉异常调试视图(Rendering 各视图)

第一件事永远是 stat unit:它把帧时间分成 Game / Draw / GPU 三段,直接决定后面往哪个方向查。

绘图调试

DrawDebugLine(World, Start, End, FColor::Red, false, 2.f);
DrawDebugSphere(World, Center, Radius, 16, FColor::Green, false, 1.f);
DrawDebugString(World, Loc, TEXT("here"), nullptr, FColor::White, 0.f);
函数用途
DrawDebugLine / Point / Sphere / Box可视化射线、判定范围
DrawDebugString在世界中写字
FlushPersistentDebugLines清除持久线条
GEngine->AddOnScreenDebugMessage屏幕输出

注意:Debug 绘制在 Shipping 包里会被剔除,且大量绘制本身也会影响性能,别留在正式代码里。

日志

UE_LOG(LogTemp, Warning, TEXT("Health = %f"), Health);
宏说明
UE_LOG(Category, Verbosity, Format, ...)分级日志
ensure(expr)首次触发时报错并生成调用栈,不中断
check(expr)失败即中断(Shipping 里被剔除)
verify(expr)与 check 类似但表达式始终求值
ensureMsgf / checkf带信息

自定义日志分类:

DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All);
DEFINE_LOG_CATEGORY(LogMyGame);

用独立分类而不是 LogTemp:可以按分类过滤,调试效率差很多。

控制台命令

命令作用
stat unit / stat game / stat gpu性能统计
show collision / show navigation显示调试几何
showdebug <类别>各类调试信息(如 showdebug abilitysystem)
DisplayAll <Class> <Property>实时显示某类对象的属性
obj gc强制 GC
p.NetCorrections / net.*网络调试
ai.debug.*AI 调试
Log LogMyGame Verbose调整日志级别

DisplayAll 与 showdebug abilitysystem 在查状态不同步时非常有用。

可视化工具

工具用途
Visual Logger时间轴上记录并回放 AI/游戏事件
Replay / Rewind Debugger录制并重放,回溯状态
Session Frontend / Profiler抓取与分析性能数据
行为树调试面板看当前节点与黑板
Network Profiler分析复制流量

Visual Logger 是 AI 调试的利器:UE_VLOG 记录事件,事后回放查看"当时 AI 为什么这么决定"。

崩溃与栈

做法说明
保留符号文件(PDB)发布时保存,否则崩溃栈无法解读
Crash Report Client自动收集
ensure 代替直接崩溃现场保留,便于继续排查
加壳/混淆要留符号映射否则线上崩溃读不懂

常见坑

坑说明
只靠 UE_LOG 排复杂问题用 Visual Logger / Rewind Debugger 更高效
Debug 绘制留在正式代码Shipping 无效果但代码与维护成本还在
没保留符号线上崩溃查不了
用 check 处理可恢复错误直接崩;应用 ensure 或错误处理