UBT · UnrealArchitectureConfig

December 25, 2026About 4 min

一、UBT 中的构建架构管理

UnrealArch 是一个枚举类型（Enum-like Class）， 代表构建平台的一个特定硬件 CPU 架构（例如 Arm64、x64）。

用途： 此标识符直接指导底层的编译器和链接器生成特定 CPU 指令集的机器码。每个平台相关的自动化脚本（如 AndroidPlatform.Automation.cs）会将其内部识别的架构字符串映射到这个标准类型。
注意： 当 UBT 需要执行需要明确单一目标架构的特定步骤（例如链接阶段），且配置了多个架构时，可能会要求明确指定一个架构。

‍

UnrealArchitectures 是一个数据结构，它包含一个或多个 UnrealArch 标识符的列表，代表目标项目需要构建和支持的所有 CPU 架构集合。

‍

UnrealArchitectureConfig是平台架构配置的基类，主要用途包括：

设置支持的架构表： 在平台初始化阶段（例如 AndroidPlatform 或 OpenHarmonyPlatform 的构造函数），定义该平台默认支持的所有硬件 CPU 架构。
提供活动架构列表： 向 UBT 的其他模块提供一个标准接口 ActiveArchitectures(...)，告知当前环境配置下需要支持哪些 CPU 架构的编译。必须确保至少存在一个有效的 UnrealArch，否则将抛出异常。
打包协调： 当构建 AAB 或 APK 时，如果 UnrealArchitectures 包含了 Arm64 和 x64，UBT 会协调编译器分别为这两个架构生成独立的本地代码库，并将它们打包进最终的应用文件中。

随着硬件行业的发展，32 位架构逐渐被淘汰，64 位架构成为主流。虚幻引擎的版本迭代反映了这一趋势，特别是在移动平台（Android）的支持上：

架构标识符	UE4 支持情况	UE5.6 支持情况	备注
Armv7 (armeabi-v7a)	支持	移除	32位架构，性能较低，已被淘汰。
x86 (x86)	支持	移除	32位架构，主要用于模拟器，已被淘汰。
Arm64 (arm64-v8a)	支持	核心支持	当前及未来移动设备的主流架构。
x64 (x86_64)	支持	核心支持	桌面、服务器、部分平板及模拟器架构。

在 UE5.6 中，Epic Games 专注于 Arm64 和 x64，简化了构建流程并提高了性能，移除了对旧版 32 位架构的支持。

在 HarmonyOS Native C++ 项目中，虽然默认支持 arm64、armv7 和 x86_64 三种架构，但它们在不同环境下的适用性有明显的区别。

架构名称	描述	主要适用场景	在 HarmonyOS Next 中的状态
arm64	64位 ARM 架构	现代智能手机、平板电脑、物联网设备等	核心支持：DevEco-Studio 的模拟器和真机（包括 Next 版本）目前仅支持 arm64 架构。
armv7	32位 ARM 架构	早期移动设备、低功耗物联网设备	兼容/遗留：通常无需为 Next 版本真机额外提供此架构的 SDK。
x86_64	64位 x86 架构	桌面电脑、服务器、基于 x86 处理器的虚拟机	兼容/遗留：主要用于某些特定的 x86 模拟器环境，通常无需提供外部 SDK。

核心要点：
开发焦点： 开发者应将重心放在 arm64 架构上。
对外 SDK： 根据 HarmonyOS Next 版本的策略，目前通常不需要对外提供 armv7 和 x86_64 版本的 SDK。

如果您需要在虚幻引擎项目（特别是使用鸿蒙适配版本时）中确保对华为鸿蒙系统的兼容性，需要重点考虑以下几点：

关键点：遵循华为的 ABI 要求和弃用策略
华为鸿蒙系统目前的主流和未来趋势完全聚焦于 64 位架构。根据华为的最新开发工具链（如 DevEco Studio NEXT Developer Beta1 及以上版本）说明：

这通常意味着您需要在 UE 的项目设置或构建脚本中，禁用或移除任何对旧的 Armv7 或 x86 架构的引用。

解决依赖库的兼容性问题
鸿蒙应用的打包错误（如 error: install parse native so failed）通常不是引擎配置错误，而是第三方原生库（如 SDK、插件）的缺失导致的。

自查所有依赖项：确保所有您使用的第三方插件或库（HSP 或 HAR 模块）都提供了针对 arm64-v8a 和 x86_64 架构的 .so 文件。
ABI 目录结构：最终打包的应用 HAP/APK 文件必须在正确的 libs/ 目录下包含这些架构目录（例如 libs/arm64-v8a/ 和 libs/x86_64/）。