UAT 层扩展

December 25, 2026About 4 min

UAT 层扩展

一. UAT 简介：核心价值与定位

Unreal Automation Tool (UAT) 是虚幻引擎中基于 C# 开发的核心自动化脚本框架。它作为引擎工作流的统一调度中心，将原本零散的流程整合为标准化的流水线，涵盖了从代码编译到最终交付的全生命周期管理。

核心功能与作用：

端到端流水线管理：
UAT 负责管理项目的构建（Build）、资产平台化转换（Cook） 、打包（Package）、部署（Deploy）及自动化测试（Test）。它将复杂的命令行操作封装为一致的任务流。
资产跨平台转换 (Cooking) ：
将引擎内的通用资源（如材质、模型、贴图）转换与优化为目标平台（如 PS5、Android、Windows）能够直接读取的二进制格式，确保运行时的读取效率和兼容性。
跨平台构建标准化：
屏蔽了不同操作系统和硬件平台（PC、移动端、主机）之间的环境差异，提供统一的执行接口，极大降低了多平台发布的维护成本。
高层级流程调度：
UAT 位于构建链的最顶层。在执行代码编译时，它会按需调用 UBT (Unreal Build Tool) 进行底层编译，并随后触发后续的资源打包与分发逻辑，实现“一键式”全流程自动化。
CI/CD 与无人值守发布：
支持完整的命令行驱动，可无缝集成至 Jenkins、GitHub Actions 或 GitLab CI 等持续集成系统，实现自动化的每日构建（Daily Build）与版本发布。
可扩展性与定制化：
开发者可以通过编写自定义的 BuildCommand 类，灵活扩展特定项目的自动化逻辑（如自动上传 CDN、同步符号表等）。

二. UAT 代码入口和核心功能

UAT 的源代码位于 Engine/Source/Programs/AutomationTool 目录。

入口与加载：位于 Programs\AutomationTool 目录下的 Program.cs 文件，启动时会加载所有以 .Automation.csproj 结尾的自动化项目。
命令执行：UAT 使用反射机制识别并执行继承自 BuildCommand 基类的命令类，命令的名称即对应需要执行的操作名称。
典型命令示例：自定义命令需要实现并继承自抽象基类 BuildCommand。以最常用的 BuildCookRun 命令为例：
- 定义文件：BuildCookRun.Automation.cs。
- 执行流程：重写 ExecuteBuild() 方法，在这个方法中调用其核心函数 DoBuildCookRun() 执行以下操作：
  - Build (编译 C++ 代码)
  - Cook (资源预处理)
  - CopyBuildToStagingDirectory (暂存并打 Pak 包)
  - Package (打包)
  - Deploy (安装到目标设备)
  - Run (启动程序)

三. 适配 OpenHarmony 平台所需完成的关键工作

UAT 适配新平台时，“编译”（涉及 UBT模块）、“打包”和“部署”等和平台强相关的功能需要针对目标平台进行功能扩展。

(1) 实现平台特定的 BuildCommand 子类（可选步骤）

目标： 在 UAT 中，标准的打包流程通常由通用的 BuildCookRun 命令驱动。只有当 OpenHarmony 的构建流程与标准流程存在显著差异，需要高度定制的入口点时，才需要创建新的 BuildCommand（例如 BuildOpenHarmony）子类。
实际操作：
- 对于基础适配，我们通常直接扩展通用的 BuildCookRun 命令所调用的平台抽象接口（见步骤2）。
- 在已有的 BuildCommand 命令中扩展目标平台实现，此步骤并非必须。例：在 BuildPluginCommand.Automation.cs中添加 OpenHarmony 的默认CPU架构（与 Android 的默认架构区分），并实现对应逻辑。

(2) 重写并扩展 Platform 抽象类接口

在Engine/Source/Programs/AutomationTool或项目自有的脚本路径下，创建OpenHarmony专用的自动化C#项目或模块。

在 UAT 的平台抽象层，为 OpenHarmony 实现具体的平台类（例如 OpenHarmonyPlatform.Automation.cs）。核心实现：

Package() 方法： 集成鸿蒙系统的专属打包流程，调用 UnrealBuildTool 的 UEBuildPlatform.cs 生成 HAP 应用包。
Deploy() 方法： 实现鸿蒙设备的安装部署逻辑，调用相应的设备管理工具（如 hdc 命令）将 HAP 包推送到目标设备。
RunClient() 方法（可选）： 扩展支持在 OpenHarmony 设备上启动应用并附加调试器。

public class OpenHarmonyPlatform : Platform
{
    ...

    // 集成鸿蒙系统的专属打包流程，调用 UnrealBuildTool 的 UEBuildPlatform.cs 生成 HAP 应用包。
    public override void Package(ProjectParams Params, DeploymentContext SC, int WorkingCL)
    { ... }

    // 实现鸿蒙设备的安装部署逻辑，调用相应的设备管理工具（如 hdc 命令）将 HAP 包推送到目标设备。
    public override void Deploy(ProjectParams Params, DeploymentContext SC)
    { ... }

    // 扩展支持在 OpenHarmony 设备上启动应用并附加调试器。
    public override IProcessResult RunClient(ERunOptions ClientRunFlags, string ClientApp, string ClientCmdLine, ProjectParams Params)
    { ... }
    
    ...
}

(3) 整合与 UBT 的协作（构建工具链配置）

**这是核心步骤，涉及 UBT 内部多个关键组件的修改。详见：**OpenHarmony 平台支持：UBT

目标： 确保 UBT 能够识别 OpenHarmony 平台，并使用正确的工具链和配置进行代码编译、链接及最终部署准备。

‍