修复 UE 5.8 源码构建中的 Unreal Engine UBA Executor UBT Error

对于工作室而言，没有什么比 Engine 构建失败更让人打击士气的了，特别是当你从源码编译 Unreal Engine 5.8.0，而 Visual Studio 却因一个语意不明的异常而中断时。构建失败并抛出一个未处理的异常，直接指向 UBAExecutor.cs。这个被称为 unreal engine uba executor ubt error 的特定阻碍会完全中断编译。它会阻止构建图完成 UnrealHeaderTool 等关键辅助程序的生成。在本指南中，我们将深入剖析为什么 Unreal Build Accelerator (UBA) 在处理嵌套调用时会遇到问题、默认配置是如何失效的，以及如何修补你的 Engine 源码以恢复正常的构建 pipeline。

理解构建系统架构

要理解为什么会发生这个错误，我们必须分析 Unreal Build Tool (UBT) 是如何编排编译的。Unreal Engine 的代码库非常庞大，通常包含数万个源文件。为了高效地编译这些文件，UBT 充当了元构建系统（meta-build system）的角色，负责生成依赖图并分发编译 action。

什么是 Unreal Build Accelerator？

Epic Games 引入了 Unreal Build Accelerator (UBA) 作为默认的编译 Executor，以替代旧的分布式系统。UBA 旨在通过利用轻量级虚拟化文件系统 (VFS) 拦截文件 I/O 操作来加速编译。它将编译器任务路由到多个本地核心，或者将它们分发到 Horde 构建节点上。

在标准的 64 核构建机器上，UBA 可以将干净的 Engine 编译时间从约 90 分钟缩短到 25 分钟以下。然而，由于 UBA 依赖一个集中的本地 Agent 来拦截 I/O，因此它需要对编译器进程的启动方式进行严格控制。

递归 UBT 调用的机制

在编译运行期间，UBT 经常会遇到必须在主 Engine 二进制文件编译之前构建的 target。例如，在编译 UnrealEditor 可执行文件之前，UBT 必须先编译 UnrealHeaderTool (UHT) 来解析头文件并生成反射元数据。

为了实现这一点，主 UBT 进程会启动一个嵌套的二级 UBT 进程来构建前置 target。这种嵌套调用被称为递归 UBT 调用（recursive UBT call）。当递归 UBT 调用处于活动状态时，UBT 会设置一个内部标志 (UnrealBuildTool.IsRecursive = true) 并传递环境变量，将该进程标记为嵌套进程。

为什么 UBA Executor 在递归调用中崩溃

崩溃发生的原因是 UBA Executor 的架构并不支持嵌套的编译循环。让我们看看在 Visual Studio 中发生此故障时 UBT 抛出的典型调用栈（call stack）：

