问题概述

在 Unreal Engine 5.3 项目中，经过多次 LiveCode 后项目突然无法编译，Visual Studio 报错：

UnrealBuildTool failed with exit code 0xe0434352

退出码 0xe0434352 为 Windows .NET CLR 未处理异常，说明 UnrealBuildTool（UBT）自身进程崩溃，而非源码编译错误。

---

环境信息

项目	内容
引擎版本	Unreal Engine 5.3
平台	Windows / Win64
编译配置	DebugGame
.NET SDK	6.0.302（引擎内置）
Visual Studio	2022 Community 17.11

---

排查过程

第一步：查看 UBT 日志

日志路径：C:\Users\Administrator\AppData\Local\UnrealBuildTool\Log.txt

日志在以下位置戛然而止，无任何异常信息：

Using EngineIncludeOrderVersion.Latest for target TESPEditor.Target.cs

说明 UBT 在 BuildRules 加载阶段崩溃，且来不及将异常写入日志文件。

第二步：手动执行 UBT 获取完整异常

通过 PowerShell 直接运行 UBT，在控制台捕获完整的 .NET 异常堆栈：

dotnet "C:\Program Files\Epic Games\UE_5.3\Engine\Binaries\DotNET\UnrealBuildTool\UnrealBuildTool.dll" `
  TESPEditor Win64 DebugGame `
  -Project="F:\workspace\02-project\00-TESP-DEV\TESP.uproject" `
  -NoMutex

第三步：分析异常堆栈

控制台输出了完整异常：

Unhandled exception. System.ArgumentException: Path fragment
'"Config/Script/Common/Independent/作战人员无听力自主脚本.json"'
contains invalid directory separators.

   at EpicGames.Core.FileSystemReference.CombineStrings(...)
      in FileSystemReference.cs:line 83
   at UnrealBuildTool.GitSourceFileWorkingSet.AddPath(String Path)
      in SourceFileWorkingSet.cs:line 279
   at UnrealBuildTool.GitSourceFileWorkingSet.OutputDataReceived(...)
      in SourceFileWorkingSet.cs:line 243

异常明确指向：GitSourceFileWorkingSet.AddPath 在解析 git status 输出时，遇到了无法处理的路径格式。

---

根本原因分析

触发链路

修改了中文命名的 JSON 文件
        ↓
git status 将其列入变更文件列表
        ↓
git 默认开启 core.quotepath=true
将非 ASCII 字符转义为八进制序列并加引号
输出：'"Config/.../\344\275\234\346\210\230...json"'
        ↓
UBT 的 GitSourceFileWorkingSet 逐行解析 git status 输出
        ↓
路径解析器遇到首尾引号，误判为非法路径分隔符
        ↓
抛出 System.ArgumentException → UBT 进程崩溃
        ↓
exit code 0xe0434352

为什么 UBT 要调用 git status？

UBT 内置自适应非统一编译（Adaptive Non-Unity Build） 优化机制：

• 通过 git status 获取近期有变更的文件列表
• 仅对变更文件单独编译（编译单元拆分）
• 其余未变更文件合并为 Unity Build 提升编译速度

因此 git status 的全部输出都会被 UBT 解析，包括非代码文件（JSON、配置文件等）。

为什么之前能编译，现在不行？

状态	git status 是否包含该文件	结果
文件未被修改 / 未被 git 追踪	否	✅ 正常编译
文件被修改或首次进入暂存区	是	❌ UBT 崩溃

每次 LiveCode 后保存配置文件，最终触发了该文件出现在 git status 输出中。

git core.quotepath 的作用

git 的 core.quotepath 配置项（默认值 true）控制非 ASCII 字符的输出方式：

# core.quotepath=true（默认）
"Config/Script/Common/Independent/\344\275\234\346\210\230\344\272\272\345\221\230\346\227\240\345\220\254\345\212\233\350\207\252\344\270\273\350\204\232\346\234\254.json"

# core.quotepath=false
Config/Script/Common/Independent/作战人员无听力自主脚本.json

UBT 的路径解析器仅能处理后者的格式。

---

解决方案

方案一：关闭 git quotepath（推荐，立即生效）

在项目目录执行（仅对当前仓库生效）：

git config core.quotepath false

或全局生效：

git config --global core.quotepath false

配置后重新编译即可恢复正常，无需修改任何项目文件。

方案二：重命名文件（治本）

将涉及的中文文件名改为英文或拼音：

# 修改前
Config/Script/Common/Independent/作战人员无听力自主脚本.json

# 修改后
Config/Script/Common/Independent/soldier_deaf_autonomous_script.json

方案三：将文件加入 .gitignore（规避）

若该配置文件属于本地个人配置，不需要被 git 追踪：

# .gitignore
Config/Script/Common/Independent/*.json

文件从 git 追踪中移除后，不再出现在 git status 输出中，UBT 也就不会解析到它。

---

各方案对比

方案	操作成本	是否需要修改文件	适用场景
关闭 core.quotepath	极低，一条命令	否	快速恢复编译，团队统一配置
重命名文件	低	是	有重构时间，彻底杜绝同类问题
加入 .gitignore	低	否	该文件本就不需要版本控制

---

延伸建议

UE5 项目中，中文路径在多个场景下均存在兼容性风险：

• 资源 Cook：Unreal 的资源烘焙系统在处理中文路径时可能产生异常
• 多人协作：不同操作系统、git 配置下的路径编码行为不一致
• CI/CD 流水线：自动化构建环境通常为纯 ASCII 环境，中文路径易导致脚本失败
• 第三方工具链：部分插件或外部工具对非 ASCII 路径支持不完善

建议在项目初期制定规范：所有纳入版本控制的文件和目录均使用英文命名。

---

参考

• UE5 源码：Engine/Source/Programs/UnrealBuildTool/System/SourceFileWorkingSet.cs
• git 文档：core.quotepath
• Windows CLR 异常码：0xe0434352 = .NET CLR Unhandled Exception