Skip to main content

UEDeployPlatform（打包部署）

December 25, 2026About 6 minUnreal EngineOpenHarmony打包

UEDeployPlatform（打包部署）

一. UBT UEDeployPlatform.cs 的定位与用途

​UEDeployPlatform.cs​ 在 Unreal Engine​ 构建系统（Unreal Build Tool​，UBT​）中至关重要，它扮演了连接 UBT 核心构建逻辑与目标平台原生打包工具之间的关键桥梁角色。

主要功能：

  • ​生成标准平台安装包​：负责生成特定格式的交付物，包括 APK​/AAB​ (Android)、IPA​ (iOS)、HAP​/APP (HarmonyOS/Apple) 或标准的桌面安装程序。
  • ​快速部署与调试支持​：通过实现 PrepTargetForDeployment 等方法，为开发者提供快速迭代的能力，支持编辑器直接启动和调试所需的临时包准备工作。
  • ​提供统一的自动化接口​：作为标准化的入口点，供 Unreal Automation Tool（UAT）​ 和虚幻编辑器调用，例如 PrepForUATPackageOrDeploy 方法，以自动化触发完整的构建、打包和部署流程。

二. 添加新平台支持时需要关注的核心实现

在实现或扩展 UEDeployPlatform.cs 以支持新平台（如 OpenHarmony）时，开发者需要重点关注并实现（Override）以下核心方法，这些方法定义了平台特有的打包行为。

方法名称作用描述
​SetPlatformPluginData（Override）数据收集与预处理。 解析项目和插件配置（如 UPL.xml），收集所有平台相关的权限声明、依赖库路径、配置参数等基础数据，为后续打包做准备。
​MakeHap​ / Make{PlatformSpecificPackage}打包核心逻辑。 将编译产物（如 .so​、.dll​）和资源结合平台模板工程，修改配置文件，调用平台专用工具（如 Gradle​、hvigor）执行构建并完成签名。
​PrepTargetForDeployment快速部署预处理。 为满足编辑器中的快速运行（Launch On）需求，调用简化版的打包逻辑，生成临时的、未完全优化的部署包。
​PrepForUATPackageOrDeploy（Override）自动化构建入口。 UAT 调用的主要接口，用于触发完整、正式的安装包构建流程，支持签名、多架构包（如 AAB 切片）组合等复杂发布场景。
​SavePackageInfo（Override）包信息记录。 在构建结束时，将最终的包名、版本号等关键信息保存到文本文件（如 packageInfo.txt），便于自动化流程后续查验和衔接。

MakeHap打包流程

  • 外部环境检测与验证
    在开始构建前，检测并验证 hvigor​、hap-sign-tool.jar​ 等核心构建及签名工具是否可用，版本是否符合要求。同时，确保环境变量、Java​ 运行环境（JRE/JDK​）、SDK路径等所有依赖环境配置正确，以避免构建失败。
  • 模板项目准备与复制
    将引擎提供的平台模板工程（Engine/Build/Platform/​ 目录下）复制到一个临时工作目录，作为本次构建的基础框架。详见：HarmonyOS Native C++ 开发指南_HarmonyOS应用
  • 配置文件替换与生成
    动态替换或生成平台特定的配置文件，例如 app.json5​、module.json5​、oh-package.json5 等。确保配置项符合目标平台的包构建需求（版本号、包名、权限声明、设备类型等）。
  • 项目文件替换与生成根据目标平台需求替换或生成关键项目文件，确保游戏逻辑与平台功能的无缝衔接：
    • 主界面（UIAbility.ets）代码
    • C++ 与目标平台原生代码的桥接实现（Node-API 等）
  • 资源与依赖项管理​
    执行资源文件的收集、拷贝和过滤，并管理所有外部依赖库，包括 .so​ 动态库、.pak​ 资源包以及 .har 模块文件。
  • 调用外部工具执行构建与签名​
    通过命令行调用 hvigor​ 和 hap-sign-tool.jar 等原生工具，自动化执行安装包的编译、打包和签名流程。
  • 多架构构建支持
    根据项目配置，设计并执行按 CPU 架构（例如 arm64-v8a​、x86）拆分或合并安装包的策略，生成适配不同硬件的最终分发包。

举例对比（Android vs OpenHarmony）

方面AndroidOpenHarmony
模板目录​Engine/Build/Android/Java​Engine/Build/OpenHarmony
配置文件​AndroidManifest.xml​, build.gradle​app.json5​、module.json5​、oh-package.json5
构建工具​Gradle​hvigor​(基于 Node.js)
签名工具​apksigner​hap-sign-tool.jar
资源处理支持 OBB/Asset Pack 分包机制资源集中复制，无OBB，支持过滤
架构支持支持多架构灵活合包（胖包）或 AAB 分发支持多架构胖包，默认arm64-v8a
语言桥接库​JNI​（Java Native Interface​）支持 C/C++调用​NAPI​（Node-API​） 作为底层桥接，实现 ArkTS ​与 C/C++ 跨语言调用

三. 潜在风险与注意事项

在实现 UEDeployPlatform.cs 过程中，需特别注意以下问题：

外部环境配置风险

  • SDK、NDK 或 JRE 版本不兼容： 原生打包工具对 Java 环境和平台 SDK 版本要求严格，版本不匹配会导致构建失败。

  • 环境变量配置复杂且不一致： 依赖 $JAVA_HOME 或其他平台特定环境变量，不同开发者环境的差异可能导致构建失败。

  • 外部打包工具路径硬编码： 打包脚本中可能硬编码了外部 .jar 或命令行工具的路径，如果位置不符则无法找到工具。

平台政策与合规风险

  • 复杂的代码签名流程导致审核失败： 新平台的签名工具和证书要求可能很陌生，签名错误会导致应用商店审核不通过。

  • 隐私权限声明遗漏： 未能正确声明所需的权限，可能导致应用在运行时崩溃或被应用市场下架。

  • 包格式不符合应用商店最新要求： 未能适配最新的包格式规范（如 AAB、HAP），会导致打包失败或无法上传应用商店。

项目模板与生成风险

  • 引擎模板文件更新延迟： UBT 打包脚本未及时更新以匹配平台 SDK 更新后的新模板结构，导致构建中断。

  • 动态替换配置文件时出现遗漏或错误： 替换 app.json5​、module.json5 等文件中的关键字段时出错，导致运行时错误或打包失败。

资源和架构管理风险

  • 架构拆包/合包策略错误： 错误处理多架构支持（例如，是否允许一个包同时包含 arm64 和 x86，或者必须拆分成不同的 AAB 切片）），导致应用在某些设备上无法安装或运行。
  • 资源文件过滤不当： 遗漏了必要的资源文件或包含了不必要的调试符号，导致包体过大或缺失文件。

‍