1. 项目概述：为什么要在Shipping模式下开启日志？
在UE4（Unreal Engine 4）项目的开发流程中，我们通常会经历Debug、Development、Shipping等几种构建配置。Shipping模式，顾名思义，是为最终发布版本准备的。在这个模式下，引擎会进行最大程度的优化：剥离编辑器功能、移除调试符号、启用最高级别的编译器优化（如LTO）。这一切的目标都是为了追求极致的运行时性能和最小的包体体积。
然而，正是这些优化，让一个对开发者至关重要的功能默认被关闭了——那就是日志输出。在Shipping模式下，你熟悉的UE_LOG宏、GEngine->AddOnScreenDebugMessage函数，其输出都会石沉大海。这对于线上版本的问题追踪来说，无疑是致命的。想象一下，你的游戏在成千上万的玩家设备上崩溃或出现诡异行为，而你却对现场情况一无所知，只能依靠玩家模糊的描述和可能存在的崩溃报告来“盲猜”问题，效率极低且痛苦不堪。
因此，“在Shipping模式下开启日志”就从一个简单的配置问题，上升为一个关键的线上运维能力。它不是为了让你在发布版本里继续做开发调试，而是为了在玩家端捕获那些在测试阶段难以复现的、与环境或特定操作序列相关的关键错误、警告和信息，为后续的问题定位和修复提供第一手“现场证据”。这不仅仅是打开一个开关，更涉及到日志的输出目的地（控制台、文件、网络）、日志级别过滤、性能影响权衡以及最终的隐私与安全合规性考量。接下来，我将从最基础的配置修改，到深入的源码级定制，为你完整拆解这套流程。
2. 核心思路与方案选型：权衡性能与信息量
在动手之前，我们必须明确目标：我们需要什么样的日志？不同的需求对应着不同的实现复杂度和性能开销。
2.1 需求分析与方案对比
首先，我们要问自己几个问题：
- 需要哪些级别的日志？是只要致命的
Fatal和Error，还是也需要Warning和关键的Info？Verbose和VeryVerbose这类调试日志在Shipping模式下通常必须关闭，因为它们数量庞大，对性能影响显著。 - 日志输出到哪里？是输出到项目的
Saved/Logs目录下的文件，还是需要输出到平台特定的日志系统（如Android的Logcat、iOS的NSLog/Unity System Log）？抑或是需要通过网络实时回传到服务器？ - 对性能的影响容忍度是多少？日志的I/O操作，尤其是同步写入文件，在移动设备上可能引起卡顿。是否需要异步日志或按条件采样？
- 是否有合规性要求？日志中绝不能包含玩家的个人身份信息（PII）、账号密码等敏感数据。
基于这些考量，常见的方案有：
| 方案 | 实现方式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|---|
| 方案A：修改项目配置 | 在.Build.cs或DefaultEngine.ini中定义宏或调整日志类别。 | 改动小，无需编译引擎，快速验证。 | 能力有限，无法精细控制某些核心日志行为，可能被引擎的Shipping预设覆盖。 | 快速验证Shipping模式下基础日志输出是否可行。 |
| 方案B：自定义日志类别与级别 | 在游戏模块中定义自己的日志类别，并在配置文件中动态设置其级别。 | 灵活，可以按模块开关日志，与游戏代码结合紧密。 | 需要修改游戏代码，对引擎自身的日志输出控制力弱。 | 希望对自己编写的游戏逻辑日志进行精细化管理。 |
| 方案C：修改引擎源码 | 直接修改引擎中控制日志初始化和输出的核心代码。 | 能力最强，可以完全控制所有日志行为，包括重定向输出目标。 | 需要编译引擎，维护成本高，升级引擎时需要合并改动。 | 需要深度定制，如实现异步文件日志、网络日志回传等高级功能。 |
| 方案D：使用插件或第三方库 | 集成如spdlog、g3log等高性能日志库，并替换或包装UE_LOG。 | 功能强大、性能优异，社区支持好。 | 引入外部依赖，需要处理与UE4原生日志系统的兼容性。 | 项目对日志性能、特性有极高要求，且不介意增加依赖。 |
对于大多数项目，我推荐采用“方案B + 方案C核心部分”的组合策略。即：通过修改引擎源码，确保在Shipping模式下日志系统本身不被禁用，并可能将默认输出级别调整到Warning或Error；同时，在游戏项目中使用自定义日志类别，以便更灵活地管理游戏逻辑日志。这样既获得了基础保障，又保持了灵活性。
2.2 关键决策点：性能与信息的平衡
这里有一个至关重要的经验：不要在Shipping模式下无差别地开启所有日志。UE_LOG宏在调用时，即使当前日志级别高于语句级别，导致最终没有输出，其参数计算（尤其是字符串格式化FString::Printf）的开销依然是存在的。对于频繁调用的日志（如在Tick函数中），这会是可观的性能浪费。
实操心得：对于高频调用的调试信息，务必使用
UE_LOG的Verbose或VeryVerbose级别，并确保在Shipping配置中这些类别被设置为NoLogging。对于关键的错误或状态变更，使用Error或Warning。一个良好的习惯是，在开发初期就规划好日志类别，而不是到处随意使用LogTemp。
3. 实操全流程：从配置文件到源码编译
我们将按照从易到难的顺序，逐步深入。请先尝试方案A和B，如果无法满足需求，再考虑方案C。
3.1 方案A：通过项目配置启用日志（基础版）
这是最快捷的方法，但效果有限，主要用于测试。
步骤1：修改DefaultEngine.ini配置文件在你的项目Config目录下的DefaultEngine.ini文件中，添加或修改[Core.Log]部分。这个部分控制着全局和特定日志类别的输出级别。
[Core.Log] ; 设置全局默认日志级别为 Warning。Log 和 VeryVerbose 等更低级别将被过滤。 Log=Warning ; 针对特定日志类别进行更细致的设置 ; 例如，开启渲染模块的警告和错误日志 LogRenderCore=Warning LogRHI=Error ; 关键：强制控制台日志在非编辑器构建中也启用 ; 这会影响输出到 StdOut/StdErr 的日志，对于打包后从命令行启动的进程查看日志有用。 [Console] ; 在Shipping构建中保留控制台 bAllowThreadedRendering=False ; 某些平台可能需要此设置来支持控制台步骤2：在 Build.cs 中定义编译宏打开你的游戏模块的.Build.cs文件（例如MyGame.Build.cs）。你可以通过定义预处理器宏，来条件化地包含某些调试代码或改变日志行为。但请注意，这主要影响的是你代码中#if宏包裹的部分，对引擎内部的日志系统开关影响不大。
// 在构造函数中添加 PublicDefinitions.Add("ALLOW_CONSOLE_IN_SHIPPING=1"); // 或者，如果你希望更激进地启用日志 // PublicDefinitions.Add("UE_BUILD_SHIPPING_WITH_LOGGING=1"); // 注意：这个宏引擎可能不识别，需要配合源码修改修改配置后，打包一个Shipping版本，运行并观察Saved/Logs/YourGame.log文件。你会发现，可能只有极少数Fatal和Error级别的日志被记录，很多Warning和Info依然缺失。这是因为引擎源码深处有基于UE_BUILD_SHIPPING宏的硬编码判断。这就引出了方案B和C。
3.2 方案B：使用自定义日志类别进行精细控制
这是管理游戏自身日志的最佳实践。
步骤1：定义自己的日志类别在一个全局可访问的头文件中（如MyGameLog.h），定义你的日志类别。不要使用DEFINE_LOG_CATEGORY_STATIC，因为它只在单个编译单元内有效。使用DEFINE_LOG_CATEGORY_CLASS和DECLARE_LOG_CATEGORY_EXTERN。
// MyGameLog.h #pragma once #include “CoreMinimal.h” #include “Logging/LogMacros.h” // 声明日志类别 DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All); DECLARE_LOG_CATEGORY_EXTERN(LogMyGameAI, Log, All); DECLARE_LOG_CATEGORY_EXTERN(LogMyGameNetwork, Warning, All); // 默认级别设为Warning // MyGameLog.cpp #include “MyGameLog.h” // 定义日志类别 DEFINE_LOG_CATEGORY(LogMyGame); DEFINE_LOG_CATEGORY(LogMyGameAI); DEFINE_LOG_CATEGORY(LogMyGameNetwork);步骤2：在代码中使用自定义类别在游戏代码中，使用你定义的类别进行日志输出。
UE_LOG(LogMyGame, Warning, TEXT(“Player %s entered zone %s”), *PlayerName, *ZoneName); UE_LOG(LogMyGameAI, Verbose, TEXT(“AI %s is calculating path…“), *AIName); // Verbose日志在Shipping中默认不输出步骤3：在运行时通过配置文件控制级别即使使用了自定义类别，在Shipping模式下，Verbose级别的日志默认还是不会输出。你可以在DefaultEngine.ini中动态调整它们的级别，但这通常只对Log,Warning,Error,Fatal有效，因为Verbose可能在编译时就被剔除了。更有效的方式是，在你的游戏初始化代码中，手动设置日志类别的级别（但这要求日志系统本身是可用的）。
// 在游戏启动早期（如GameInstance初始化时） if (FLogCategoryBase* LogCat = GetLogCategory(LogMyGameAI)) { // 仅在特定条件（如启动命令行参数包含 -verboseai）下开启Verbose日志 if (FParse::Param(FCommandLine::Get(), TEXT(“verboseai”))) { LogCat->SetVerbosity(ELogVerbosity::Verbose); } else { // 在Shipping模式下，默认设置为Warning或更高 LogCat->SetVerbosity(ELogVerbosity::Warning); } }注意事项：
SetVerbosity这种运行时动态修改，其有效性取决于底层日志系统是否支持。在Shipping模式下，如果日志系统被彻底关闭或编译优化掉了，此方法可能无效。这直接导向了最终的解决方案——修改引擎源码。
3.3 方案C：修改引擎源码以彻底启用日志
这是最根本的方法。你需要一份引擎的源代码版本。我们将修改几个关键位置。
步骤1：定位并修改日志初始化逻辑引擎中控制日志是否初始化的关键代码位于Engine/Source/Runtime/Core/Private/GenericPlatform/GenericPlatformOutputDevices.cpp的FGenericPlatformOutputDevices::SetupOutputDevices函数，以及Engine/Source/Runtime/Core/Private/Misc/OutputDevice.cpp的FOutputDevice::SetupDevice相关逻辑。但更直接的开关在于日志系统本身的初始化。
一个更集中的位置是Engine/Source/Runtime/Core/Private/Logging/LogMacros.cpp和Engine/Source/Runtime/Core/Public/Logging/LogVerbosity.h。不过，修改宏定义可能影响广泛。一个相对安全的切入点是修改FOutputDevice的创建和注册逻辑。
实际上，控制台变量Log的行为是由Engine/Source/Runtime/Core/Private/Misc/OutputDeviceConsole.cpp等文件决定的。但在Shipping构建中，很多调试设备（如FOutputDeviceDebug、FOutputDeviceWindowsError）不会被创建。
步骤2：修改特定输出设备的创建条件以文件日志为例，关键文件是Engine/Source/Runtime/Core/Private/GenericPlatform/GenericPlatformOutputDevices.cpp。查看FGenericPlatformOutputDevices::Create函数：
FOutputDevice* FGenericPlatformOutputDevices::Create() { TArray<FOutputDevice*> OutputDevices; // 控制台输出设备。在Windows上，即使是非编辑器构建，也通常会创建。 OutputDevices.Add(new FOutputDeviceConsole()); // 文件日志输出设备。这是最重要的！ // 注意：在部分平台的Shipping构建中，可能会通过宏判断是否创建。 OutputDevices.Add(new FOutputDeviceFile()); // 调试输出设备，通常在Shipping中不创建。 #if !UE_BUILD_SHIPPING OutputDevices.Add(new FOutputDeviceDebug()); #endif // … 其他平台特定设备 … return new FFeedbackContextAnsi(OutputDevices); }你需要确保FOutputDeviceFile()在任何构建配置下都被创建。检查引擎代码，有时你会看到如下判断：
// 在某些引擎版本中可能存在这样的条件编译 #if ALLOW_LOG_FILE && !NO_LOGGING OutputDevices.Add(new FOutputDeviceFile()); #endif你需要找到这些宏定义（通常在Build.h或平台特定的头文件中），并确保在Shipping构建中，ALLOW_LOG_FILE和!NO_LOGGING的条件为真。更直接的做法是：注释掉或修改这些条件编译，强制创建文件输出设备。例如：
// 修改前： #if ALLOW_LOG_FILE && !NO_LOGGING OutputDevices.Add(new FOutputDeviceFile()); #endif // 修改后（强制创建）： //#if ALLOW_LOG_FILE && !NO_LOGGING OutputDevices.Add(new FOutputDeviceFile()); //#endif重要警告：直接注释条件编译是侵入性很强的修改，可能会影响引擎其他部分。更推荐的做法是，在引擎的构建配置（
*.Target.cs）或全局宏定义中，为Shipping模式也定义ALLOW_LOG_FILE=1和WITH_LOGGING=1（如果存在NO_LOGGING，则确保它未定义）。
步骤3：修改引擎的构建配置（推荐）这是更“正确”的方式。找到你项目的引擎构建配置文件，或者修改引擎的BuildConfiguration.xml。但更常见的是修改你的游戏项目的Target.cs文件，将宏传递给引擎编译。
在你的游戏Target.cs文件中（例如MyGame.Target.cs和MyGameEditor.Target.cs）：
// MyGame.Target.cs (对应 Shipping/Development 等构建) public class MyGameTarget : TargetRules { public MyGameTarget(TargetInfo Target) : base(Target) { Type = TargetType.Game; DefaultBuildSettings = BuildSettingsVersion.V2; // 关键在这里：为 Shipping 构建额外添加宏定义 if (Configuration == UnrealTargetConfiguration.Shipping) { // 允许日志文件 GlobalDefinitions.Add(“ALLOW_LOG_FILE=1”); // 确保日志系统被编译（如果引擎使用 WITH_LOGGING 宏） GlobalDefinitions.Add(“WITH_LOGGING=1”); // 允许控制台（可选，对于需要命令行查看日志的情况） GlobalDefinitions.Add(“ALLOW_CONSOLE=1”); } ExtraModuleNames.Add(“MyGame”); } }步骤4：修改日志详细级别的默认过滤行为即使日志设备创建了，默认的日志详细级别也可能被限制。这通常由FLogCategoryBase的初始化或ELogVerbosity::Type的编译时过滤决定。UE_LOG宏在展开时，会包含一个UE_LOG_IMPL的内部宏，其中可能包含基于UE_BUILD_SHIPPING的编译时检查。
你需要找到LogMacros.h中UE_LOG宏的定义。在某些引擎版本中，它可能长这样：
#define UE_LOG(CategoryName, Verbosity, Format, …) \ do { \ const ELogVerbosity::Type VerbosityEnum = ELogVerbosity::Verbosity; \ if (CategoryName::IsSuppressed(VerbosityEnum)) { /* … */ } \ /* 可能存在的编译时过滤 */ \ } while(0)或者，更关键的过滤可能在LogVerbosity.h的ENSURE_LOG_VERBOSITY_ALLOWED宏中。你需要确保在Shipping构建下，Warning,Error,Fatal,Log（即Display）级别的日志不被这个宏过滤掉。这可能涉及修改IS_LOGGING_ACTIVE_FOR之类的宏定义。
一个相对取巧且安全的方法是：不修改宏，而是修改日志类别的默认详细级别。在自定义日志类别时（方案B），我们将其默认级别设为Warning或Error。对于引擎自身的日志类别，我们无法直接修改其定义，但可以在引擎初始化后，通过遍历所有日志类别并调整其详细级别来实现。这需要一些反射或访问内部数据结构的技巧，较为复杂。
步骤5：编译引擎完成上述源码修改后，你需要重新编译引擎。在源码根目录运行GenerateProjectFiles.bat（Windows）重新生成解决方案，然后用Visual Studio等IDE编译Development Editor、Shipping等配置。这是一个漫长的过程。
实操心得：修改引擎源码前，务必先备份原文件，并在一个独立的、为该项目定制的引擎分支上进行操作。永远不要直接修改主引擎分支，否则未来升级引擎将是一场合并冲突的噩梦。建议使用Git等版本控制工具管理你的引擎修改。
4. 高级定制与性能优化
成功在Shipping模式下输出日志只是第一步。接下来要考虑如何让这个日志系统更健壮、更高效、更安全。
4.1 实现异步文件日志
默认的FOutputDeviceFile是同步写入的，这意味着每次调用UE_LOG都可能触发一次磁盘I/O，在频繁日志记录时会造成帧率波动。我们可以实现一个简单的异步日志器。
思路：创建一个继承自FOutputDevice的类，内部维护一个生产者-消费者队列。日志消息先被放入队列，由一个后台线程负责从队列中取出并写入文件。
// FAsyncFileOutputDevice.h #pragma once #include “CoreMinimal.h” #include “HAL/ThreadSafeQueue.h” #include “Misc/OutputDevice.h” #include “HAL/Runnable.h” #include “HAL/Thread.h” class FAsyncFileOutputDevice : public FOutputDevice, public FRunnable { public: FAsyncFileOutputDevice(const TCHAR* InFilename); virtual ~FAsyncFileOutputDevice(); // FOutputDevice interface virtual void Serialize(const TCHAR* V, ELogVerbosity::Type Verbosity, const class FName& Category) override; virtual void Flush() override; virtual bool CanBeUsedOnAnyThread() const override { return true; } // FRunnable interface virtual bool Init() override { return true; } virtual uint32 Run() override; virtual void Stop() override; virtual void Exit() override { } private: struct FLogEntry { FString Message; ELogVerbosity::Type Verbosity; FName Category; double Time; }; FString FilePath; FThreadSafeQueue<FLogEntry> LogQueue; FRunnableThread* WorkerThread; FEvent* ShutdownEvent; std::atomic<bool> bStopping; void WriteToFile(const FLogEntry& Entry); }; // FAsyncFileOutputDevice.cpp // 实现序列化、后台线程运行逻辑等。然后，在你的游戏启动模块中，用这个自定义的设备替换掉默认的文件输出设备。这需要更深入地介入引擎的日志初始化流程，可能需要替换FGenericPlatformOutputDevices::Create中的设备创建逻辑，或者通过引擎模块启动回调来注册你的设备。
4.2 日志回传服务器
对于移动端或PC线上游戏，将日志实时或定期回传到服务器进行分析是更高级的需求。这可以基于上述异步日志器实现，在Serialize函数中，除了放入文件队列，也放入一个网络发送队列。网络发送器在另一个线程中工作，将日志批量压缩后发送到指定的日志收集端点（如HTTP服务器）。
注意事项：
- 流量与电量：移动网络下需控制频率和单次数据量，可能需要在Wi-Fi环境下才上传。
- 数据安全：日志内容需脱敏，避免传输敏感信息。传输通道应使用HTTPS加密。
- 上下文信息：每条日志应附带设备ID（非个人标识）、游戏版本、时间戳、关卡/场景等上下文，便于分析。
- 本地缓存与轮转：网络不可用时，日志需在本地加密缓存，待网络恢复后上传。本地日志文件应设置大小或时间限制，进行轮转，避免占用过多磁盘空间。
4.3 基于运行时配置的动态日志
理想情况下，你希望能在不更新客户端的情况下，动态调整线上版本的日志详细级别。这可以通过以下方式实现：
- 配置文件热重载：在游戏中监听某个特定的配置文件（如从服务器下载的
LogConfig.ini），当文件变化时，重新解析并应用其中的日志级别设置。 - 远程命令：通过游戏内建的远程控制台或管理命令通道，接收服务器下发的指令来动态调整日志级别。
- 条件采样：对于高频日志，可以设计采样率。例如，只有1%的请求会记录详细的Verbose日志，通过随机数或特定条件触发。
5. 常见问题排查与实战技巧
即使按照上述步骤操作，你可能还是会遇到各种问题。这里记录一些常见的坑和解决方法。
5.1 问题排查清单
| 现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| 打包后无任何日志文件生成 | 1. 文件输出设备未创建。 2. 日志文件路径无写入权限。 3. 日志级别过高，无任何语句满足输出条件。 | 1. 检查方案C中FOutputDeviceFile的创建条件是否满足。在FGenericPlatformOutputDevices::Create函数开始处添加一个简单的FOutputDeviceDebug输出（仅限Debug构建）来测试设备创建流程。2. 检查 Saved/Logs目录是否存在且可写。在代码中打印当前进程的工作目录和日志文件全路径。3. 在代码中强制输出一条 UE_LOG(LogTemp, Fatal, TEXT(“Test Fatal Log”));。Fatal级别最高，如果这都不输出，说明日志系统根本未工作。 |
| 只有Fatal/Error级别日志，无Warning/Log | 默认的日志详细级别在Shipping模式下被限制。 | 1. 确认DefaultEngine.ini中[Core.Log]下的Log=设置是否为Log或All。2. 检查是否在代码中或引擎初始化时，有地方强制设置了全局日志级别。搜索 LogConsoleResponse命令的处理或FLogCategory的初始化代码。3. 实施方案C，修改引擎中控制默认日志级别的宏或变量。 |
| 日志输出导致游戏明显卡顿 | 同步I/O阻塞了游戏线程。 | 1. 实现异步文件日志（见4.1节）。 2. 减少非必要的日志输出频率，尤其是Tick中的日志。 3. 使用 UE_LOG时，对于复杂的参数，使用*FString::Printf提前格式化，避免在日志判断为不输出时仍进行昂贵的格式化计算（实际上UE_LOG宏内部已做优化，但自定义的日志包装函数需注意）。 |
| 移动设备上日志文件找不到 | 移动平台（iOS/Android）的沙盒机制，日志文件可能不在项目目录下。 | 1.Android：日志通常输出到adb logcat。文件日志路径可能是应用的内置存储目录，如/data/data/com.youcompany.yougame/files/UE4Game/YourGame/YourGame/Saved/Logs。需要通过FPaths相关的API获取可写路径。2.iOS：文件日志在沙盒的 Documents或Library目录。连接Xcode的Device Console可以查看部分输出。最可靠的方式是实现日志回传服务器。 |
| 修改引擎源码后编译失败 | 语法错误、宏冲突或依赖问题。 | 1. 仔细检查修改处的语法，确保括号匹配、分号结束。 2. 如果添加了新的源文件，确保将其加入对应模块的 *.Build.cs文件中。3. 尝试先编译一个非Shipping配置（如Development），看错误是否与你的修改直接相关。 4. 清理中间文件（Intermediate, Saved）和解决方案，重新生成项目文件并编译。 |
5.2 实战技巧与心得
为日志添加上下文：一条孤立的
“Error: Player fell out of world”不如“Error: [Map: Desert_Temple][PlayerID:123][Location:(X=1200,Y=300,Z=-50)] Player fell out of world”有用。可以创建一个辅助函数或宏，自动将当前关卡、玩家状态、游戏模式等信息附加到日志消息中。使用结构化日志：考虑使用JSON或其他结构化格式记录日志，便于后续的自动化分析。你可以重写
Serialize函数，将消息、级别、类别、时间戳、上下文序列化为一个JSON对象再写入文件。区分“开发者日志”与“运营日志”：前者用于调试程序错误，后者用于分析用户行为（如“关卡开始”、“道具购买”）。建议使用不同的日志类别甚至不同的输出管道，方便管理。
定期清理日志：在游戏启动时，检查日志文件的大小和数量，删除过旧的日志，避免占用用户过多磁盘空间。这对于移动端应用商店的审核和用户体验都很重要。
测试！测试！测试！：在开启Shipping日志后，务必进行全面的性能测试和功能测试。对比开启前后在低端设备上的帧率、内存占用、发热情况。确保你的日志系统不会成为线上版本的性能瓶颈或稳定性隐患。
最后，记住一点：线上日志是最后一道防线，而不是主要的调试工具。完善的自动化测试、健全的错误处理机制、清晰的架构设计，才是减少线上问题的根本。但当问题真的出现时，一个设计良好的Shipping日志系统，将成为你定位和解决问题的“眼睛”。
