UE5调试实战：UE_LOG与屏幕打印的进阶应用与性能优化

1. 项目概述为什么UE_LOG和屏幕打印是UE5调试的“瑞士军刀”在虚幻引擎5UE5的开发过程中无论你是刚入门的新手还是已经摸爬滚打多年的老手调试都是绕不开的核心环节。项目标题里提到的“调试神器”绝非夸大其词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)这是最容易被忽略但极其有用的参数。它代表这条消息的唯一标识符。默认用法-1Key -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));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 TMapint32, FDebugTextItem DebugTextMap; static FCriticalSection DebugTextCriticalSection; // 线程安全考虑 }; // DebugHUD.cpp #include DebugHUD.h #include Engine/Engine.h TMapint32, 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; TArrayint32 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 TMapint32, 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 AIPhysics // 显示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 TAutoConsoleVariableint32 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的永久性消息TimeToDisplay0如果对应的逻辑对象已被销毁消息会残留在屏幕上。一个好的习惯是在对象的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到有策略、有层次、有颜色地输出信息这正是从一个代码编写者走向系统思考者的重要一步。