1. 项目概述为什么LogTemp不够用了在UE4/UE5项目里摸爬滚打过的开发者对UE_LOG(LogTemp, Warning, TEXT(“Hello World”))这行代码肯定不陌生。它就像我们初学编程时的printf(“Hello World”)简单直接是快速验证逻辑、输出调试信息的“万能钥匙”。但当你接手一个中型甚至大型项目或者开始构建自己的插件和模块时如果还在满世界用LogTemp那调试日志很快就会变成一场灾难。想象一下你的输出日志窗口里来自AI行为树、网络同步、资源加载、UI逻辑等不同系统的几百条警告和错误信息全都顶着同一个LogTemp的标签混杂在一起想要从中快速定位到“某个特定NPC的寻路失败”或者“某次网络RPC调用超时”的具体日志无异于大海捞针。这就是自定义日志分类存在的核心价值。它不仅仅是给日志换个名字而是对项目调试信息进行体系化、模块化管理的基础设施。通过为不同的系统、模块甚至类创建专属的日志分类你可以实现精准过滤在编辑器输出日志窗口或运行时控制台可以单独启用、禁用或设置特定分类的日志详细级别。比如你只想看网络相关的错误就只打开LogNet或你自定义的LogMyGameNet的Error级别。问题归因看到一条LogMyGameInventory的错误你立刻就知道问题出在背包系统而不是渲染或物理模块。性能优化在开发期你可以为调试模块开启Verbose级别输出海量细节在发布版本或性能测试时可以一键关闭所有非关键 (Display级别以下) 的日志输出避免日志打印本身成为性能瓶颈。团队协作清晰的日志分类是代码可读性和可维护性的一部分。新同事接手你的模块通过查看日志分类就能快速理解代码结构和数据流向。所以别再只满足于LogTemp了。接下来我将手把手带你从零开始为你的UE4/UE5项目创建、配置并高效使用自定义日志分类。我会提供完整的、可直接粘贴使用的代码示例并分享一些官方文档里不会写的实操技巧和避坑指南。2. 自定义日志分类的完整创建流程创建一个可用的自定义日志分类需要分别在头文件 (.h) 和源文件 (.cpp) 中进行声明和定义。下面我们以一个实战场景为例假设我们正在开发一个名为MyGame的项目其中有一个负责处理玩家技能系统的模块SkillSystem我们需要为它创建专属的日志分类LogMyGameSkill。2.1 头文件中的声明 (DECLARE_LOG_CATEGORY_EXTERN)首先在你技能系统模块的核心头文件中进行声明。通常这个头文件会被该模块的其他类广泛引用比如SkillSystem.h或MyGameSkillSystem.h。// SkillSystem.h #pragma once #include CoreMinimal.h // 声明日志分类的外部引用。 // 参数1: LogMyGameSkill - 我们自定义的分类名称建议以Log为前缀后接模块名清晰明了。 // 参数2: Warning - 该分类的**默认**日志详细级别。这里设为Warning意味着默认情况下Error和Warning级别的日志会输出。 // 参数3: All - 这是一个编译时标志通常保持为All即可表示在所有编译配置Debug, Development, Shipping等中都启用此分类的声明。 DECLARE_LOG_CATEGORY_EXTERN(LogMyGameSkill, Warning, All); class MYGAME_API USkillSystem : public UObject { GENERATED_BODY() // ... 你的技能系统类定义 };关键点解析DECLARE_LOG_CATEGORY_EXTERN这个宏告诉编译器“在其他地方通常是.cpp文件定义了一个名为LogMyGameSkill的日志分类对象我在这里声明要使用它”。这类似于用extern声明一个全局变量。第二个参数Verbosity这个Warning非常重要。它设定了这个日志分类的默认冗长度。它决定了在不进行额外配置的情况下哪些级别的日志会被实际输出。例如设置为Warning默认输出Fatal,Error,Warning级别的日志。Display,Log,Verbose级别的日志默认被抑制。设置为Display默认输出Fatal,Error,Warning,Display级别的日志。设置为Log默认输出Fatal,Error,Warning,Display,Log级别的日志。设置为Verbose默认输出Fatal,Error,Warning,Display,Log,Verbose级别的日志VeryVerbose仍被抑制。 开发期为了详细调试可以设为Verbose对于相对稳定、只需关注错误和警告的模块设为Warning或Error可以减少日志噪音。2.2 源文件中的定义 (DEFINE_LOG_CATEGORY)接下来在对应的源文件如SkillSystem.cpp中对这个日志分类进行实际的定义。// SkillSystem.cpp #include SkillSystem.h #include SomeOtherSkillClass.h // 其他可能需要日志的类 // 定义日志分类。 // 参数: LogMyGameSkill - 必须与头文件中声明的名称完全一致。 DEFINE_LOG_CATEGORY(LogMyGameSkill); // 类的实现... void USkillSystem::SomeFunction() { // 现在可以使用自定义分类了 UE_LOG(LogMyGameSkill, Display, TEXT(SkillSystem initialized successfully.)); if (bSomeErrorCondition) { UE_LOG(LogMyGameSkill, Error, TEXT(Failed to load skill data for ID: %d), SkillId); } }关键点解析DEFINE_LOG_CATEGORY这个宏在编译单元.cpp文件中实际创建了LogMyGameSkill这个全局日志分类对象。一个分类只需要被定义一次通常放在该模块最主要的或第一个被编译的源文件中。包含关系确保定义了该分类的.cpp文件被编译到你的模块中。只要你的模块依赖正确这通常不是问题。使用定义之后在这个模块的任何地方只要包含了声明它的头文件你就可以用UE_LOG(LogMyGameSkill, ...)来输出日志了用法和LogTemp完全一样但分类名变成了你自己的。注意一个常见的“坑”是如果你在多个.cpp文件中都写了DEFINE_LOG_CATEGORY(LogMyGameSkill)会导致链接错误重复定义。所以请牢记一个日志分类只DEFINE一次。通常放在模块的“主”源文件或一个专门的Logging.cpp文件中。2.3 为整个游戏项目创建顶级分类除了为具体模块创建分类为你的整个游戏项目创建一个顶级日志分类也是最佳实践。这可以用于那些不属于任何特定模块的、全局性的日志信息。通常我们会在游戏项目的“主”头文件和源文件中定义它。例如如果你的游戏模块叫MyGame// MyGame.h (项目的主头文件通常由UE自动生成或自定义) #pragma once #include CoreMinimal.h DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All); // MyGame.cpp #include MyGame.h #include MyGameCharacter.h #include MyGameGameMode.h DEFINE_LOG_CATEGORY(LogMyGame); // 在游戏初始化等地方使用 void AMyGameGameMode::InitGame(const FString MapName, const FString Options, FString ErrorMessage) { Super::InitGame(MapName, Options, ErrorMessage); UE_LOG(LogMyGame, Display, TEXT(MyGame initialized on map: %s), *MapName); }这样你就有了一个清晰的日志层次LogMyGame用于全局信息LogMyGameSkill,LogMyGameInventory,LogMyGameAI等用于具体子系统。3. 高级用法与配置技巧创建了分类只是第一步如何高效地管理和使用它们才是关键。3.1 在编辑器与运行时控制日志输出自定义分类最大的好处就是可以动态控制。1. 编辑器输出日志窗口在虚幻编辑器的“输出日志”Window - Output Log窗口的顶部有一个过滤器输入框。你可以输入你的分类名如LogMyGameSkill来只查看该分类的日志。你也可以结合级别过滤比如LogMyGameSkill Error只看错误。2. 运行时控制台命令-LogCmds这是最强大的功能。你可以在启动游戏的命令行参数中或是在游戏运行时的控制台按~键呼出中使用LogCmds命令来精确控制每个分类的日志级别。命令行参数示例UE4Editor.exe YourProject.uproject -LogCmdsLogMyGameSkill Verbose, LogMyGameAI Warning这条命令会在启动时将LogMyGameSkill分类的默认级别设置为Verbose输出所有详细日志而将LogMyGameAI分类的级别设置为Warning只输出警告和错误。运行时控制台命令在游戏内按~打开控制台输入Log LogMyGameSkill Verbose这会将LogMyGameSkill的日志级别立即改为Verbose。如果你想关闭某个分类的所有输出除了Fatal可以将其级别设为Fatal或NoLogging注意NoLogging是一个特殊值可能需要通过引擎代码设置通常设为Fatal即可有效关闭。查看所有活跃分类在控制台输入Log list可以列出当前所有已注册的日志分类及其当前冗长度。3. 配置文件DefaultEngine.ini你还可以在Config/DefaultEngine.ini中预设日志级别这对于测试团队或特定构建配置非常有用。[Core.Log] LogMyGameSkillVerbose LogMyGameAIWarning LogMyGameInventoryError这样项目启动时会自动应用这些设置。3.2 结构化日志 (UE_LOGFMT) 的运用从UE5.2开始引入了更强大的UE_LOGFMT宏。它支持结构化、带命名参数的日志不仅更易读还能被一些日志分析工具更好地解析。#include Logging/StructuredLog.h // 传统UE_LOG变量顺序必须严格对应格式字符串中的占位符 UE_LOG(LogMyGameSkill, Warning, TEXT(Skill %s (ID: %d) cast by %s failed, cost: %.1f), *SkillName, SkillId, *CasterName, ManaCost); // 使用UE_LOGFMT具名参数顺序无关且可读性更强 UE_LOGFMT(LogMyGameSkill, Warning, Skill {SkillName} (ID: {SkillId}) cast by {CasterName} failed, cost: {ManaCost}, (SkillName, SkillName), (SkillId, SkillId), (CasterName, CasterName), (ManaCost, ManaCost) );优势可读性日志消息本身就像一句清晰的描述。健壮性参数顺序错误不会导致格式错乱崩溃传统%s对应错了类型很危险。可解析性输出的日志是结构化的便于用脚本或工具提取特定字段如所有失败的技能名。实操心得对于新的UE5项目尤其是涉及复杂数据记录的模块如数据分析、网络同步验证强烈建议逐步采用UE_LOGFMT。对于维护中的UE4项目或简单的调试输出传统的UE_LOG仍然快捷有效。3.3 创建日志分类的辅助宏与最佳实践当项目有几十个模块时手动为每个模块写DECLARE/DEFINE会很繁琐。我们可以创建一些辅助宏来简化。1. 统一的日志头文件创建一个MyGameLogging.h文件集中声明所有项目的日志分类。// MyGameLogging.h #pragma once // 游戏全局 DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All); // 各子系统 DECLARE_LOG_CATEGORY_EXTERN(LogMyGameSkill, Warning, All); DECLARE_LOG_CATEGORY_EXTERN(LogMyGameInventory, Warning, All); DECLARE_LOG_CATEGORY_EXTERN(LogMyGameAI, Verbose, All); DECLARE_LOG_CATEGORY_EXTERN(LogMyGameNet, Error, All); // 网络日志通常只关心错误 DECLARE_LOG_CATEGORY_EXTERN(LogMyGameUI, Display, All);2. 统一的日志定义文件创建一个MyGameLogging.cpp文件集中定义所有分类。// MyGameLogging.cpp #include MyGameLogging.h DEFINE_LOG_CATEGORY(LogMyGame); DEFINE_LOG_CATEGORY(LogMyGameSkill); DEFINE_LOG_CATEGORY(LogMyGameInventory); DEFINE_LOG_CATEGORY(LogMyGameAI); DEFINE_LOG_CATEGORY(LogMyGameNet); DEFINE_LOG_CATEGORY(LogMyGameUI);然后将这个MyGameLogging.cpp文件添加到你的游戏模块的编译源文件列表在.Build.cs文件中中。这样任何需要日志的模块只需要包含#include “MyGameLogging.h”即可使用相应的分类管理起来非常清晰。3. 命名规范建议前缀一律以Log开头。项目标识接着是项目或产品名缩写如LogMyGame。模块名然后是具体的模块名如LogMyGameSkill。避免冲突确保你的分类名不会与引擎内置分类如LogNet,LogTemp,LogCore或其他第三方插件冲突。4. 实战在复杂模块中应用自定义日志让我们深入一个更复杂的场景一个技能系统包含技能加载、冷却计算、效果应用等多个环节。我们将看到自定义日志如何帮助我们进行分层调试。假设我们有SkillManager,SkillInstance,DamageCalculator几个类。// SkillManager.cpp #include MyGameLogging.h // 包含我们统一的日志头文件 void USkillManager::LoadAllSkills() { UE_LOG(LogMyGameSkill, Verbose, TEXT(Begin loading all skill definitions.)); for (auto SkillDef : SkillDefinitions) { UE_LOG(LogMyGameSkill, Log, TEXT(Loading skill: %s), *SkillDef-GetName()); if (!SkillDef-IsValid()) { // 资源加载失败是严重错误需要立即关注 UE_LOG(LogMyGameSkill, Error, TEXT(Skill definition %s is invalid or failed to load!), *SkillDef-GetName()); continue; } // ... 加载逻辑 } UE_LOG(LogMyGameSkill, Display, TEXT(Finished loading %d skill definitions.), SkillDefinitions.Num()); } // SkillInstance.cpp void USkillInstance::OnCast() { // 技能释放是核心逻辑用Display级别在测试时总是可见 UE_LOG(LogMyGameSkill, Display, TEXT([%s] Cast by %s. Target: %s), *GetSkillName(), *GetCaster()-GetName(), *GetTarget()-GetName()); // 详细的内部状态只在需要深度调试时开启Verbose UE_LOG(LogMyGameSkill, Verbose, TEXT([%s] Pre-cast state: CooldownRemaining%.2f, ManaCost%d), *GetSkillName(), CurrentCooldown, ManaCost); ApplyEffects(); StartCooldown(); } // DamageCalculator.cpp (可能属于另一个模块如GameplayAbilities) // 假设我们为伤害计算也创建了一个分类 LogMyGameDamage #include MyGameLogging.h // 注意如果DamageCalculator属于独立模块应在该模块内定义LogMyGameDamage这里只是使用。 float UDamageCalculator::CalculateFinalDamage(...) { float BaseDamage ...; float CritMultiplier ...; float FinalDamage BaseDamage * CritMultiplier; // 伤害计算细节非常频繁只在极端调试时需要使用VeryVerbose UE_LOG(LogMyGameDamage, VeryVerbose, TEXT(Damage Calc: Base%.1f, CritMul%.2f, Final%.1f), BaseDamage, CritMultiplier, FinalDamage); // 如果出现异常值如负数伤害用Warning提示 if (FinalDamage 0) { UE_LOG(LogMyGameDamage, Warning, TEXT(Calculated negative damage: %.1f. Clamping to 0.), FinalDamage); FinalDamage 0; } return FinalDamage; }这样分层记录的好处日常测试将LogMyGameSkill设为Display可以看到所有技能释放的关键事件。排查技能加载问题将LogMyGameSkill设为Verbose可以看到每个技能的加载细节。性能分析关闭所有Verbose和VeryVerbose日志只保留Error和Warning获得干净的运行环境。专注伤害问题如果怀疑伤害计算有bug可以单独将LogMyGameDamage设为VeryVerbose而其他模块保持安静。5. 常见问题排查与性能考量即使正确创建了分类在实际使用中也可能遇到问题。5.1 链接错误分类未定义或重复定义症状编译成功但链接时报错LNK2001或LNK2005提示LogMyGameXXX相关符号未定义或重复定义。原因与解决未定义你使用了DECLARE_LOG_CATEGORY_EXTERN但在任何一个.cpp文件中都找不到对应的DEFINE_LOG_CATEGORY。确保定义语句被编译到了项目中检查.Build.cs中的源文件列表。重复定义你在多个.cpp文件中都写了DEFINE_LOG_CATEGORY(LogMyGameXXX)。记住一个分类只能定义一次。解决方案是集中定义如前文所述的MyGameLogging.cpp方案。5.2 日志没有输出症状UE_LOG语句执行了但在输出日志窗口或日志文件里看不到。排查步骤检查日志级别这是最常见的原因。你输出的日志级别如Verbose可能低于该分类的当前默认级别如Warning。在编辑器输出日志窗口的过滤器里输入你的分类名全称看看是否有更高等级的日志出现。或者在控制台输入Log LogMyGameSkill Verbose调低级别再试。检查分类名拼写确保UE_LOG宏中的分类名与DECLARE/DEFINE的完全一致包括大小写。检查编译配置在Shipping发布构建中除了Fatal和Error其他级别的日志默认是被编译掉的取决于DEFINE_LOG_CATEGORY的第三个参数All还是Shipping。如果你在发布版测试请确保在DEFINE_LOG_CATEGORY中使用了All并且通过命令行-LogCmds开启了相应级别。检查输出目标Log和Verbose级别的日志默认不会打印到编辑器视口或打包后的游戏控制台它们只写入日志文件。你需要到Saved/Logs/目录下查看对应的.log文件。5.3 性能影响频繁的日志输出尤其是字符串格式化和I/O操作在循环或每帧调用的函数中可能成为性能热点。优化策略使用日志级别作为编译开关Verbose和VeryVerbose级别的日志在非调试构建中可以被编译器优化掉如果DEFINE_LOG_CATEGORY的第三个参数不是All。善用它们来包裹那些开销大的调试信息。条件编译对于极度频繁且开销大的调试日志可以使用#if WITH_EDITOR或#if !(UE_BUILD_SHIPPING || UE_BUILD_TEST)来确保它们只在开发版本中存在。避免在热路径中格式化复杂字符串如果日志信息需要复杂的计算或字符串拼接可以先检查日志级别是否启用。// 不佳无论级别如何都会执行昂贵的ToString() UE_LOG(LogMyGame, Verbose, TEXT(Object State: %s), *VeryComplexObject-GetDetailedDebugString()); // 更佳先检查级别 if (LogMyGame.IsVerbose()) { FString DebugInfo VeryComplexObject-GetDetailedDebugString(); // 只在需要时计算 UE_LOG(LogMyGame, Verbose, TEXT(Object State: %s), *DebugInfo); }注意IsVerbose(),IsLogging()等方法可以用来在运行时检查当前是否启用了某个级别。5.4 与屏幕调试消息 (AddOnScreenDebugMessage) 的配合UE_LOG是记录到文件而GEngine-AddOnScreenDebugMessage是显示在游戏画面上的。它们用途不同可以互补。// 在技能释放时既记录日志供事后分析也在屏幕上显示实时反馈 void USkillInstance::OnCast() { FString LogMsg FString::Printf(TEXT([%s] Cast by %s), *GetSkillName(), *GetCaster()-GetName()); UE_LOG(LogMyGameSkill, Display, TEXT(%s), *LogMsg); if (GEngine bShowOnScreenDebug) { // 使用一个唯一的Key如技能实例的Hash避免消息重复覆盖 int32 Key GetTypeHash(this); GEngine-AddOnScreenDebugMessage(Key, 3.0f, FColor::Cyan, LogMsg); } }配合心得屏幕消息适合显示非常关键、需要玩家或测试者实时看到的信息如“连击数”、“获得金币”但数量不宜过多且生命周期短。日志则用于记录一切供开发者深度分析。自定义日志分类让屏幕消息的来源也更清晰你可以在屏幕消息前加上分类缩写如[Skill] Fireball cast。6. 从LogTemp迁移到自定义分类的步骤如果你已经有一个大量使用LogTemp的项目逐步迁移是可行的。审计与规划搜索项目中所有的LogTemp。根据其所在的模块、类或功能为它们规划新的分类如LogMyGameAI,LogMyGameInventory。创建分类按照前述方法创建好规划中的所有日志分类头文件和定义。分批替换不要一次性全部替换。选择一个模块如AI模块将其所有LogTemp替换为LogMyGameAI。编译测试确保无误。更新过滤器习惯教导团队成员在输出日志窗口使用新的分类名进行过滤。更新调试流程在项目的调试文档或Wiki中更新常用命令例如“当AI行为异常时请在控制台输入Log LogMyGameAI Verbose”。这个过程虽然有些繁琐但对于提升项目的长期可维护性和团队调试效率是一次非常值得的投资。当你和你的团队能够通过清晰的日志分类在数秒内定位到问题模块时你就会深刻体会到告别LogTemp所带来的秩序与便捷。
完整教程)
