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

UET工具详解：提升Unreal Engine项目构建自动化与团队协作效率

news 2026/7/18 8:13:45

1. 项目概述：为什么我们需要 UET？

如果你在 Unreal Engine 项目里摸爬滚打过一段时间，尤其是经历过团队协作、多平台打包、自动化测试这些环节，那你大概率会对“构建”这件事又爱又恨。爱的是，点击一下“打包”就能生成可执行文件，感觉一切尽在掌握；恨的是，当项目规模变大、平台变多、需要集成到 CI/CD 流水线时，你会发现 Unreal Engine 自带的打包流程，在自动化、可重复性和错误处理方面，简直像在走钢丝。

这就是 UET（Unreal Engine Tool）诞生的背景。它不是 Epic Games 的官方工具，而是由 Redpoint Games 社区开发并维护的一套命令行工具集。简单来说，UET 的核心目标，是把 Unreal Engine 项目的构建、测试和部署流程，从一个依赖图形界面和手动操作的“艺术活”，变成一个稳定、可配置、可脚本化的“工程活”。

我最早接触 UET 是在一个需要同时为 Windows、Linux 和 Android 三个平台打包的多人游戏项目里。当时我们尝试用批处理脚本调用 UnrealBuildTool 和 AutomationTool，结果光是处理不同平台的依赖路径、处理构建失败后的清理、以及在不同机器上保持环境一致，就耗费了大量精力。UET 的出现，相当于提供了一个经过实战检验的“脚手架”，它封装了底层复杂的构建逻辑，让你能通过一个统一的uet build命令，应对绝大多数构建场景。更重要的是，它原生支持 BuildGraph（Unreal Engine 的官方构建系统），并能将构建任务分发到多台机器执行，这对于缩短大型项目的构建时间至关重要。

所以，UET 适合谁？如果你是独立开发者，只是想简化一下打包命令，它能让你的生活更轻松。但它的真正威力，是在中小型以上的团队、需要建立自动化构建流水线（CI/CD）、或者项目需要频繁进行多平台测试的场景下，才会完全展现出来。接下来，我会带你从零开始，深入 UET 的每一个核心环节。

2. UET 核心设计与工作流解析

在深入命令行之前，我们必须先理解 UET 的设计哲学。它不是一个全新的构建系统，而是一个“胶水层”和“增强器”。它的底层依然严重依赖 Unreal Engine 自身的工具链，比如 UnrealBuildTool (UBT)、AutomationTool (UAT) 和 BuildGraph。UET 的价值在于，它标准化了调用这些工具的方式，并添加了团队协作和自动化所必需的关键特性。

2.1 核心架构：从命令到分布式构建

UET 的架构可以粗略分为三层：

命令行接口层：这是你直接交互的部分，即uet.exe。它解析你的命令（如build,test,upgrade），并将其转化为内部任务。
任务协调层：这是 UET 的核心大脑。它负责理解你的BuildConfig.json配置文件，创建并调度一系列构建步骤（Step）。每个步骤可能对应一个 BuildGraph 脚本的执行，或者一个远程测试任务。
执行与适配层：这一层负责与 Unreal Engine 的工具链以及外部系统（如 CI 服务器、设备农场）进行通信。它处理平台差异、环境变量、错误捕获和重试逻辑。

这种分层设计带来的最大好处是一致性。无论你是在 Windows 的 PowerShell、macOS 的 Terminal 还是 Linux 的 Bash 中运行uet build，只要配置相同，得到的构建结果就是一致的。这对于消除“在我机器上是好的”这类问题至关重要。

2.2 两种使用模式：简易模式与配置模式

UET 贴心地提供了两种使用路径，适应不同复杂度的需求。

简易模式：适用于快速验证或小型项目。你只需要在.uproject或.uplugin文件所在的目录下，运行uet build。UET 会自动探测引擎版本（对于项目）或要求你通过-e参数指定引擎版本（对于插件），然后使用一套合理的默认配置进行构建。这个模式的优势是零配置，立即可用。

