1. 项目概述：为什么UE_LOG和屏幕打印是UE5调试的“瑞士军刀”？
在虚幻引擎5（UE5）的开发过程中，无论你是刚入门的新手，还是已经摸爬滚打多年的老手，调试都是绕不开的核心环节。项目标题里提到的“调试神器”绝非夸大其词，UE_LOG和屏幕打印消息（GEngine->AddOnScreenDebugMessage）这两样工具，就像是开发者口袋里的“瑞士军刀”——看似简单，但关键时刻总能派上大用场。它们不像断点调试那样需要暂停游戏，也不像蓝图调试那样局限于可视化脚本，它们提供了一种实时、动态、低侵入性的观察窗口，让你能在游戏运行时，清晰地看到代码内部的“心跳”与“脉搏”。
很多开发者，尤其是从蓝图转向C++或者刚开始接触UE5底层逻辑的朋友，常常会陷入一种困境：代码编译通过了，游戏也能跑起来，但逻辑就是不对。变量值是不是传错了？这个函数到底有没有被调用？循环执行了几次？这时候，如果只会用断点，效率会很低，特别是对于一些偶发性问题或者需要观察连续状态变化的场景。而UE_LOG和屏幕打印，恰恰弥补了这个缺口。UE_LOG负责将信息记录到后台的日志文件和控制台，适合追踪详细的执行流水线，方便事后复盘；屏幕打印则直接把关键信息“怼”到你的游戏画面上，让你在测试时一目了然，实现真正的“所见即所得”调试。
我见过不少项目，因为初期没有建立良好的日志规范，到了后期排查一个线上问题，犹如大海捞针。也见过一些团队，巧妙利用不同颜色的屏幕消息，快速定位了渲染线程、游戏线程的逻辑冲突。所以，掌握并善用这两项基础技能，不仅仅是学会几个API调用，更是构建一种高效、可追溯的调试思维。接下来，我们就深入这把“瑞士军刀”的每一个细节，从原理到实操，从基础调用到高阶技巧，让你彻底玩转UE5的日志与屏幕调试系统。
2. UE_LOG深度解析：从基础打印到自定义日志系统
UE_LOG是虚幻引擎C++代码中最基础、最强大的日志输出宏。它的核心作用是将格式化的文本信息输出到两个地方：一是编辑器的“输出日志”（Output Log）窗口，二是项目目录下Saved/Logs文件夹中的文本文件。这种双轨记录机制，保证了信息既能在开发时实时查看，也能在事后离线分析。
2.1 UE_LOG的基本语法与参数详解
一个标准的UE_LOG宏调用看起来是这样的：
UE_LOG(LogTemp, Warning, TEXT("Character %s took %f damage."), *CharacterName, DamageAmount);我们来拆解它的四个核心部分（实际上是三个参数，但格式化字符串后可以跟多个变量）：
日志类别（Log Category）：第一个参数，示例中的
LogTemp。这是日志的分组标签。引擎内置了很多类别，如LogNet（网络）、LogRender（渲染）等。使用LogTemp是一个快捷但不推荐长期使用的方式，因为它会把所有临时日志混在一起，不利于筛选。最佳实践是为你的模块定义专属的日志类别。日志详细级别（Log Verbosity）：第二个参数，示例中的
Warning。它决定了这条日志的“严重程度”和输出行为。它不是一个简单的字符串，而是ELogVerbosity枚举的值。级别从高到低包括：Fatal: 致命错误。打印此日志后程序会崩溃。慎用，仅用于无法恢复的严重错误。Error: 错误。红色文本，输出到控制台和日志文件。通常表示功能失效。Warning: 警告。黄色文本，输出到控制台和日志文件。表示可能存在潜在问题，但程序仍可运行。Display: 显示。灰色文本，输出到控制台和日志文件。用于重要的常规信息。Log: 日志。灰色文本，仅输出到日志文件，不在控制台显示。用于一般的调试信息。Verbose/VeryVerbose: 冗长信息。默认不在控制台显示，且需要命令行开启对应类别冗长模式后才会记录到文件。用于输出海量的、最细致的调试信息。
注意：级别不仅影响颜色和输出位置，更重要的是用于过滤。在打包发布版本时，可以通过配置将
Log及以下级别的日志完全禁用，从而避免性能损耗和敏感信息泄露。而Warning和Error通常会被保留，用于收集错误报告。格式化字符串（Format String）：第三个参数，用
TEXT()宏包裹的字符串。它支持类似C语言printf的格式说明符，但因为是TCHAR字符串（支持Unicode），所以是安全的。常见的说明符有：%s: 字符串（需要将FString用*操作符解引用）。%d,%i: 整数。%f: 浮点数。%x: 十六进制整数。%p: 指针地址。
可变参数（Variadic Arguments）：格式化字符串后面跟的参数，与格式说明符一一对应。这是将变量值注入日志的关键。
2.2 定义专属的日志类别
长期使用LogTemp就像把所有的工具扔进一个抽屉，找起来非常麻烦。定义自己的日志类别是项目规范化的第一步。
第一步，在头文件（通常是YourModuleName.h）中声明日志类别：
// YourModuleName.h #pragma once #include "CoreMinimal.h" // 声明日志类别 DECLARE_LOG_CATEGORY_EXTERN(LogYourModule, Log, All);这里DECLARE_LOG_CATEGORY_EXTERN的三个参数分别是：
LogYourModule: 你定义的类别名（建议以Log开头）。Log:默认的详细级别。这意味着当你用Log级别输出时，这条日志默认是启用的。你可以设为Verbose来让常规日志默认静默。All: 表示这个类别在所有配置（Debug, Development, Shipping）下都可用。你也可以指定为Debug等。
第二步，在源文件（通常是YourModuleName.cpp）中定义这个类别：
// YourModuleName.cpp #include "YourModuleName.h" // 定义日志类别 DEFINE_LOG_CATEGORY(LogYourModule);第三步，在代码中使用：
UE_LOG(LogYourModule, Log, TEXT("Initializing YourModule...")); UE_LOG(LogYourModule, Warning, TEXT("Invalid configuration detected for %s"), *ConfigName);这样做的好处是，你可以在编辑器输出日志窗口的筛选栏中直接输入LogYourModule，只查看与你模块相关的日志，极大提升了排查效率。
2.3 高级用法与性能考量
结构化日志 UE_LOGFMT (UE5.2+)从UE5.2开始，引入了更安全的UE_LOGFMT宏。它使用花括号{}作为占位符，能避免传统%s、%d容易造成的参数类型不匹配或数量不一致导致的崩溃风险。
// 位置参数方式 UE_LOGFMT(LogYourModule, Warning, "Player {PlayerName} with health {Health} joined", PlayerName, CurrentHealth); // 具名参数方式（更清晰，顺序无关） UE_LOGFMT(LogYourModule, Warning, "Player {PlayerName} joined", ("PlayerName", PlayerName), ("Health", CurrentHealth), ("Weapon", EquippedWeaponName) // 额外字段也会被记录 );结构化日志的另一个优势是便于后续的日志分析工具进行解析和检索。
性能注意事项日志输出本身有开销，尤其是在循环中输出Verbose级别的日志。
- 使用日志级别进行控制：确保在
Shipping等最终版本中，通过引擎的日志系统配置，关闭Verbose、VeryVerbose甚至Log级别。 - 避免在热路径中构建复杂字符串：
FString的拼接操作（如FString::Printf）在频繁调用的函数中可能成为性能瓶颈。有时可以先检查日志级别是否启用：if (UE_LOG_ACTIVE(LogYourModule, Verbose)) { FString ComplexInfo = FString::Printf(TEXT("Complex object state: ..."), ...); UE_LOG(LogYourModule, Verbose, TEXT("%s"), *ComplexInfo); }UE_LOG_ACTIVE宏会在日志级别未启用时提前返回，避免不必要的字符串构建开销。
控制台命令动态控制日志你可以在游戏运行时通过控制台命令动态调整日志的冗长度，这对调试线上问题或特定模块的问题非常有用。
// 在编辑器控制台或游戏内控制台（~键）输入 Log LogYourModule Verbose // 开启LogYourModule类别的Verbose级别输出 Log LogYourModule Log // 关闭Verbose，只显示Log及以上级别 Log LogYourModule Off // 完全关闭LogYourModule类别的所有日志这个功能让你无需重新编译代码，就能即时获得更详细的调试信息。
3. 屏幕打印消息实战：让调试信息一目了然
如果说UE_LOG是写给“后台”（日志文件）看的日记，那么屏幕打印消息就是直接贴在“舞台”（游戏画面）上的即时贴。它通过GEngine->AddOnScreenDebugMessage函数实现，将信息实时渲染在游戏视口上，对于调试游戏逻辑、动画状态、物理效果等需要视觉反馈的场景，效率极高。
3.1 核心函数拆解与参数活用
屏幕打印的核心函数原型如下（通常通过GEngine单例调用）：
if (GEngine) { GEngine->AddOnScreenDebugMessage( Key, // 参数1：消息键值（用于防止重复） TimeToDisplay, // 参数2：显示时间（秒） DisplayColor, // 参数3：显示颜色 DebugMessage, // 参数4：调试消息字符串 bNewerOnTop, // 参数5：是否将新消息置顶（可选，默认false） ReplacementScale // 参数6：文本缩放（可选，默认FVector2D(1.0f, 1.0f)） ); }参数深度解读与实战技巧：
Key (int32)：这是最容易被忽略但极其有用的参数。它代表这条消息的唯一标识符。
- 默认用法（-1）：
Key = -1表示每次调用都生成一条新的消息，旧消息不会被覆盖。这会导致屏幕上消息不断堆积，最终变得混乱不堪。仅在临时、一次性调试时使用。 - 推荐用法（指定正整数）：为每一类你想持续跟踪的信息分配一个固定的
Key值。例如，用1代表玩家血量，2代表玩家位置，3代表当前状态。当用相同Key调用时，新消息会直接覆盖旧消息。这样，屏幕上只会保持最新的一条玩家血量、一条位置信息，非常清晰。
// 在Tick函数中持续更新玩家位置，屏幕上始终只有一条位置信息 GEngine->AddOnScreenDebugMessage(1, 0.0f, FColor::Green, FString::Printf(TEXT("Pos: X=%.1f, Y=%.1f, Z=%.1f"), GetActorLocation().X, GetActorLocation().Y, GetActorLocation().Z));- 默认用法（-1）：
TimeToDisplay (float)：消息在屏幕上停留的秒数。
0.0f：表示消息永久显示，直到被相同Key的新消息覆盖，或者用GEngine->RemoveOnScreenDebugMessage(Key)手动移除。适合用于需要持续监控的变量。5.0f：显示5秒后自动消失。适合用于提示一次性事件，如“拾取物品”、“技能释放”。- 技巧：可以将此参数与游戏状态关联。例如，在调试模式下设为
0.0f永久显示，在常规游戏中设为2.0f短暂提示。
DisplayColor (FColor)：消息的颜色。这是让屏幕调试信息变得直观的关键。
FColor预定义了大量颜色常量，如FColor::Red、FColor::Green、FColor::Yellow、FColor::Cyan等。- 颜色分类策略：建立一套颜色规范能大幅提升调试效率。例如：
FColor::Red：用于错误、异常状态（如血量低于零、资源加载失败）。FColor::Yellow：用于警告、需要注意的状态（如弹药不足、技能冷却中）。FColor::Green：用于正常、成功状态（如任务完成、连接成功）。FColor::Cyan或FColor::Blue：用于信息显示（如坐标、速度、帧率）。FColor::White或FColor::Silver：用于普通的调试信息。
- 自定义颜色：你也可以使用
FColor(255, 100, 0)这样的RGB值来创建自定义颜色，用于区分更细的类别。
- 颜色分类策略：建立一套颜色规范能大幅提升调试效率。例如：
DebugMessage (const FString&)：要显示的字符串。和
UE_LOG一样，可以使用FString::Printf来格式化变量。- 性能提示：由于屏幕打印每帧都可能调用（如在
Tick中），应避免在字符串中频繁进行复杂的计算或字符串拼接。可以考虑在条件判断后再构建字符串。
- 性能提示：由于屏幕打印每帧都可能调用（如在
bNewerOnTop (bool)：可选参数，默认为
false。当为true时，新消息会添加到屏幕消息列表的顶部（上方）。当为false时，新消息添加到底部（下方）。根据你的阅读习惯和消息重要性来设置。ReplacementScale (FVector2D)：可选参数，用于缩放文本大小。
FVector2D(2.0f, 2.0f)会使文本变大两倍。在4K等高分辨率屏幕上，适当调大文本可以看得更清楚。
3.2 构建一个实用的屏幕调试信息管理器
直接在游戏角色的Tick函数里到处写AddOnScreenDebugMessage会让代码变得混乱。一个更好的做法是创建一个简单的调试信息管理器。这里提供一个思路：
// DebugHUD.h #pragma once #include "CoreMinimal.h" #include "GameFramework/HUD.h" #include "DebugHUD.generated.h" UCLASS() class YOURPROJECT_API ADebugHUD : public AHUD { GENERATED_BODY() public: virtual void DrawHUD() override; // 供其他类调用的静态函数 static void AddDebugText(int32 Key, const FString& Text, const FColor& Color = FColor::White, float Time = 0.0f); static void RemoveDebugText(int32 Key); private: struct FDebugTextItem { FString Text; FColor Color; float TimeRemaining; }; static TMap<int32, FDebugTextItem> DebugTextMap; static FCriticalSection DebugTextCriticalSection; // 线程安全考虑 }; // DebugHUD.cpp #include "DebugHUD.h" #include "Engine/Engine.h" TMap<int32, ADebugHUD::FDebugTextItem> ADebugHUD::DebugTextMap; FCriticalSection ADebugHUD::DebugTextCriticalSection; void ADebugHUD::DrawHUD() { Super::DrawHUD(); FScopeLock Lock(&DebugTextCriticalSection); float YOffset = 50.0f; // 起始Y坐标 const float LineHeight = 20.0f; TArray<int32> KeysToRemove; for (auto& It : DebugTextMap) { FDebugTextItem& Item = It.Value; // 绘制文本 DrawText(Item.Text, FColor::White, 50.0f, YOffset, GEngine->GetMediumFont(), 1.0f, false); // 或者用带背景的绘制，更清晰 // DrawRect(Item.Color, 50.0f, YOffset, Canvas->SizeX - 100.0f, LineHeight); // DrawText(Item.Text, FColor::Black, 55.0f, YOffset + 2.0f, GEngine->GetMediumFont(), 1.0f, false); YOffset += LineHeight; // 更新或移除过期消息 if (Item.TimeRemaining > 0.0f) { Item.TimeRemaining -= GetWorld()->GetDeltaSeconds(); if (Item.TimeRemaining <= 0.0f) { KeysToRemove.Add(It.Key); } } } for (int32 Key : KeysToRemove) { DebugTextMap.Remove(Key); } } void ADebugHUD::AddDebugText(int32 Key, const FString& Text, const FColor& Color, float Time) { FScopeLock Lock(&DebugTextCriticalSection); FDebugTextItem& Item = DebugTextMap.FindOrAdd(Key); Item.Text = Text; Item.Color = Color; Item.TimeRemaining = Time; // 0.0f 表示永久 } void ADebugHUD::RemoveDebugText(int32 Key) { FScopeLock Lock(&DebugTextCriticalSection); DebugTextMap.Remove(Key); }然后在游戏模式中设置使用这个ADebugHUD类。这样，任何地方的代码都可以通过ADebugHUD::AddDebugText(1, “Health: 100”, FColor::Green);来添加调试文本，所有绘制逻辑集中管理，更加清晰和高效。
3.3 屏幕消息与UE_LOG的协同作战
在实际调试中，UE_LOG和屏幕消息应该搭配使用，形成立体化的调试网络。
场景一：复现偶发崩溃在怀疑可能崩溃的函数调用前，同时使用
UE_LOG和屏幕消息。UE_LOG(LogGame, Warning, TEXT("[%s] Attempting to access invalid pointer.”), *GetName()); GEngine->AddOnScreenDebugMessage(999, 5.0f, FColor::Red, FString::Printf(TEXT(“WARNING: %s accessing pointer.”), *GetName())); // ... 可能崩溃的操作如果游戏崩溃了，屏幕消息能让你在崩溃前一刻看到提示。而
UE_LOG则会在日志文件中留下确切的记录，即使你没来得及看屏幕。场景二：调试复杂状态机在角色状态机的每个状态切换处，用不同颜色的屏幕消息显示当前状态，同时在
UE_LOG中记录状态切换的详细原因和上下文变量。void AMyCharacter::SetState(ECharacterState NewState) { FString StateName = UEnum::GetValueAsString(NewState); UE_LOG(LogGame, Log, TEXT(“Character %s state change: %s -> %s. Reason: %s”), *GetName(), *UEnum::GetValueAsString(CurrentState), *StateName, *StateChangeReason); FColor Color = FColor::White; switch(NewState) { case ECharacterState::Idle: Color = FColor::Green; break; case ECharacterState::Combat: Color = FColor::Red; break; case ECharacterState::Dead: Color = FColor::Gray; break; } GEngine->AddOnScreenDebugMessage(100, 0.0f, Color, FString::Printf(TEXT(“State: %s”), *StateName)); CurrentState = NewState; }这样，你既能实时看到角色头顶的状态标签（颜色区分），又能在日志中追溯状态变化的完整链条。
场景三：性能热点分析在怀疑性能问题的代码块前后，使用
UE_LOG记录时间戳（FPlatformTime::Seconds()），计算耗时。同时，在屏幕上用一个固定的Key来显示最近几帧的平均耗时或最大耗时，实时监控性能波动。// 在Tick函数中 static float MaxDeltaTime = 0.0f; static float LastLogTime = 0.0f; float CurrentTime = FPlatformTime::Seconds(); float DeltaTime = CurrentTime - LastFrameTime; if (DeltaTime > MaxDeltaTime) MaxDeltaTime = DeltaTime; // 每5秒在屏幕上更新一次最大耗时 if (CurrentTime - LastLogTime > 5.0f) { GEngine->AddOnScreenDebugMessage(200, 5.1f, FColor::Yellow, FString::Printf(TEXT(“Max Tick Delta (last 5s): %.4f ms”), MaxDeltaTime * 1000.0f)); UE_LOG(LogGame, Verbose, TEXT(“Performance Sample - Max Delta: %.4fms”), MaxDeltaTime * 1000.0f); MaxDeltaTime = 0.0f; LastLogTime = CurrentTime; } LastFrameTime = CurrentTime;
4. 颜色参数详解与视觉调试系统构建
颜色在调试中远不止是“好看”，它是一种高效的信息编码和过滤手段。正确地使用颜色，能让你的调试信息在瞬间传达出状态、严重性和类别。
4.1 FColor颜色系统全解析
FColor是UE中表示32位颜色的类（RGBA，各8位）。除了直接使用RGB值构造，引擎提供了丰富的预定义颜色常量。了解这些常量的视觉含义和适用场景非常重要。
| 预定义颜色 | RGB值 (近似) | 视觉印象 | 推荐调试用途 |
|---|---|---|---|
FColor::Red | (255, 0, 0) | 强烈、警示 | 错误、失败、致命状态。如：网络断开、资源加载失败、血量归零、无效操作。 |
FColor::Green | (0, 255, 0) | 安全、通过 | 成功、正常、可用状态。如：连接成功、任务完成、技能就绪、安全区域。 |
FColor::Yellow | (255, 255, 0) | 注意、警告 | 警告、需注意状态。如：弹药不足、技能冷却、接近边界、非致命异常。 |
FColor::Blue | (0, 0, 255) | 冷静、信息 | 一般信息、数据展示。如：玩家ID、坐标信息、版本号。在深色背景下很醒目。 |
FColor::Cyan | (0, 255, 255) | 清晰、突出 | 系统信息、调试数据。如：帧率(FPS)、内存使用、网络延迟。非常醒目。 |
FColor::Magenta | (255, 0, 255) | 醒目、特殊 | 特殊事件、测试标记。如：调试路径点、触发器激活、自定义测试流程。 |
FColor::White | (255, 255, 255) | 中性、标准 | 普通调试文本、默认信息。 |
FColor::Black | (0, 0, 0) | 对比 | 在浅色背景上绘制文字时使用，注意默认HUD背景可能是深色。 |
FColor::Gray | (128, 128, 128) | 次要、暗淡 | 次要信息、历史记录、低优先级日志。 |
FColor::Orange | (255, 165, 0) | 提醒、中间态 | 介于警告和正常之间。如：资源加载中、缓冲状态、中等威胁。 |
FColor::Purple | (128, 0, 128) | 独特、模块标识 | 用于标识特定子系统或模块的调试信息。 |
实操心得：颜色选择的三条军规
- 一致性原则：在整个项目或至少单个模块内，固定颜色代表的含义。例如，永远用红色表示“错误”，用黄色表示“警告”。这能形成肌肉记忆，一看颜色就知道大概是什么问题。
- 对比度原则：考虑游戏场景的背景色。如果你的游戏背景经常是蓝天（蓝色），那么用
FColor::Blue显示调试文本就会看不清。UE编辑器视图口的默认背景是深灰色，因此FColor::Cyan、FColor::Yellow、FColor::Green通常有较好的对比度。 - 克制原则：不要滥用颜色。如果满屏都是五颜六色的文字，反而会失去重点。重要的、需要立即关注的信息才用高亮色（红、黄、绿），常规信息用白色或灰色。
4.2 动态颜色与状态映射
更高级的用法是根据游戏状态或变量值动态计算颜色，这能让调试信息直接“可视化”数据。
示例1：根据血量比例改变颜色
float HealthPercent = CurrentHealth / MaxHealth; FColor HealthColor; if (HealthPercent > 0.6f) HealthColor = FColor::Green; else if (HealthPercent > 0.3f) HealthColor = FColor::Yellow; else HealthColor = FColor::Red; GEngine->AddOnScreenDebugMessage(10, 0.0f, HealthColor, FString::Printf(TEXT(“HP: %.0f/%.0f (%.0f%%)”), CurrentHealth, MaxHealth, HealthPercent * 100.0f));这样，血条的颜色会随着血量减少从绿变黄再变红，一目了然。
示例2：根据帧率(FPS)改变颜色
float CurrentFPS = 1.0f / DeltaTime; FColor FPSColor; if (CurrentFPS >= 55.0f) FPSColor = FColor::Green; else if (CurrentFPS >= 30.0f) FPSColor = FColor::Yellow; else FPSColor = FColor::Red; GEngine->AddOnScreenDebugMessage(20, 0.0f, FPSColor, FString::Printf(TEXT(“FPS: %.1f”), CurrentFPS));示例3：使用线性插值获得平滑过渡色
// 根据压力值(0-1)从蓝色过渡到红色 float Pressure = FMath::Clamp(SomePressureValue, 0.0f, 1.0f); FColor PressureColor = FLinearColor::LerpUsingHSV(FLinearColor::Blue, FLinearColor::Red, Pressure).ToFColor(true); GEngine->AddOnScreenDebugMessage(30, 0.0f, PressureColor, FString::Printf(TEXT(“Pressure: %.2f”), Pressure));4.3 构建分层级、可过滤的视觉调试系统
对于大型项目，调试信息可能非常多。我们可以借鉴日志级别的思想，为屏幕消息也设计一个“显示级别”系统。
// EDebugDisplayLevel.h UENUM(BlueprintType) enum class EDebugDisplayLevel : uint8 { None = 0, // 不显示 ErrorsOnly, // 只显示错误 Warnings, // 显示错误和警告 Important, // 显示错误、警告和重要信息 Verbose, // 显示所有信息 MAX }; // DebugDrawSubsystem.h (游戏实例子系统) UCLASS() class YOURPROJECT_API UDebugDrawSubsystem : public UGameInstanceSubsystem { GENERATED_BODY() public: static void AddDebugMessage(EDebugDisplayLevel Level, int32 Key, const FString& Text, const FColor& Color, float Time = 0.0f); static void SetGlobalDisplayLevel(EDebugDisplayLevel NewLevel); private: static EDebugDisplayLevel GlobalDisplayLevel; static TMap<int32, FDebugMessage> ActiveMessages; // ... 绘制和管理逻辑 }; // 使用示例 // 在某个游戏实例初始化时设置显示级别 UDebugDrawSubsystem::SetGlobalDisplayLevel(EDebugDisplayLevel::Important); // 在代码中添加消息 // 这条消息只有在显示级别 >= Important 时才会出现 UDebugDrawSubsystem::AddDebugMessage(EDebugDisplayLevel::Important, 1, TEXT(“Player entered combat.”), FColor::Yellow); // 这条详细的位置信息只有在Verbose级别才会显示 UDebugDrawSubsystem::AddDebugMessage(EDebugDisplayLevel::Verbose, 2, FString::Printf(TEXT(“Pos: %s”), *GetActorLocation().ToString()), FColor::Cyan);你甚至可以扩展这个系统，使其支持按频道（Channel）过滤，比如“网络频道”、“AI频道”、“物理频道”，并允许在游戏运行时通过控制台命令动态切换显示哪些频道的信息。
// 控制台命令 DebugDraw.Level Verbose // 设置显示级别为Verbose DebugDraw.Channel AI // 只显示AI频道的调试信息 DebugDraw.Channel AI+Physics // 显示AI和物理频道的调试信息通过构建这样的系统，你可以从容应对从开发初期到后期优化各个阶段的调试需求，在需要详细信息时打开“全频道Verbose模式”，在性能测试或演示时只保留关键的“ErrorsOnly模式”。
5. 常见问题排查与实战调试技巧实录
即使熟练掌握了UE_LOG和屏幕打印，在实际项目中还是会遇到各种稀奇古怪的问题。这一部分，我结合自己踩过的坑，总结了一些典型问题的排查思路和实战技巧。
5.1 为什么我的UE_LOG没有输出？
这是新手最常见的问题。请按以下清单逐一排查：
检查日志级别：你使用的日志级别（如
Verbose）可能默认被关闭。在编辑器输出日志窗口的左下角，确保你的日志类别（如LogYourModule）和对应的详细级别（如Verbose）复选框是勾选状态。或者，在游戏启动命令行中添加-LogCmds=“LogYourModule Verbose”。确认代码被执行：最根本的原因可能是包含
UE_LOG的那行代码根本没有运行。在它前面加一个必然执行的屏幕打印消息（AddOnScreenDebugMessage）或者一个更简单的UE_LOG(LogTemp, Error, …)来确认。在正确的环境中查看：
- 编辑器模式：日志输出到编辑器的“输出日志”窗口和
Saved/Logs/Editor.log。 - 独立游戏进程（Standalone Game）：日志输出到
Saved/Logs/YourGame.log。你需要用文本编辑器打开这个文件查看，或者启动时加上-log参数让日志也在单独的控制台窗口显示。 - 打包后（Shipping Build）：默认
Log及以下级别日志被禁用。你需要修改引擎或项目的日志配置来启用。注意：在Shipping版本中启用详细日志会影响性能。
- 编辑器模式：日志输出到编辑器的“输出日志”窗口和
字符串格式化错误：不正确的格式说明符会导致整个
UE_LOG调用被静默忽略，甚至崩溃。确保%s对应FString*（记得加*），%d对应整型，%f对应浮点型。多线程问题：在非游戏线程（如渲染线程、工作线程）中调用
UE_LOG是安全的，但输出可能会稍有延迟或顺序不一致。屏幕打印消息AddOnScreenDebugMessage则必须在游戏线程中调用，否则会导致崩溃或无法显示。
5.2 屏幕消息不显示或闪烁的排查
GEngine 为空：
AddOnScreenDebugMessage是通过全局的GEngine单例调用的。在非常早的初始化阶段（如某些静态初始化）或某些特定的子系统（非游戏线程）中，GEngine可能还未初始化或已销毁。务必在使用前检查if (GEngine)。// 绝对安全的调用方式 if (GEngine && GEngine->GameViewport && GEngine->GameViewport->GetWorld()) { GEngine->AddOnScreenDebugMessage(...); }Key值冲突与覆盖：如果你为不同的信息使用了相同的
Key值，后一条消息会覆盖前一条，造成“闪烁”或信息丢失的错觉。规划好你的Key值命名空间。可以按功能模块分配Key范围，例如：玩家相关（1000-1999）、AI相关（2000-2999）、系统相关（3000-3999）。显示时间（TimeToDisplay）问题：如果你在每帧的
Tick中都调用AddOnScreenDebugMessage，并且TimeToDisplay设置得较短（如0.1秒），那么消息会不断被刷新，看起来就像在闪烁。对于需要持续显示的信息，应该使用固定的Key和TimeToDisplay = 0.0f（永久），或者只在值真正发生变化时才更新消息。视口或HUD被覆盖：屏幕消息是渲染在游戏视口上的。如果全屏UI、过场动画、或者你自己的HUD绘制代码覆盖了同一区域，消息可能会被遮挡。尝试调整消息的起始Y坐标（通过自定义HUD绘制），或者检查UI的渲染深度。
5.3 性能优化与调试信息管理
调试信息本身不能成为性能瓶颈。
避免在Tick中构建复杂字符串：这是最常见的性能陷阱。特别是当Tick频率很高（如VR项目90Hz）时。
// 不佳的做法：每帧都进行字符串拼接和转换 void AMyActor::Tick(float DeltaTime) { Super::Tick(DeltaTime); FString ComplexString = FString::Printf(TEXT(“Pos: %s, Vel: %s, State: %d”), *GetActorLocation().ToString(), *GetVelocity().ToString(), (int32)CurrentState); GEngine->AddOnScreenDebugMessage(1, 0.0f, FColor::White, ComplexString); } // 改进的做法：只在数据变化时更新 void AMyActor::Tick(float DeltaTime) { Super::Tick(DeltaTime); FVector CurrentLocation = GetActorLocation(); if (!CurrentLocation.Equals(LastLoggedLocation, 1.0f)) // 位置变化超过1单位才更新 { GEngine->AddOnScreenDebugMessage(1, 0.0f, FColor::White, FString::Printf(TEXT(“Pos: X=%.1f, Y=%.1f, Z=%.1f”), CurrentLocation.X, CurrentLocation.Y, CurrentLocation.Z)); LastLoggedLocation = CurrentLocation; } }使用条件编译和配置控制：确保在最终发布版本中，大量的调试日志和屏幕绘制代码不会被编译进去或不会执行。
// 方法1：使用预处理器宏 #if !UE_BUILD_SHIPPING UE_LOG(LogGame, Verbose, TEXT(“Very detailed debug info: %s”), *DetailedInfo); if (GEngine) GEngine->AddOnScreenDebugMessage(...); #endif // 方法2：使用静态变量或CVar控制 static TAutoConsoleVariable<int32> CVarShowDebugInfo( TEXT(“ai.Debug”), 0, // 默认关闭 TEXT(“Show AI debug info on screen. 0:Off, 1:On”), ECVF_Cheat); // ECVF_Cheat 表示通常只在开发版本或作弊开启时可用 void AAIController::Tick(float DeltaTime) { Super::Tick(DeltaTime); if (CVarShowDebugInfo.GetValueOnGameThread() > 0) { // 绘制复杂的AI调试信息 } }通过控制台命令
ai.Debug 1即可在游戏中实时开启AI调试信息的显示。定期清理“僵尸”消息：对于使用固定
Key的永久性消息（TimeToDisplay=0），如果对应的逻辑对象已被销毁，消息会残留在屏幕上。一个好的习惯是在对象的BeginDestroy或EndPlay函数中，移除它注册的所有调试消息。void AMyDebugActor::EndPlay(const EEndPlayReason::Type EndPlayReason) { if (GEngine) { GEngine->RemoveOnScreenDebugMessage(MyDebugKey1); GEngine->RemoveOnScreenDebugMessage(MyDebugKey2); } Super::EndPlay(EndPlayReason); }
5.4 高级调试模式设计思路
将调试工具系统化，能极大提升团队效率。
创建调试命令菜单：在游戏中通过快捷键（如
~或F1-F12）呼出一个简单的调试菜单，可以快速开关各种调试信息：显示碰撞体、显示导航网格、显示AI感知刺激、显示网络同步状态等。每个选项对应一个Console Variable (CVar)。录制与回放调试信息：对于难以复现的Bug，可以设计一个简单的系统，将关键帧的调试信息（位置、状态、变量值）连同时间戳一起记录到内存或文件。当Bug发生时，保存这段记录。之后可以像播放录像一样，逐帧回放并查看当时的调试信息，结合引擎的
Take Recorder（场景录制）功能，效果更佳。远程调试信息显示：对于移动平台或VR设备，在设备屏幕上显示大量调试信息会影响体验且不便查看。可以建立一个简单的TCP/UDP服务器，让游戏将调试信息发送到同一网络下的PC端工具上显示。这对于调试性能问题或复杂逻辑尤其有用。
与蓝图调试的联动：在C++中暴露一些调试函数到蓝图，让策划和美术同学也能在需要时，通过蓝图节点触发特定的调试显示（如高亮某个NPC的路径、显示一个技能的作用范围）。这能促进不同职能的同事共同参与问题排查。
调试不仅仅是解决问题的工具，更是一种理解系统运行、验证设计假设的思维方式。将UE_LOG和屏幕打印消息用活、用好，建立起一套属于你自己或团队的调试规范，你会发现定位问题的速度会呈指数级提升。从在代码里漫无目的地Printf，到有策略、有层次、有颜色地输出信息，这正是从一个代码编写者走向系统思考者的重要一步。
