1. 项目概述为什么我们需要 UET如果你在 Unreal Engine 项目里摸爬滚打过一段时间尤其是经历过团队协作、多平台打包、自动化测试这些环节那你大概率会对“构建”这件事又爱又恨。爱的是点击一下“打包”就能生成可执行文件感觉一切尽在掌握恨的是当项目规模变大、平台变多、需要集成到 CI/CD 流水线时你会发现 Unreal Engine 自带的打包流程在自动化、可重复性和错误处理方面简直像在走钢丝。这就是 UETUnreal Engine Tool诞生的背景。它不是 Epic Games 的官方工具而是由 Redpoint Games 社区开发并维护的一套命令行工具集。简单来说UET 的核心目标是把 Unreal Engine 项目的构建、测试和部署流程从一个依赖图形界面和手动操作的“艺术活”变成一个稳定、可配置、可脚本化的“工程活”。我最早接触 UET 是在一个需要同时为 Windows、Linux 和 Android 三个平台打包的多人游戏项目里。当时我们尝试用批处理脚本调用 UnrealBuildTool 和 AutomationTool结果光是处理不同平台的依赖路径、处理构建失败后的清理、以及在不同机器上保持环境一致就耗费了大量精力。UET 的出现相当于提供了一个经过实战检验的“脚手架”它封装了底层复杂的构建逻辑让你能通过一个统一的uet build命令应对绝大多数构建场景。更重要的是它原生支持 BuildGraphUnreal 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 buildUET 会执行以下操作引擎探测读取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.jsonBuildConfig.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:WithFullDebugInfotrue } }, { 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/CDGitLab CI 示例UET 的一大亮点是能轻松集成到持续集成/持续部署流水线中。它提供了-xexport参数可以将构建任务导出为 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 日志中显示的命令通常能获得更直接的错误信息。检查依赖确保所有构建依赖都已满足例如特定的 SDKAndroid 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 ScriptsUES迁移到 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可能会觉得有些繁琐但这份投入在项目后期会以百倍的效率回报给你。