配置模式（推荐用于正式项目）：这是 UET 的完全体。你需要创建一个BuildConfig.json文件来精确描述你的构建流程。这个文件定义了诸如“为哪些平台构建”、“使用哪个 BuildGraph 脚本”、“构建后运行哪些测试”、“构建产物输出到哪里”等一系列规则。UET 会严格遵循这个配置文件执行，确保了构建过程的可重复性和可审计性。

注意：即使你从简易模式开始，我也强烈建议在项目早期就转向配置模式。因为BuildConfig.json是团队共享构建逻辑的唯一事实来源，它能避免每个开发者因为本地环境差异而得到不同的构建结果。

2.3 版本同步机制：团队协作的基石

UET 解决了一个在团队开发中非常头疼的问题：构建工具版本不一致。想象一下，美术用 UET 1.0 打包的资源，程序用 UET 1.1 打包的代码，在 CI 服务器上用 UET 1.2 进行的集成构建，这中间可能因为工具本身的 Bug 或行为变更，导致各种灵异问题。

UET 的解决方案很巧妙：在BuildConfig.json中，你可以指定一个UETVersion属性。当任何团队成员在项目根目录运行uet build时，UET 会先检查这个版本号。如果本地运行的 UET 版本与配置文件中指定的版本不一致，UET 会自动下载并切换到指定版本，然后重新执行命令。

这意味着，你只需要在BuildConfig.json中更新一次版本号，提交到代码库，整个团队和所有构建服务器在下一次构建时都会自动同步到相同的 UET 版本。这个设计极大地提升了团队协作的可靠性和可维护性。

3. 从零开始：UET 的安装与环境配置

理论讲得再多，不如动手实操。让我们一步步把 UET 配置到你的开发环境中。

3.1 下载与安装

UET 是一个独立的可执行文件，目前支持 Windows (x64)、macOS (ARM64/x64) 和 Linux (x64)。访问其 GitHub 仓库的 Releases 页面，下载对应平台的最新版本。

以 Windows 为例，下载下来的是一个名为uet-win-x64.exe的文件。我个人的习惯是：

在系统盘（如C:\）或一个专门存放开发工具的目录下，创建一个UET文件夹。
将下载的uet-win-x64.exe重命名为uet.exe，并放入该文件夹。
将这个UET文件夹的路径（如C:\UET\）添加到系统的PATH环境变量中。

添加PATH后，你可以在任何命令行窗口（CMD、PowerShell、Terminal）中直接输入uet来调用它。

更“UET”的方式是使用其自带的安装命令。打开命令行，导航到你存放uet.exe的目录，然后运行：

uet upgrade

这个命令不仅会将当前目录的uet.exe注册到PATH（如果需要），还会检查更新。以后要升级 UET，在任何地方运行uet upgrade即可。

实操心得：在团队中，我建议将uet.exe的下载和PATH配置写入新员工的环境 setup 文档。更好的做法是，在 CI/CD 流水线的 Docker 镜像或构建代理预配置脚本中，就包含uet upgrade这一步，确保构建环境从一开始就是一致的。

3.2 验证安装与基础命令

安装完成后，打开一个新的命令行窗口，输入：

uet --help

你应该能看到 UET 所有可用命令的列表。最常用的几个是：

uet build: 执行构建。
uet test: 运行自动化测试（通常与构建结合使用）。
uet upgrade: 更新 UET 自身。
uet --version: 查看当前 UET 版本。

如果命令能正常执行并输出版本信息，说明安装成功。

3.3 准备一个测试项目

为了后续的演示，你需要一个 Unreal Engine 项目。如果你手头没有，最快的方式是使用 Unreal Engine 编辑器创建一个新的“第三人称模板”项目，或者使用命令行：

