当前位置：首页 > news >正文

git core.quotepath 导致 UE5 UnrealBuildTool 编译崩溃

news 2026/6/3 9:12:28

问题概述

在 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	低	否	该文件本就不需要版本控制