1. 问题缘起当UE_Log遇上中文字符在UE4/UE5的C开发中UE_LOG是我们最亲密的调试伙伴。无论是追踪变量值、标记执行路径还是输出错误信息它都不可或缺。然而很多开发者尤其是中文社区的开发者都踩过一个不大不小的坑当你满怀期待地写下UE_LOG(LogTemp, Warning, TEXT(“你好世界”))时在输出日志窗口看到的却是一堆问号“”或者诡异的乱码字符。这个问题看似简单却直接影响了开发过程中信息读取的效率和准确性尤其是在调试涉及中文内容如UI文本、本地化字符串、网络数据包的逻辑时乱码会让问题排查变得异常困难。这个问题的根源并不在于UE4引擎本身有缺陷而在于源代码文件的编码格式、编译器处理宽字符的方式以及输出控制台的编码环境这三者未能统一。简单来说你写的C源代码文件是一种编码UE4的TEXT宏和日志系统期望的是另一种编码而最终显示日志的窗口可能是Visual Studio的输出窗口、独立的编辑器日志窗口或命令行又可能使用第三种编码。任何一个环节不匹配乱码就出现了。本文将彻底拆解UE4/UE5中UE_LOG打印中文乱码的成因并提供从源头到显示的完整解决方案。无论你使用的是Visual Studio、Visual Studio Code还是Rider无论你的项目是纯C还是蓝图与C混合这里的思路和步骤都能帮你一劳永逸地解决这个问题。2. 乱码问题的三层根源剖析要解决问题必须先理解其背后的原理。UE4/UE5的日志输出链可以简化为源代码 - 编译器预处理与编译 - 引擎运行时输出 - 控制台显示。乱码可能发生在任何一环。2.1 第一层源代码文件编码这是最基础也是最常见的一层。C源代码文件本身就是一个文本文件它需要以一种特定的字符编码格式保存。常见的编码有UTF-8 with BOM带签名的UTF-8。文件开头有特殊的字节顺序标记BOM帮助识别编码。UTF-8 without BOM不带签名的UTF-8。这是现代跨平台项目的推荐格式但在Windows传统环境下可能遇到问题。GB2312 / GBK中文Windows系统默认的ANSI编码。在中文环境下创建的文件很可能默认是此编码。UE_LOG宏中的字符串字面量通过TEXT()宏包裹会被编译器处理。如果源代码文件的编码与编译器预期的编码不一致那么在编译阶段字符串的二进制表示就已经错了。例如一个以GBK保存的“你好”源代码被编译器误认为是UTF-8进行解析生成的数据自然是乱码。注意Visual Studio 2019及更早版本对于.cpp和.h文件除非明确指定否则其“高级保存选项”中的编码可能默认为系统区域编码如GB2312。这是乱码的首要嫌疑犯。2.2 第二层编译器与TEXT宏的处理UE4使用TEXT()宏来定义宽字符字符串在Windows上是wchar_t其他平台可能是char16_t或char32_t。这个宏的作用是确保字符串字面量被正确地视为宽字符。关键在于编译器如何解释源代码中的字符串字节流并将其转换为宽字符。这个过程依赖于编译器的“源代码字符集”和“执行字符集”设置。如果编译器认为源代码是GBK而你将文件存为UTF-8那么TEXT(“中文”)在编译时就会产生错误的宽字符序列。在Visual Studio中这通常由编译选项/source-charset和/execution-charset或/utf-8选项控制。对于跨平台兼容性UE4项目通常期望所有源代码都是UTF-8编码。2.3 第三层输出控制台的编码即使前两步都正确字符串在内存中已经是正确的Unicode格式最终显示也可能出问题。这是因为显示日志的“终端”或“控制台”本身有一个代码页Code Page设置。Windows命令行CMD/PowerShell默认代码页是GBK代码页936。如果你直接运行UE4的独立游戏或通过命令行启动编辑器其日志输出到CMD窗口UTF-8编码的宽字符输出到GBK环境的控制台就会显示为乱码。Visual Studio输出窗口它本身可以支持UTF-8输出但有时也需要正确配置或者其缓冲区可能无法正确渲染某些Unicode字符。UE4编辑器内的输出日志窗口这是最理想的环境因为它本身就是引擎的一部分理论上能最好地处理引擎内部输出的宽字符字符串。如果在这里还出现乱码那问题几乎肯定出在前两层。3. 一劳永逸的解决方案与实操步骤下面我们按照从治标到治本、从易到难的顺序提供一套完整的解决方案。建议你按顺序尝试。3.1 方案一检查并转换源代码文件编码治本之策这是最根本的解决方法确保所有源代码文件都使用UTF-8 with BOM编码。这是与Visual Studio和UE4构建系统兼容性最好的选择。操作步骤使用Visual Studio转换单个文件用Visual Studio打开出现乱码的.cpp或.h文件。点击菜单栏文件 - 另存为。在“保存”按钮旁边点击“向下箭头”选择“编码保存”。在弹出的对话框中选择“Unicode (UTF-8 带签名) - 代码页 65001”。保存文件然后重新编译项目。批量转换整个项目源码推荐使用工具手动一个个改太麻烦。可以使用高级文本编辑器如Notepad或VS Code。以Notepad为例用Notepad打开你的项目源码文件夹Source目录。在菜单栏选择编码 - 转为 UTF-8-BOM 编码。Notepad会递归地转换所有打开文件的编码。或者使用搜索 - 在文件中查找不搜索内容直接在全目录文件完成后通过编码 - 转换为 UTF-8-BOM来批量操作。更可靠的方法是安装Converter插件进行批量转换。以VS Code为例打开项目文件夹在底部状态栏可以看到当前文件的编码如“UTF-8”、“GB2312”。点击状态栏的编码按钮选择“通过编码保存”然后选择“UTF-8 with BOM”。批量操作需要借助终端命令或脚本对于普通开发者使用Notepad更直观。实操心得我个人的习惯是在项目伊始就用Notepad将整个Source目录批量转换为“UTF-8-BOM”。之后所有新创建的文件也务必注意保存为统一格式。在Visual Studio中创建新文件后可以立即用“高级保存选项”设置一次。这是避免团队协作中编码混乱的最佳实践。3.2 方案二配置Visual Studio编译器选项确保编译器以UTF-8方式解析源代码。对于使用Visual Studio构建的UE4项目可以通过修改项目属性来实现。操作步骤在Visual Studio中右键点击你的游戏项目通常是.uproject文件生成的那个.vcxproj项目选择“属性”。在属性页中导航到配置属性 - C/C - 命令行。在“其他选项”框中添加以下编译参数/source-charset:utf-8 /execution-charset:utf-8或者更简洁的一个选项/utf-8/utf-8选项等同于同时设置了/source-charset:utf-8和/execution-charset:utf-8并会影响输入给链接器的响应文件编码是最推荐的方式。点击“应用”并“确定”。然后清理解决方案并重新生成。注意事项这个修改是针对特定Visual Studio项目配置Debug/Development/Shipping等的。你需要为所有需要用到的配置如Debug Game、Development Editor等都进行同样的设置。此外这个设置只对你当前这个模块的.vcxproj文件有效。UE4项目通常有多个模块如Game、Editor、Client等你需要为每个产生乱码的模块都进行配置。更一劳永逸的方法是直接修改Build.cs文件见方案四。3.3 方案三处理Windows控制台输出乱码如果你的乱码只出现在独立游戏运行的Windows命令行窗口中而在编辑器内日志正常那么问题就是控制台代码页不匹配。临时解决方案每次启动都需要在运行游戏前在命令行中执行chcp 65001这条命令将当前控制台的代码页切换为UTF-865001。然后在此命令行中启动你的游戏可执行文件。永久解决方案修改启动方式你可以创建一个批处理文件.bat来启动游戏内容如下echo off chcp 65001 nul start YourGame Path\To\Your\Game.exe %*或者更优雅的方式是在你的C代码中在程序启动初期如在main或引擎初始化早期调用系统API设置控制台代码页。但对于UE4项目更推荐使用第一种批处理方式因为它不侵入业务代码。踩坑记录单纯执行chcp 65001可能还不够因为Windows控制台字体也需要支持UTF-8字符。你需要将命令行窗口的字体设置为“Consolas”或“Lucida Console”等支持Unicode的字体。右键点击命令行标题栏 - 属性 - 字体进行选择。如果字体不支持即使代码页正确某些字符也可能显示为方框而非乱码。3.4 方案四在UE4构建系统中指定编码推荐上述方案二修改的是Visual Studio的工程文件对于跨平台或使用不同构建生成器如通过UnrealBuildTool直接生成的情况可能不生效。最根本的方法是在模块的构建描述文件Build.cs中指定编译器参数。操作步骤找到你的游戏模块或其他自定义模块的Build.cs文件例如Source/YourGame/YourGame.Build.cs。在构造函数public YourGame(TargetInfo Target)中添加编译参数。找到PublicDependencyModuleNames添加的地方在其后添加if (Target.Platform UnrealTargetPlatform.Win64) { // 对于Windows平台添加UTF-8编译选项 bEnableUndefinedIdentifierWarnings false; // 在UE5中可以通过修改CppStandard来影响但更直接的是加参数 // 实际上UnrealBuildTool (UBT) 会传递参数给编译器。 // 我们可以通过修改PrivatePCHHeaderFile或添加AdditionalCompilerArguments来实现。 // 更通用的方法是修改模块的编译环境 CppStandard CppStandardVersion.Cpp17; // 确保使用较新的标准对UTF-8支持更好 // 添加额外的编译器标志 string utf8Flags /utf-8; PublicDefinitions.Add(USE_UTF8_COMPILATION1); // 注意直接修改AdditionalCompilerArguments可能更底层但UBT对cl.exe的参数传递有封装。 // 对于Visual Studio编译器UBT默认可能不会添加/utf-8。最可靠的方式是 // 在Windows平台描述文件WindowsPlatformCompilerSetup.cs级别修改但这太复杂。 // 对于项目级一个有效但“硬核”的方法是在Build.cs里 if (BuildConfiguration.bUseUnityBuild false) { // 非Unity Build时为每个文件添加编译选项谨慎使用可能影响编译速度 // 实际上更好的实践是确保源文件编码正确方案一并依赖UE4默认的宽字符处理。 } }实际上对于大多数情况确保源文件是UTF-8-BOM编码方案一并正确配置Visual Studio项目方案二已经足够。在Build.cs中直接操作编译器参数属于相对高级的用法且可能因引擎版本和平台差异而不同。UE4引擎自身的源码就是UTF-8-BOM编码其构建系统也默认以此为前提进行配置。核心建议优先采用方案一转换文件编码配合方案二配置VS项目。这是被验证最有效、最稳定的组合。4. 高级排查与特殊情况处理如果你尝试了以上所有方案中文日志仍然显示异常那么可能需要进入更深层次的排查。4.1 使用调试器查看内存数据这是终极的验证手段可以确定乱码发生在哪个环节。在UE_LOG行设置断点。当断点命中时在Visual Studio的调试器“监视”窗口或“内存”窗口中查看TEXT(“中文”)这个字符串在内存中的实际字节。对于宽字符串你应该能看到类似4F 60 59 7D这样的序列“你好”的UTF-16LE编码。如果看到的是C4 E3 BA C3之类的那说明字符串在编译时就被错误地解释为GBK编码了问题出在源代码或编译器设置上。你也可以在代码中强制转换并输出原始字节来辅助调试FString TestStr TEXT(你好); const TCHAR* CharPtr *TestStr; for (int32 i 0; i TestStr.Len(); i) { UE_LOG(LogTemp, Warning, TEXT(Char[%d]: 0x%04X), i, CharPtr[i]); }输出每个字符的十六进制Unicode码点。正确的“你”和“好”应该分别对应0x4F60和0x597D。4.2 处理第三方库或外部数据的中文有时乱码并非来自静态字符串字面量而是来自网络传输、文件读取或第三方库返回的数据。这类动态数据的编码需要显式转换。FString 的编码转换UE4提供了FString与UTF8、ANSI系统本地编码之间的转换方法。// 假设收到一个UTF-8编码的字节数组 const uint8* UTF8Data ...; int32 UTF8DataSize ...; FString ConvertedStr UTF8_TO_TCHAR((const char*)UTF8Data); // 或者 FString ConvertedStr; FUTF8ToTCHAR Converter((const char*)UTF8Data, UTF8DataSize); ConvertedStr FString(Converter.Length(), Converter.Get()); // 将FString转换为UTF-8 FTCHARToUTF8 Converter(*MyFString); const uint8* UTF8Bytes (const uint8*)Converter.Get(); int32 UTF8Length Converter.Length();明确指定源数据的编码在读取文件或解析网络包时一定要清楚数据源的编码格式。如果是UTF-8就用上述方法转换。如果是其他编码如GBK在Windows平台上可能需要借助MultiByteToWideCharAPI或第三方库如iconv先转换到FString可以处理的宽字符格式。4.3 UE5的潜在差异与注意事项UE5在底层字符串处理上延续了UE4的架构因此上述方案基本通用。但需要注意虚幻引擎版本随着引擎更新对Unicode的支持可能会更加完善。始终建议使用最新稳定版本的引擎。构建系统UE5的构建系统可能有一些微调但通过.Build.cs文件配置编译器参数的原则不变。IDE支持Visual Studio 2022对UTF-8的支持比2019更好。确保你的IDE也更新到最新版本并检查其文本编辑器编码设置。5. 常见问题速查与避坑指南下表汇总了典型乱码现象、可能原因及快速应对措施乱码现象可能发生环节首要排查点解决方案日志中中文显示为“???”编译时或运行时转换失败源代码文件编码将源文件转换为UTF-8 with BOM日志中中文显示为“锟斤拷”等乱码多次错误编码转换导致数据流经多次编码转换检查外部数据源编码使用正确的FString转换API仅Windows命令行中乱码编辑器内正常控制台显示环境Windows控制台代码页运行前执行chcp 65001或修改控制台字体所有地方都乱码且调试器内存查看字节错误编译器解析错误Visual Studio编译器字符集设置在项目属性中添加/utf-8编译选项新增文件乱码旧文件正常新文件编码不一致新文件的保存编码统一团队规范所有新文件用UTF-8-BOM保存从特定文件或网络读取后乱码数据源编码问题数据源的字符编码明确数据源编码使用FTCHARToUTF8/FUTF8ToTCHAR正确转换最后的个人建议解决UE_LOG中文乱码问题本质上是一个“标准化”的工作。我最推荐也最有效的流程是首先用工具如Notepad将整个项目源码目录批量转为UTF-8-BOM编码。其次在Visual Studio项目属性中为所有配置添加上/utf-8编译选项。最后如果需要在独立命令行窗口调试则通过批处理文件或手动执行chcp 65001来启动程序。这套组合拳下来无论是开发期在编辑器内查看日志还是发布后排查问题中文字符都能清晰无误地显示极大提升开发体验和调试效率。记住统一编码是团队协作和跨平台开发的基石早规范早省心。