# 假设你的 UE5 引擎安装在 C:\UE_5.5\ # 首先导航到引擎的 GenerateProjectFiles 脚本所在目录（Windows示例） cd C:\UE_5.5\Engine\Binaries\DotNET\UnrealBuildTool\ # 创建一个空白项目（这需要你已安装 .NET 版本的 UBT） # 更常见的方式是直接用编辑器创建。

对于本文，我们假设你已有一个现成的项目，其目录结构如下：

MyGameProject/ ├── MyGameProject.uproject ├── Source/ ├── Content/ └── ... (其他文件夹)

4. 核心实战：使用 UET 构建你的第一个项目

现在，让我们进入最核心的环节：用 UET 构建项目。我们将从最简单的场景开始，逐步深入到复杂配置。

4.1 简易模式构建：快速验证

这是上手最快的方式。打开命令行，导航到你的.uproject文件所在目录：

cd /path/to/MyGameProject

然后，直接运行：

uet build

UET 会执行以下操作：

引擎探测：读取MyGameProject.uproject文件，找到其中指定的EngineAssociation字段，从而确定使用哪个版本的 Unreal Engine。
参数默认化：采用默认配置，通常包括：
- 目标配置：Development（开发配置）。
- 目标平台：当前主机平台（例如，在 Windows 上就是Win64）。
- 构建动作：执行BuildCookRun类型的任务（即编译、烘焙内容、打包）。
调用底层工具：在后台，UET 会调用 Unreal Engine 的AutomationTool，并传递一系列精心构造的参数，最终启动构建流程。

构建过程会在命令行中实时输出日志，其格式和内容与你通过 Unreal Editor 的“输出日志”窗口看到的类似。如果一切顺利，你会在项目的Saved/StagedBuilds或Binaries目录下找到构建产物。

为插件构建：如果你构建的是一个.uplugin文件（插件），则需要通过-e参数明确指定引擎版本，因为.uplugin文件本身不包含引擎信息。

cd /path/to/MyPlugin uet build -e 5.5

常用简易参数：

--platform：指定目标平台。可以多次使用以构建多个平台。
```
uet build --platform Win64 --platform Android
```
--shipping：构建Shipping配置（去掉了调试信息，进行了更多优化）。
```
uet build --shipping
```
--config：显式指定配置（Debug、Development、Shipping等）。
```
uet build --config Debug
```

注意事项：简易模式虽然方便，但缺乏灵活性。例如，你无法精细控制构建的每个阶段（如是否跳过内容烘焙），也无法定义构建后的自动化步骤（如上传到测试服务器）。对于严肃的项目开发，我们需要BuildConfig.json。

4.2 配置模式核心：详解 BuildConfig.json

BuildConfig.json是 UET 强大功能的控制中心。它是一个 JSON 文件，定义了构建的完整蓝图。我们来看一个相对完整的示例，并逐部分解析。

{ "Version": 2, "UETVersion": "2026.1194.222", "Type": "Project", "Name": "MyAwesomeGame", "RootPath": ".", "Distributions": [ { "Name": "Win64_Development", "Platforms": [ "Win64" ], "Configurations": [ "Development" ], "Targets": [ "MyAwesomeGame" ], "Steps": [ { "Name": "Build Client", "Type": "BuildGraph", "Graph": "Engine/Build/InstalledEngineBuild.xml", "Target": "Make Installed Build Win64", "Arguments": { "set:WithFullDebugInfo=true" } }, { "Name": "Run Automated Tests", "Type": "Command", "Command": "uet", "Arguments": [ "test", "--platform", "Win64", "--config", "Development" ], "Condition": "Always" } ], "DeploySteps": [ { "Name": "Archive Build", "Type": "Copy", "Source": "{StagedBuildPath}/WindowsNoEditor", "Destination": "Z:\\BuildArchive\\{BuildDate}" } ] } ] }

顶层字段解析：

