Debug
自动关联目录:Debug
调试能力的价值在于缩短"现象 → 原因"的距离。UE 提供了很丰富的手段,关键是知道什么时候用哪个。
本目录
| 笔记 | 内容 | 状态 |
|---|---|---|
| 崩溃与 Dump | 崩溃类型、符号与栈还原、平台工具、稳定性工具 | 已补充 |
| 日志与断言体系 | UE_LOG、check/verify/ensure 的选择、日志分类与级别 | 已补充 |
| Visual Logger 与 Gameplay Debugger | 事后回放与实时状态,UE_VLOG 打点 | 已补充 |
Debug.md(本页) | 分层定位、绘图调试、控制台命令、可视化工具总览 | 已补充 |
阅读顺序与优先级
| 顺序 | 笔记 | 什么时候读 |
|---|---|---|
| 1 | 本页的"分层" | 任何问题先分层 |
| 2 | 日志与断言体系 | 写代码时就要用对(尤其是 check vs ensure) |
| 3 | Visual 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 或错误处理 |
许可协议:CC BY
作者:Davids
本文链接:https://hustjjd.github.io/ad6468a3.html
更新于:2026年11月16日