如果你正在学习虚幻引擎C开发或者已经写过一些UEC代码那么下面这个场景你一定不陌生你写了一个复杂的Actor组件在运行时却没有任何反应。你怀疑某个函数没被调用某个变量没被正确赋值或者某个条件分支走错了。你打开编辑器运行游戏然后……一片寂静。你不知道代码执行到了哪里也不知道内部状态是什么。你只能一遍遍地加断点、重新编译、启动游戏效率低得让人抓狂。这就是为什么日志Log是UEC开发中最重要的调试工具没有之一。很多新手开发者会忽略它觉得有断点调试就够了。但实际上在虚幻引擎这种大规模、多线程、蓝图与C混合的复杂环境中日志是你洞察系统运行、定位线上问题、甚至进行性能分析的“眼睛”。然而UEC的日志系统并不像标准C的printf或std::cout那么简单直接。它有两套看似相似、实则用途迥异的日志体系UE_LOG和GEngine-AddOnScreenDebugMessage。用错了地方轻则信息混乱、难以查找重则影响性能、干扰正式版本。本文将彻底讲清楚这两套日志系统的核心区别、适用场景、详细用法以及实战中的最佳实践。读完本文你将能精准选择在任何场景下都能立刻判断该用UE_LOG还是屏幕日志。高效输出掌握格式化输出、分类管理、条件编译等高级技巧让日志信息清晰可读。实战排错通过几个真实的开发案例学会用日志快速定位和解决常见Bug。优化工程了解如何管理日志级别、避免性能陷阱为项目构建健壮的日志体系。我们直接从最核心的区别开始。1. 核心抉择UE_LOG与屏幕日志到底该用谁很多教程会把两者混为一谈这是最大的误区。它们的设计目标和使用场景完全不同。UE_LOG写给开发者和机器的“档案”本质将结构化的文本信息写入到日志文件如YourProjectName.log和输出日志窗口。特点持久化、可搜索、可分类、支持多种严重级别。它是你事后分析问题、监控程序状态、进行性能剖析的基石。类比就像飞机的“黑匣子”或服务器的系统日志记录一切以供查阅。GEngine-AddOnScreenDebugMessage写给玩家的“即时贴”本质在游戏运行画面的指定位置临时显示一段文本信息。特点实时、可视化、短暂存在可设置显示时间。主要用于调试时快速查看变量值、验证逻辑流程。类比就像赛车游戏里的实时速度表或调试信息叠加层看一眼就知道当前状态。用一个简单的表格来对比特性UE_LOGGEngine-AddOnScreenDebugMessage输出目标日志文件、输出日志窗口游戏画面屏幕持久性持久化保存临时显示默认2秒主要用途调试、监控、错误报告、性能分析运行时快速可视化调试使用场景任何需要记录的时刻实时查看变量、验证动画状态、调试物理等性能影响低可控制级别中涉及渲染文本是否依赖GEngine否是仅在游戏运行时有效核心判断如果你需要记录信息以备后续查看分析用UE_LOG如果你只想在游戏运行时看一眼某个值用屏幕日志。永远不要用屏幕日志来替代UE_LOG进行错误记录或状态跟踪。2.UE_LOG深入解析从基础到高级2.1 基础语法与日志类别最基本的UE_LOG宏看起来像这样// 在某个类的成员函数中例如 AMyActor::BeginPlay() UE_LOG(LogTemp, Warning, TEXT(MyActor %s 已开始播放。), *GetName());我们来拆解这个宏的三个参数LogTemp日志类别Log Category。这是UEC日志系统的核心设计用于对日志进行分类和过滤。LogTemp是一个预定义的、通用的临时日志类别。对于正式项目你应该创建自己的日志类别。Warning日志级别Log Verbosity。它定义了这条信息的重要性。级别从低到高包括Log 最低级别通常用于最详细的跟踪信息。Verbose 详细信息。Display 普通显示信息。Warning警告。表示可能有问题但程序仍可继续运行。这是你最常用的调试级别。Error错误。表示发生了错误功能可能受损。Fatal致命错误。记录后会调用FatalError可能导致程序崩溃。慎用。格式化字符串使用TEXT()宏包裹字符串以支持Unicode。支持类似printf的格式化占位符如%s(FString),%d(int),%f(float) 等。注意FString需要先用*操作符解引用。2.2 创建自定义日志类别总是用LogTemp会让你的日志文件变得混乱不堪。创建自定义类别很简单// 在全局头文件如 YourProjectName.h或某个模块的头文件中定义 DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All); // 在对应的 .cpp 文件中实现 DEFINE_LOG_CATEGORY(LogMyGame);现在你就可以在自己的代码中使用了UE_LOG(LogMyGame, Warning, TEXT([玩家状态] 玩家 %s 的生命值已更新为%d), *PlayerName, CurrentHealth);这样做的好处是你可以在编辑器或命令行中单独启用或禁用LogMyGame类别的日志而不会影响其他系统如引擎或插件的日志输出。2.3 高级格式化与输出技巧UE_LOG支持丰富的格式化输出能清晰展示复杂数据结构。输出FVector、FRotator等常见结构体FVector PlayerLocation GetActorLocation(); FRotator PlayerRotation GetActorRotation(); UE_LOG(LogMyGame, Display, TEXT(玩家位置: %s, 旋转: %s), *PlayerLocation.ToString(), *PlayerRotation.ToString()); // 输出示例玩家位置: X1200.0 Y350.0 Z90.0, 旋转: P0.0 Y90.0 R0.0输出TArray等容器TArrayFString ItemNames GetInventoryItemNames(); FString AllItems FString::Join(ItemNames, TEXT(, )); UE_LOG(LogMyGame, Verbose, TEXT(背包物品列表: %s), *AllItems);使用UE_LOG进行简单的性能计时void UMyComplexComponent::PerformExpensiveCalculation() { FScopeLogTime Logger(TEXT(PerformExpensiveCalculation), nullptr, LogMyGame, Verbose); // ... 这里执行耗时的计算 ... // 函数结束时会自动输出执行耗时例如LogMyGame: [PerformExpensiveCalculation] 12.34ms }3. 屏幕日志 (GEngine-AddOnScreenDebugMessage) 实战指南屏幕日志的核心优势是“所见即所得”但它有几个关键限制和技巧。3.1 基本使用与关键参数// 确保 GEngine 有效在游戏运行时 if (GEngine) { // 在屏幕左上角(位置Key-1)显示一条信息显示4秒颜色为绿色字体缩放1.0 GEngine-AddOnScreenDebugMessage( -1, // Key: 如果使用非负Key相同Key的新信息会覆盖旧信息。-1表示总是添加新行。 4.0f, // 显示时间秒 FColor::Green, // 文本颜色 TEXT(敌人进入了警戒状态) // 要显示的文本 ); }关键参数解析Key 这是最容易被忽略但极其有用的参数。如果你希望某个信息如玩家当前血量始终在固定位置更新而不是不断添加新行就给它一个唯一的非负Key如0。// 在Key0的位置持续更新血量信息 GEngine-AddOnScreenDebugMessage(0, 0.1f, FColor::White, FString::Printf(TEXT(HP: %d / %d), CurrentHealth, MaxHealth)); // 每次调用都会更新Key0位置的内容而不会产生滚动。DisplayTime 设置太短可能看不清设置太长又会覆盖屏幕。调试变量时0.5f - 2.0f比较合适显示重要事件可以更长。3.2 屏幕日志的局限性依赖GEngine 在游戏启动前如某些静态初始化或关闭后调用会导致崩溃。务必用if (GEngine)保护。仅限游戏视图 在编辑器模式PIE的游戏视口中可见但在编辑器UI或其他窗口不可见。性能开销 每帧渲染大量文本会影响性能。切忌在Tick函数中无节制地使用。信息过载 屏幕空间有限同时显示太多信息会变得毫无意义。3.3 实用技巧创建辅助调试函数为了避免重复代码和条件编译可以创建一个简单的辅助函数// MyDebugHelper.h #pragma once #include Engine/Engine.h class MYGAME_API FMyDebugHelper { public: static FORCEINLINE void ScreenLog(const FString Message, float Time 2.0f, FColor Color FColor::White, int32 Key -1) { #if !UE_BUILD_SHIPPING // 仅在非发布版本中编译 if (GEngine) { GEngine-AddOnScreenDebugMessage(Key, Time, Color, Message); } #endif } static FORCEINLINE void ScreenLogf(float Time, FColor Color, const TCHAR* Fmt, ...) { #if !UE_BUILD_SHIPPING if (GEngine) { va_list Args; va_start(Args, Fmt); FString FormattedText FString::Printf(Fmt, Args); va_end(Args); GEngine-AddOnScreenDebugMessage(-1, Time, Color, FormattedText); } #endif } }; // 使用示例 FMyDebugHelper::ScreenLog(TEXT(对象被创建)); FMyDebugHelper::ScreenLogf(2.0f, FColor::Yellow, TEXT(坐标: X%.1f, Y%.1f), Location.X, Location.Y);注意#if !UE_BUILD_SHIPPING的使用这确保了屏幕日志代码在发布版本中会被完全移除避免任何性能和安全风险。4. 完整实战案例用日志调试一个常见的AI行为问题假设我们有一个简单的敌人AI它应该在一定距离内发现玩家并开始追击。但发现它有时毫无反应。问题代码简化版// AMyEnemy.cpp void AMyEnemy::Tick(float DeltaTime) { Super::Tick(DeltaTime); AMyCharacter* Player GetPlayerCharacter(); // 假设这个函数能获取玩家 if (Player) { float Distance FVector::Dist(GetActorLocation(), Player-GetActorLocation()); if (Distance SightRadius) { // 发现了玩家 MoveToActor(Player); } } }第一步用UE_LOG记录关键状态和流程我们在关键位置添加日志了解代码是否执行、数据是否正确。void AMyEnemy::Tick(float DeltaTime) { Super::Tick(DeltaTime); UE_LOG(LogMyGame, Verbose, TEXT([%s] Tick 被调用), *GetName()); AMyCharacter* Player GetPlayerCharacter(); if (Player) { UE_LOG(LogMyGame, Verbose, TEXT([%s] 成功获取到玩家引用: %s), *GetName(), *Player-GetName()); float Distance FVector::Dist(GetActorLocation(), Player-GetActorLocation()); UE_LOG(LogMyGame, Display, TEXT([%s] 与玩家距离: %.2f (视觉半径: %.2f)), *GetName(), Distance, SightRadius); if (Distance SightRadius) { UE_LOG(LogMyGame, Warning, TEXT([%s] 发现玩家开始追击。), *GetName()); MoveToActor(Player); } else { UE_LOG(LogMyGame, Verbose, TEXT([%s] 玩家在视觉范围外。), *GetName()); } } else { // 这是关键如果获取不到玩家AI就不会工作。 UE_LOG(LogMyGame, Error, TEXT([%s] 错误无法获取玩家角色), *GetName()); } }第二步用屏幕日志实时可视化距离为了更直观地看到距离变化我们在屏幕上也显示信息。void AMyEnemy::Tick(float DeltaTime) { Super::Tick(DeltaTime); // ... 前面的 UE_LOG 代码保持不变 ... if (Player) { float Distance FVector::Dist(GetActorLocation(), Player-GetActorLocation()); // 使用屏幕日志实时显示距离Key100 确保信息在同一位置更新 if (GEngine) { FColor DistColor (Distance SightRadius) ? FColor::Green : FColor::Red; GEngine-AddOnScreenDebugMessage(100, 0.05f, DistColor, FString::Printf(TEXT([%s] 距玩家: %.1f), *GetName(), Distance)); } // ... 后续判断逻辑 ... } }第三步运行与分析运行游戏观察输出日志窗口和游戏屏幕。场景A敌人静止不动。日志输出你发现大量[Enemy1] 错误无法获取玩家角色的Error级别日志。屏幕显示可能没有距离信息因为Player为空。结论问题出在GetPlayerCharacter()函数。它可能返回了nullptr。你需要检查这个函数的实现或者玩家Pawn是否被正确设置。场景B敌人偶尔动一下。日志输出你看到距离在SightRadius上下波动发现玩家的日志时有时无。屏幕显示距离数字在红绿之间频繁切换。结论逻辑基本正确但可能因为网络延迟、Tick频率或玩家移动速度导致检测不稳定。你可能需要增加一个“确认发现”的延迟计时器或者调整SightRadius。通过这个案例你可以看到UE_LOG用于记录完整的诊断历史而屏幕日志用于提供实时反馈两者结合能极大提升调试效率。5. 日志配置、过滤与高级管理5.1 在编辑器中控制日志输出在虚幻编辑器的“输出日志”窗口你可以直接输入命令过滤日志Log MyGame 只显示LogMyGame类别的日志。Log MyGame Warning 只显示LogMyGame类别下Warning及以上级别的日志。Log MyGame Verbose 显示LogMyGame的所有日志包括最详细的Verbose。Log All 显示所有日志可能会非常嘈杂。5.2 通过配置文件控制日志DefaultEngine.ini对于测试或打包版本你可以在配置文件中预设日志级别无需修改代码。; DefaultEngine.ini [Core.Log] ; 全局设置所有日志类别默认只显示 Warning 及以上级别 LogWarning ; 针对特定日志类别的详细设置 Log.MyGameVerbose ; 允许 MyGame 输出 Verbose 级别 Log.PhysicsError ; Physics 只输出 Error 和 Fatal Log.NetworkingLog ; Networking 输出所有级别非常详细5.3 使用命令行参数控制日志在启动游戏时通过命令行参数可以动态控制-LogCmdsLog MyGame Verbose 启动时即开启LogMyGame的详细日志。-NoLog 完全禁用所有日志输出用于性能测试。6. 常见问题与排查清单问题现象可能原因排查方式解决方案UE_LOG没有任何输出1. 日志级别设置过高。2. 日志类别被过滤。3. 代码没有被执行。1. 检查输出日志窗口的过滤设置。2. 尝试使用LogTemp和Warning级别测试。3. 在函数入口添加日志确认函数被调用。1. 在编辑器输入Log All查看所有日志。2. 确保使用正确的级别如Warning。3. 检查代码逻辑和调用堆栈。屏幕日志不显示1.GEngine为空非游戏运行时。2. 显示时间太短。3. 被其他屏幕信息覆盖。1. 用if (GEngine)包裹调用。2. 增加DisplayTime参数。3. 使用唯一的Key值避免覆盖。1. 确保在游戏运行时如BeginPlay之后调用。2. 使用ScreenLog辅助函数并检查条件编译。日志文件找不到或为空1. 项目未正确生成日志。2. 日志路径不对。3. 日志被其他进程锁定。1. 在编辑器运行游戏查看“输出日志”是否有内容。2. 日志文件通常在Saved/Logs/目录下。3. 关闭编辑器再查看文件。1. 确认项目配置正确。2. 使用FPlatformMisc::GetAbsoluteLogFilename()获取完整路径。UE_LOG格式化字符串崩溃1. 格式化符号与参数类型不匹配。2.FString未用*解引用。仔细检查UE_LOG行对照每个占位符和参数。对于FString使用%s和*int用%dfloat用%f。发布版本中仍有调试日志未使用#if !UE_BUILD_SHIPPING等宏保护调试日志。检查代码中所有UE_LOG和屏幕日志调用。对纯调试用的日志尤其是Verbose,Log级别用条件编译宏包裹。7. 最佳实践与工程化建议尽早并频繁地使用日志不要等到出问题再加。在关键函数入口、状态改变、网络事件、错误处理处添加日志构建代码的“可观测性”。创建有意义的日志类别按功能模块划分如LogMyGameAI,LogMyGameInventory,LogMyGameNetwork。便于过滤和管理。选择合适的日志级别Fatal/Error 仅用于不可恢复的错误。Warning调试的主力用于潜在问题和重要状态变更。Display 一般性信息如“关卡加载完成”。Verbose/Log 最详细的跟踪信息发布前务必关闭。结构化日志信息在日志消息中包含上下文如对象名、时间戳、状态值。例如[PlayerController_1][WeaponSwitch] 从 Rifle 切换到 Shotgun。区分调试日志与运营日志调试日志用于开发期排错可以用条件编译移除。运营日志如玩家行为、经济系统可能需要持久化到数据库或日志服务需要更稳固的设计。性能意识避免在Tick或高频循环中输出Verbose级别日志。字符串拼接如FString::Printf也有开销。为屏幕日志设定规则使用唯一的Key来更新信息而不是创建滚动列表。为不同类型的信息分配不同的屏幕区域通过Key和自定义位置计算。发布版本前必须确保所有屏幕日志调用被条件编译宏移除。建立日志审查习惯在测试时定期查看保存的.log文件。学会从日志中还原程序执行流程。掌握UEC的日志系统远不止是学会两个API的调用。它代表了一种系统化的调试思维和工程习惯。UE_LOG是你的持久化诊断工具用于事后分析和监控屏幕日志是你的实时可视化助手用于快速验证和调试。从今天起尝试在你的下一个UEC类中有意识地运用这两种日志在类的头文件中定义专属的日志类别如LogMyAwesomeComponent。在BeginPlay、关键状态转换和错误处理处添加Warning级别的UE_LOG。在需要实时观察变量如速度、血量、技能冷却时使用带唯一Key的屏幕日志。在打包发布前检查并确保所有Verbose日志和屏幕日志已被适当条件编译或关闭。当你养成了这种“日志驱动”的开发习惯你会发现大部分Bug的定位时间会大幅缩短你对代码运行时的理解也会更加深刻。这或许是成为一名高效虚幻引擎C开发者最重要也最容易被低估的一项技能。