Version: 配置文件的架构版本。目前最新是2。UET 会根据这个版本号来解析文件。
UETVersion:关键字段。指定此项目要求使用的 UET 版本。团队协作时，务必确保此版本号一致。
Type: 项目类型，"Project"或"Plugin"。
Name和RootPath: 项目名称和配置文件相对于项目根目录的路径（通常为"."）。

Distributions（分发配置）：这是核心数组，你可以定义多种构建“套餐”。每个Distribution对象代表一种特定的构建流程，比如“Windows开发版”、“Android测试版”、“Linux服务器专用版”等。

Name: 该分发的名称，用于在命令行中通过-d参数指定。
Platforms和Configurations: 目标平台和配置列表。
Targets: 要构建的 Target 名称，对应.Target.cs文件中的定义。

Steps（构建步骤）：定义了构建过程中要执行的任务序列。每个步骤都有Type。

Type: "BuildGraph": 最常用的类型，用于执行 Unreal Engine 的 BuildGraph 脚本。你需要指定Graph（脚本路径）和Target（脚本中的目标节点）。Arguments用于向 BuildGraph 传递参数。
Type: "Command": 执行一个命令行命令。如上例中，在构建完成后运行uet test来执行自动化测试。
Condition: 步骤执行条件，如"Always"（总是执行）、"OnSuccess"（仅当之前所有步骤成功时执行）。

DeploySteps（部署步骤）：在构建步骤全部成功完成后执行，通常用于处理构建产物，如复制到网络共享、上传到云存储、生成安装包等。

4.3 执行配置模式构建

创建好BuildConfig.json并放置在与.uproject文件同级的目录后，执行构建就非常简单了：

# 在项目根目录执行 uet build -d Win64_Development -e 5.5

-d Win64_Development: 指定使用配置文件中名为Win64_Development的Distribution。
-e 5.5: 指定使用的 Unreal Engine 版本。UET 会利用这个信息找到正确的引擎目录。

UET 会读取配置文件，按顺序执行Steps中定义的每一个任务，并在所有Steps成功后，执行DeploySteps。

4.4 集成到 CI/CD：GitLab CI 示例

UET 的一大亮点是能轻松集成到持续集成/持续部署流水线中。它提供了-x（export）参数，可以将构建任务导出为 CI 系统的配置文件。

例如，为 GitLab CI 生成配置：

uet build -d Win64_Development -e 5.5 -x gitlab --executor-output-file .gitlab-ci.yml --windows-shared-storage-path "\\\\network\\share\\builds"

-x gitlab: 指定导出为 GitLab CI 格式。
--executor-output-file .gitlab-ci.yml: 指定输出的 YAML 文件路径。
--windows-shared-storage-path: 指定一个 Windows 网络共享路径，用于在 CI Runner 之间共享构建缓存和中间文件，这能极大加速后续构建。

执行此命令后，UET 会生成一个.gitlab-ci.yml文件。这个文件定义了完整的 CI 流水线阶段（如build、test、deploy），每个阶段都包含了运行 UET 构建的命令。你只需要将这个文件提交到仓库，GitLab 就会自动识别并运行它。

实操心得：在 CI 环境中，强烈建议使用共享存储路径。Unreal Engine 的构建会产生大量的中间文件（Intermediate、DerivedDataCache），在每次 CI 运行时都重新生成这些文件极其耗时。通过网络共享复用这些数据，可以将构建时间从数小时缩短到几十分钟。确保你的 CI Runner 对共享路径有读写权限。

5. 进阶功能与最佳实践

掌握了基础构建后，我们来看看 UET 如何解决更复杂的问题。

5.1 多平台并行与分布式构建

对于需要发布到多个平台（如 PC、主机、移动端）的项目，串行构建的总时间是不可接受的。UET 通过 BuildGraph 和自身调度器，支持并行构建。

