🎮 Unreal Engine - UE_LOG

---

📝 定义

UE_LOG 是 Unreal Engine 中用于输出日志信息的核心宏，用于在开发过程中调试程序、记录运行状态、追踪错误等。它支持将信息输出到控制台、日志文件（如 Saved/Logs 目录下的日志文件）以及调试器（如 Visual Studio 的输出窗口），并可通过日志级别和日志类别进行过滤管理。

---

🏛 类/宏关联

UE_LOG 本身是一个宏定义，其实现依赖于 Unreal Engine 的日志系统框架，核心关联组件包括：

• FLogCategoryBase：日志类别基类，所有自定义日志类别均继承自此
• ELogVerbosity：日志级别枚举（如 Fatal、Error、Warning 等）
• FOutputDevice：日志输出设备基类，负责将日志信息发送到控制台、文件等目标

---

⚡ 关键特性

• 分级日志：通过日志级别（Fatal、Error、Warning、Display、Log、Verbose、VeryVerbose）控制信息详细程度，便于过滤无关内容
• 类别管理：支持自定义日志类别（如 LogMyGame），可单独开启/关闭某类日志
• 跨平台兼容：在 Windows、Mac、Linux 等平台均能稳定输出日志
• 格式化输出：支持类似 C++ printf 的格式化语法（如 %s、%d、%f），可输出变量值、对象信息等
• 调试集成：日志信息可直接显示在编辑器控制台和调试器，便于实时追踪程序流程

---

🛠️ 常见配置

• 日志级别设置：

  • 在 DefaultEngine.ini 中配置全局或类别日志级别，例如：

    [Core.Log]
    LogMyGame=Verbose  ; 自定义类别 LogMyGame 输出 Verbose 及以上级别日志
    LogTemp=Warning    ; 临时类别 LogTemp 仅输出 Warning 及以上级别日志

  • 通过命令行参数覆盖配置：LogCmds="LogMyGame=VeryVerbose"

• 日志文件路径：默认存储在项目目录 Saved/Logs/[项目名].log，可通过引擎配置自定义路径

---

📚 使用方法

🔧 基础语法

UE_LOG(LogCategory, LogVerbosity, FormatString, Parameters...)

• LogCategory：日志类别（如 LogTemp 临时类别，或自定义类别）
• LogVerbosity：日志级别（如 Error、Warning）
• FormatString：格式化字符串
• Parameters：对应格式化字符串的参数

🔍 示例

1. 使用临时日志类别：

   UE_LOG(LogTemp, Warning, TEXT("Player health: %d"), CurrentHealth);

2. 自定义日志类别：

   • 先在头文件中声明：

     DECLARE_LOG_CATEGORY_EXTERN(LogSpaceShooter, Log, All);

   • 在源文件中定义：

     DEFINE_LOG_CATEGORY(LogSpaceShooter);

   • 使用：

     UE_LOG(LogSpaceShooter, Display, TEXT("Enemy spawned at: %s"), *SpawnLocation.ToString());

3. 输出致命错误（会导致程序崩溃）：

   UE_LOG(LogTemp, Fatal, TEXT("Critical error: Player controller is null!"));

---

🪂 典型应用场景

• 🐞 调试阶段输出变量值，验证程序逻辑（如角色位置、属性值变化）
• 🚨 记录错误信息（如空指针、资源加载失败），便于定位 Bug
• 📊 追踪程序流程（如关卡切换、事件触发），确认代码执行顺序
• 🔍 性能分析辅助（如记录函数执行时间）

---

🔗 与其他组件对比

功能	UE_LOG	GEngine->AddOnScreenDebugMessage
输出位置	控制台、日志文件、调试器	游戏屏幕直接显示
信息保留	持久化到日志文件	一段时间后自动消失
适用场景	详细日志记录、调试追踪	实时显示关键信息（如坐标、状态）
性能影响	较低（可通过级别控制）	较高（频繁调用可能影响帧率）

---

⚠️ 常见问题与注意事项

• 日志级别滥用：避免在发布版本中保留过多 Verbose 或 VeryVerbose 级别日志，可能增加性能开销和日志文件体积
• 格式化错误：格式化字符串与参数类型不匹配会导致编译错误或运行时崩溃（如 %d 对应整数，%s 对应 FString 需加 转换）
• 自定义类别未定义：使用 DECLARE_LOG_CATEGORY_EXTERN 声明的类别必须用 DEFINE_LOG_CATEGORY 定义，否则会链接错误
• Fatal 级别谨慎使用：Fatal 级日志会强制程序崩溃，仅用于不可恢复的致命错误

---

🏷 小结

• ✅ UE_LOG 是 Unreal Engine 中最核心的日志工具，支持分级和分类管理
• ✅ 合理使用日志级别和类别可提高调试效率，便于后期问题排查
• ✅ 自定义日志类别能让日志更有条理，建议按模块或功能划分（如 LogCombat、LogUI）
• ✅ 发布版本前需清理冗余日志，避免敏感信息泄露和性能损耗