Unhandled exception: Exception: UBA executor is not expected to be invoked from a recursive UBT call.
   at UnrealBuildTool.UBAExecutor.Init(IEnumerable`1 targetDescriptors, ILogger logger) in UnrealEngine\Engine\Source\Programs\UnrealBuildTool\Executors\UnrealBuildAccelerator\UBAExecutor.cs:line 315
   at System.Threading.ExecutionContext.RunInternal(ExecutionContext executionContext, ContextCallback callback, Object state)
   at UnrealBuildTool.UBAExecutor.ExecuteActionsAsync(IEnumerable`1 inputActions, ILogger logger) in UnrealEngine\Engine\Source\Programs\UnrealBuildTool\Executors\UnrealBuildAccelerator\UBAExecutor.cs:line 617
   at UnrealBuildTool.ActionGraph.InternalExecuteActions(ActionExecutor Executor, List`1 ActionsToExecute, ILogger Logger) in UnrealEngine\Engine\Source\Programs\UnrealBuildTool\Actions\ActionGraph.cs:line 435

UBAExecutor.cs 中的安全检查

在 UBAExecutor.Init 方法内部（大约在 UBAExecutor.cs 的第 315 行），Engine 显式地执行了递归安全检查：

// Engine/Source/Programs/UnrealBuildTool/Executors/UnrealBuildAccelerator/UBAExecutor.cs
public void Init(IEnumerable<TargetDescriptor> TargetDescriptors, ILogger Logger)
{
    if (UnrealBuildTool.IsRecursive)
    {
        throw new Exception("UBA executor is not expected to be invoked from a recursive UBT call.");
    }
    
    // Virtualized file system and network initialization follow...
}

这个安全检查的存在有一个至关重要的原因。本地 UBA Agent 需要绑定到特定的 TCP 端口，以便与虚拟化的编译器辅助进程进行通信。

如果递归 UBT 调用尝试初始化 UBA Executor 的第二个实例，两个实例都会尝试绑定到相同的网络 socket，并在虚拟化文件系统挂钩（hooks）上产生冲突。这将导致 socket 分配错误、文件系统损坏或无限期的构建死锁（build deadlocks）。因此，该异常是一个保护性屏障。

根本原因：Executor 选择失败

Unreal Engine 5.8.0 源码构建中的真正 Bug 并非这个安全检查，而是 Executor 工厂逻辑未能正确处理递归调用。

当 UBT 决定使用哪个 Executor 时，它会查询 ExecutorFactory.cs 类。工厂会检查 UBA 在主机上是否启用且可用。

然而，它并没有验证当前的 UBT 进程是否是递归执行。结果，当二级 UBT 进程启动以编译 UnrealHeaderTool 时，工厂尝试将 UBAExecutor 分配给嵌套的构建，从而触发了 Init 方法中的崩溃。

XML 配置陷阱

许多开发者尝试通过修改全局 BuildConfiguration.xml 文件来绕过这个问题。旧论坛帖子中的标准建议是通过禁用以下标签来关闭 UBA：

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <bAllowUBA>false</bAllowUBA>
    </BuildConfiguration>
</Configuration>

为什么 bAllowUBA 在 UE 5.8 中被忽略

如果你将上述 XML 配置应用到 Unreal Engine 5.8.0 源码构建中，编译器仍然会尝试启动 UBA 并抛出异常。这是因为 Engine 的构建配置系统已经过重构。

旧的 bAllowUBA 标志已被废弃，不再映射到 Executor 选择逻辑。相反，UBA 的行为由两个不同的属性控制：bAllowUBAExecutor 和 bAllowUBALocalExecutor。

由于 UBT 在你的 XML 中找不到 bAllowUBAExecutor，它会默认将其设为 true。这会静默覆盖你关闭 UBA 的尝试。

UBA 配置的正确 XML 结构

要成功通过配置文件禁用 UBA，你必须使用更新后的 XML 属性名称。以下是强制 UBT 回退到标准本地 Executor 的正确结构：

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <bAllowUBAExecutor>false</bAllowUBAExecutor>
        <bAllowUBALocalExecutor>false</bAllowUBALocalExecutor>
    </BuildConfiguration>
</Configuration>

该配置可以成功绕过 UBA。然而，完全禁用 UBA 意味着你将失去它为主构建 Action 带来的显著编译加速优势。

修复该错误的逐步指南

根据你的工作流程，你可以选择通过修改 XML 配置在全局解决此问题，或者直接修补 UBT 源码，以便为非递归编译保留构建加速（build acceleration）。

方法 1：覆盖 BuildConfiguration.xml

如果你不想修改 Engine 源码，可以在全局禁用 UBA。这是让项目开始编译的最快方法，但根据你的硬件配置，它会使干净构建（clean build）的编译时间增加约 40% 到 60%。

1. 找到或创建你的全局 BuildConfiguration.xml file。在 Windows 上，这通常位于 %AppData%\Roaming\Unreal Engine\UnrealBuildTool\BuildConfiguration.xml。在 Linux 上，它位于 ~/.config/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml。
2. 在文本编辑器中打开该 XML 文件。
3. 将内容替换为下方所示的更新后的 XML schema。
4. 保存文件并重新启动你的 Visual Studio 构建。

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <BuildConfiguration>
        <bAllowUBAExecutor>false</bAllowUBAExecutor>
        <bAllowUBALocalExecutor>false</bAllowUBALocalExecutor>
    </BuildConfiguration>
</Configuration>

方法 2：修补 UBT 源码（推荐）

由于你是从源码编译 Unreal Engine 5.8，推荐的解决方案是修补 UBT 的 C# 源码。这允许 UBA 在你的主编译 target 上运行，同时在递归调用期间强制回退到标准的 ParallelExecutor。

1. 导航到 UBT 源码目录：Engine/Source/Programs/UnrealBuildTool/Executors/。
2. 在 Visual Studio 或文本编辑器中打开 ExecutorFactory.cs 文件。
3. 找到 Create 方法。该方法负责评估你的配置并返回适当的 ActionExecutor。
4. 修改 UBA 选择的条件判断语句，加入对递归 UBT 运行的检查。

// Engine/Source/Programs/UnrealBuildTool/Executors/ExecutorFactory.cs

public static ActionExecutor Create(BuildConfiguration BuildConfiguration, List<TargetDescriptor> TargetDescriptors, ILogger Logger)
{
    // Check if UBA is allowed, available, and NOT running recursively
-   if (BuildConfiguration.bAllowUBAExecutor && UBAExecutor.IsAvailable())
+   if (BuildConfiguration.bAllowUBAExecutor && UBAExecutor.IsAvailable() && !UnrealBuildTool.IsRecursive)
    {
        return new UBAExecutor(BuildConfiguration, Logger);
    }

    // Fall back to IncrediBuild if configured
    if (BuildConfiguration.bAllowXGE)
    {
        return new XGEExecutor(BuildConfiguration, Logger);
    }

    // Fall back to standard ParallelExecutor
    return new ParallelExecutor(BuildConfiguration, Logger);
}

此补丁可阻止嵌套的 UBT 实例选择 UBA Executor。相反，递归构建（例如构建 UnrealHeaderTool）将安全地使用本地 ParallelExecutor 运行，而你的主 Engine 编译则继续发挥 UBA 的全部威力。

方法 3：命令行参数

如果你是通过自定义命令行脚本或 CI/CD pipeline 运行构建流程，可以在每次调用时单独禁用 UBA。如果你希望为本地开发人员保持启用 UBA，但在远程构建服务器上禁用它，这会特别有用。

为此，在你的 UBT 构建命令中追加 -NoUBA 标志：

# Example command to build the editor without UBA
Engine\Build\BatchFiles\Build.bat UnrealEditor Win64 Development -NoUBA

或者，你可以通过使用 -Executor 标志显式指定，来强制 UBT 使用标准 Parallel Executor：

Engine\Build\BatchFiles\Build.bat UnrealEditor Win64 Development -Executor=Parallel

清理并重新生成构建环境

应用上述任何修复方法后，由于缓存的 assembly 文件或过期的中间元数据，UBT 可能会编译失败。为确保修复能干净利落地生效，你必须清除生成的构建工具二进制文件并重新生成项目文件。

对于 Windows 环境

在指向你的 Unreal Engine 源码目录的命令提示符或 PowerShell 实例中运行以下命令：

:: Delete the cached UBT assembly and build binaries
rd /s /q Engine\Intermediate\Build\UnrealBuildTool
rd /s /q Engine\Binaries\DotNET\UnrealBuildTool

:: Regenerate the project files
GenerateProjectFiles.bat

对于 Linux 和 macOS 环境

在你的终端中执行以下命令：

# Remove cached build tool data
rm -rf Engine/Intermediate/Build/UnrealBuildTool
rm -rf Engine/Binaries/DotNET/UnrealBuildTool

# Regenerate project files
./GenerateProjectFiles.sh

环境清理完毕后，在 Visual Studio 中打开生成的解决方案文件 (UE5.sln) 并重新构建 target。构建现在应该能够通过递归编译阶段，而不会抛出 Executor 异常。

Unreal Engine 源码构建的实用最佳实践

从源码构建自定义引擎分支会带来各种编译、优化和打包挑战。应用以下最佳实践将帮助你维护稳定且高度优化的开发 pipeline。

1. 优化并发以防止内存饥饿

现代 C++ 编译器在每个编译线程上都需要大量的 RAM。在构建大型 Engine 模块时，UBT 生成的并行任务数量可能会超过系统 RAM 的承载能力，从而导致页面文件抖动（page-file thrashing）或编译器崩溃。

你可以通过在 BuildConfiguration.xml 文件中配置 ParallelExecutor 设置来限制最大处理器数量：

<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <ParallelExecutor>
        <MaxProcessorCount>16</MaxProcessorCount>
        <ProcessorCountMultiplier>1.0</ProcessorCountMultiplier>
    </ParallelExecutor>
</Configuration>

将数量限制在每个线程大约 2 GB RAM 左右。例如，拥有 32 GB RAM 的机器应将 MaxProcessorCount 限制为 16。

2. 掌握 Dedicated Server 资产剥离

将游戏部署到云端时，应避免将不必要的客户端资产（如 UI 贴图、音频和网格体）编译到 Dedicated Server 二进制文件中。这可以减少服务器的启动时间和内存占用，这对于高效扩展服务器集群至关重要。

要了解如何配置构建脚本以排除这些资产，请遵循我们关于 Unreal Engine Dedicated Server Asset Stripping 的详细指南。

3. 尽早验证 Blueprint 和包的完整性

成功的 Engine 构建并不能保证你的项目在打包时不会出错。过期的 Blueprint 或序列化错误经常会在最后的打包阶段导致崩溃。

为了防止这些问题阻塞你的发布 pipeline，请阅读我们的指南 Resolving the Unreal Package HasValidBlueprint Ensure Crash 以设置自动验证检查。

4. 正确配置 UBA VFS 缓存

如果你决定使用 C# 补丁保持启用 UBA，请配置虚拟文件系统缓存以在本地存储编译后的对象文件。这使你能够在切换分支时避免重新编译未更改的源文件。

在 XML 文件中添加 UnrealBuildAccelerator 配置块以启用缓存：

<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
    <UnrealBuildAccelerator>
        <WriteCache>true</WriteCache>
        <Cache>127.0.0.1</Cache>
    </UnrealBuildAccelerator>
</Configuration>

确保你的防火墙没有阻挡 UBA 的本地网络通信端口，这些端口用于管理缓存同步循环。

提升你的 Backend 架构

解决诸如 unreal engine uba executor ubt error 之类的构建问题对于维护健康的开发工作流至关重要。然而，设置本地编译环境只是构建现代 Multiplayer 游戏的第一步。

一旦你的自定义 Engine 完成编译并且 Dedicated Server 准备就绪，你就必须应对 Backend 基础设施的复杂挑战。从头开始编写你自己的服务器编排、Matchmaking 算法和持久化数据库需要数周的开发时间。

设置 Load Balancing、数据库分片（database sharding）和 SSL 证书管理很容易耗费 4 到 6 周的专注工作。有了 horizOn，这些 Backend 服务都已预先配置并准备好进行扩展。

与其编写基础设施代码，你只需通过几个简单的 API 调用即可集成玩家数据、实时大厅和服务器扩缩容。这使你能够部署 Dedicated Server 构建并管理玩家状态，且无需任何维护开销。你的团队可以专注于游戏玩法机制和 Engine 功能，而由 horizOn 来处理云端基础设施。

后续步骤

要解决此构建错误，请选择快速 XML 覆盖或在 ExecutorFactory.cs 中应用 C# 源码补丁。一旦你的构建 pipeline 运行顺畅，请寻找优化部署工作流的方法。如果你想扩展你的 Multiplayer 游戏而省去托管自定义服务器的开销，请免费试用 horizOn 或查看我们的 API 文档 以了解更多信息。

---

来源：Unhandled exception: Exception: UBA executor is not expected to be invoked from a recursive UBT call.