在BuildConfig.json的Steps中，你可以定义多个BuildGraph步骤，每个针对不同平台。UET 会尝试并行执行它们（取决于你的机器核心数）。更高级的用法是利用 BuildGraph 的聚合节点（Aggregate Node），在单个 BuildGraph 脚本内部定义并行编译任务。

真正的威力在于分布式构建。UET 可以将一个大型 BuildGraph 任务分解，分发到网络中的多台机器上执行，最后再汇总结果。这需要额外的设置，包括配置构建代理（Worker）和协调器（Coordinator）。对于超大型项目，这几乎是必备方案。UET 简化了这个过程的初始配置和故障处理。

5.2 自动化测试集成

构建出包只是第一步，确保包的质量同样重要。UET 可以无缝集成 Unreal Engine 的自动化测试框架。

你可以像前面示例那样，在Steps中添加一个Type: "Command"的步骤来运行uet test。uet test命令本身也非常强大：

--platform和--config: 指定在哪个平台的哪种配置下运行测试。
--test：运行功能测试。
--test=“MapName”：运行指定的关卡测试。
--strict-includes: 在测试前执行严格的头文件依赖检查，这是一个很好的代码质量门禁。

UET 会管理测试设备的发现、会话建立、测试执行和结果收集。它支持在真实的移动设备、游戏主机或通过云设备农场（如 AWS Device Farm）上远程执行测试，并具备故障重试机制。

5.3 故障容忍与自动重试

网络波动、设备临时无响应、第三方服务不稳定……在自动化流水线中，瞬时失败很常见。UET 内置了故障容忍（Fault Tolerance）和自动重试（Automatic Retries）机制。

对于可识别的瞬时错误（如网络超时、设备连接断开），UET 可以自动重试失败的步骤，而不是让整个构建立即失败。你可以在配置中设置重试次数和重试间隔。这个功能对于维护 CI/CD 流水线的稳定性至关重要，避免了大量因环境偶发问题导致的“红色”构建。

6. 常见问题与排查技巧实录

即使工具再完善，在实际使用中也难免会遇到问题。以下是我和团队在长期使用 UET 过程中积累的一些典型问题及其解决方法。

6.1 构建失败：找不到引擎或版本不匹配

问题现象：运行uet build时，提示Could not locate Unreal Engine installation或The specified engine version '5.5' is not found。

排查思路：

检查引擎关联：打开项目的.uproject文件（用文本编辑器），查看EngineAssociation字段。它的值可能是一个版本号（如"5.5"）或一个哈希值。确保你本地安装了对应版本的引擎。
检查引擎安装目录：Unreal Engine 通常安装在C:\Program Files\Epic Games\UE_5.5\或类似路径。UET 会通过注册表（Windows）、环境变量或默认安装路径来查找引擎。你可以通过设置环境变量UE5_ROOT或UE4_ROOT来明确指定引擎路径。
使用-e参数：在命令中显式指定引擎版本，如uet build -e 5.5。UET 会优先使用命令行指定的版本。
对于插件构建：构建插件必须使用-e参数，因为.uplugin文件没有引擎关联信息。

6.2 BuildConfig.json 解析错误或步骤执行失败

问题现象：UET 报告Error parsing BuildConfig.json或某个 Step 执行失败。

排查步骤：

验证 JSON 格式：使用在线的 JSON 验证工具或编辑器的格式化功能，检查BuildConfig.json是否有语法错误，如缺少逗号、引号不匹配等。
检查路径：确保BuildConfig.json中所有文件路径（如Graph路径）都是正确的，并且相对于RootPath。
查看详细日志：UET 的默认输出可能不够详细。添加-v或--verbose参数来获取更详细的日志，这通常会包含底层 AutomationTool 或 BuildGraph 的错误信息。
单独执行 BuildGraph：如果某个Type: "BuildGraph"的步骤失败，尝试手动运行对应的 BuildGraph 命令。UET 最终也是调用RunUAT.bat（或对应平台脚本）来执行 BuildGraph。在引擎目录下找到这个脚本，并手动执行 UET 日志中显示的命令，通常能获得更直接的错误信息。
检查依赖：确保所有构建依赖都已满足，例如特定的 SDK（Android NDK、Windows SDK）、工具链（Visual Studio 构建工具）等。UET 不会帮你安装这些，它只是调用者。

6.3 在 CI/CD 环境中构建缓慢

问题现象：在 GitLab Runner、Jenkins Agent 等 CI 环境中，每次构建都从头开始，耗时极长。

优化方案：

启用共享存储：如前所述，使用--windows-shared-storage-path等参数，为 CI Runner 配置一个共享的网络驱动器或高性能网络存储（如 SSD NAS），用于存放DerivedDataCache和Intermediate目录。这是提升速度最有效的手段。
使用增量构建：确保你的 BuildGraph 脚本正确设置了依赖关系，支持增量编译。UET 默认会利用 BuildGraph 的增量机制。
缓存第三方库：如果你的项目使用了大量的第三方库（如 PhysX、FMOD），考虑将这些库的编译结果也缓存到共享存储中。
优化 Runner 配置：为 CI Runner 分配足够的 CPU 核心和内存。Unreal Engine 的编译是高度并行化的，更多的核心意味着更快的编译速度。
分层构建：考虑将内容（Content）的烘焙和代码的编译分离。代码变更频率低但编译耗时，内容变更频率高但烘焙可能更快。可以设计不同的Distribution，在代码未变更时跳过编译，只进行内容烘焙和打包。

6.4 版本同步失败

问题现象：团队中有人更新了BuildConfig.json中的UETVersion，但其他成员或 CI 服务器没有自动更新到新版本。

排查与解决：

检查网络：UET 自动下载新版本需要网络连接。确保构建环境可以访问互联网（或你们内部部署的 UET 版本仓库）。
检查写入权限：UET 会将新版本下载到本地缓存目录（通常是用户目录下的.uet文件夹）。确保运行 UET 的用户对该目录有写入权限。
手动升级：在受影响的机器上，可以尝试手动运行uet upgrade。如果手动升级成功，但自动切换失败，可能是 UET 的版本检测逻辑遇到了问题，可以检查 UET 的 Issue 列表或考虑暂时回退到一个更稳定的版本。

6.5 从 Unreal Engine Scripts 迁移的注意事项

如果你之前在使用旧的 Unreal Engine Scripts（UES），迁移到 UET 相对平滑，但有几个关键点：

命令调用方式改变：不再需要调用Build.ps1或Generate.ps1，统一使用uet build。
无需 Git 子模块：UET 是独立可执行文件，不需要作为子模块添加到你的仓库中。这简化了仓库管理。
Type 字段变为必填：在旧的 UES 中，BuildConfig.json的Type字段是可选的，默认为"Plugin"。在 UET 中，你必须明确设置"Type": "Project"或"Type": "Plugin"，否则会解析错误。
路径处理：检查BuildConfig.json中所有相对路径，确保它们在新的调用上下文（从项目根目录直接调用uet）下仍然有效。

UET 的出现，本质上是对 Unreal Engine 工业化生产流程中“构建”这一环的标准化和强化。它填补了引擎自身工具链在自动化、团队协作和流程集成方面的空白。从我个人的使用体验来看，引入 UET 后，最直观的感受是构建流程从“黑盒魔法”变成了“白盒工程”。构建失败的原因更容易定位，构建速度通过缓存和并行得以提升，最重要的是，团队每个成员、每台构建服务器输出的包是完全一致的，这为高质量的持续交付打下了坚实基础。刚开始配置BuildConfig.json可能会觉得有些繁琐，但这份投入在项目后期会以百倍的效率回报给你。

查看全文

http://www.cnnetsun.cn/news/3479472.html