Unity 项目迁移鸿蒙（一）：环境准备与工程结构

背景

在将现有的 Unity 项目迁移到基于 OpenHarmony（鸿蒙）架构的团结引擎时，由于底层操作系统从 Android（AOSP）完全切换到了鸿蒙架构，很多历史遗留的 Android 逻辑、原生库以及打包配置都会失效并导致报错。

本系列将提供由浅入深的迁移步骤，涵盖环境搭建、报错排查、SDK 适配及工程构建。

本篇先介绍环境准备与工程结构。

环境与工具准备

安装团结引擎

下载团结 Hub
安装团结引擎，并注意勾选 OpenHarmony Build Support

安装 DevEco Studio

鸿蒙的原生 IDE 是华为自研的 DevEco Studio，它是构建、签名、调试鸿蒙应用的核心，类似于 Android 开发中的 Android Studio。

前往鸿蒙开发者官网下载最新版 DevEco Studio
打开团结引擎导出的工程时，会提示是否指定构建 SDK 版本，勾选自动，即可同步使用与团结引擎相同版本的 SDK

项目升级与代码/资源适配

切换平台与基础设置

直接使用 OpenHarmony 平台打开项目。

如果项目使用了 URP，需要删除原先的 URP 插件并重新下载，因为团结引擎使用了独立的 URP 插件，相应的修改也要同步过去。

如果需要在模拟器进行测试，需要勾选 x86_64 平台。

处理报错

旧项目通常充满了 Android 或 iOS 的宏，鸿蒙系统需要添加专门的宏。团结引擎为 OpenHarmony 提供了专门的宏定义：UNITY_OPENHARMONY。比如：

#if UNITY_OPENHARMONY
    // OpenHarmony 平台的特有逻辑
#elif UNITY_ANDROID
    // ...
#endif

OpenHarmony 工程修改

处理完编辑器和导出时的报错后，一般就可以顺利导出鸿蒙工程了。但商业项目的启动等步骤通常包含了第三方 SDK 的调用，需要先完成 SDK 的接入、应用信息的配置等，再对游戏进行测试。

OpenHarmony 工程与 Android Studio 工程结构对比

对于安卓开发者来说，OpenHarmony 工程结构与 Android Studio 有很多相似之处：

Project
│
├── AppScope
│   └── app.json5
│   └── resources
│
├── entry  (launcher)
│   ├── src
│   │   └── main
│   │       ├── ets  (src/main/java)
│   │       ├── resources
│   │       │   ├── base
│   │       │   │   ├── media  (drawable)
│   │       │   │   ├── element  (values)
│   │       │   │   └── profile
│   │       └── module.json5  (AndroidManifest.xml)
│   │
│   ├── oh-package.json5  (build.gradle)
│   └── build
│
├── tuanjieLib
│   ├── libs
│   ├── src
│   │   └── main
│   │       ├── ets  (src/main/java)
│   │       │   └── gen
│   │       │       └── TuanjieJSScriptRegister.ets
│   │       ├── resources
│   │       │   └── rawfile  (src/main/assets)
│   │       │       └── Data
│   │       │           ├── Managed
│   │       │           └── StreamingAssets
│   │       └── module.json5  (AndroidManifest.xml)
│   └── oh-package.json5  (build.gradle)
│
├── hvigor
├── build-profile.json5  (settings.gradle)
├── hvigorfile.ts        (settings.gradle)
└── oh-package.json5

这里整理了一个常见文件的速查表：

OpenHarmony 文件	类似 Android
app.json5	Application 级配置
module.json5	AndroidManifest.xml
build-profile.json5	Project build.gradle
oh-package.json5	Gradle dependencies
hvigorfile.ts	Gradle Task
resources/base	res
resources/rawfile	assets
ets	java/kotlin
cpp	cpp
libs	libs/jniLibs

另外是 Harmony 独有的目录：

OpenHarmony 目录	作用
AppScope	全局资源、全局配置，类似 Android 中 Application 层面的资源和配置，但独立出来管理。
oh_modules	类似 Android 的 Gradle/Maven 依赖缓存（相当于 External Libraries），一般不需要提交到版本控制。
hvigor	Harmony 的构建缓存，类似 Gradle 缓存。
.hvigor	本地构建缓存，作用类似 .gradle。

OpenHarmony 工程与 Android Studio 工程构建 IL2CPP 的对比

与 Unity 2021.x 相比，团结引擎在构建 IL2CPP 的过程中，OpenHarmony 工程的构建方式与 Android Studio 工程有很大不同。

Unity 2021.x 以上的版本，IL2CPP 的构建从原先在 Unity 中进行，改为在 Android Studio 中进行。Unity 导出 Android Studio 工程后，会将代码存储在 Il2CppOutputProject 目录下，在构建 APK 时再由 Android Studio 进行 IL2CPP 的构建。

而团结引擎导出 OpenHarmony 工程时，IL2CPP 的构建则是自动进行的。导出时，代码存储在导出目录同级的 Il2CppBackup 目录后，由 DevEco Studio 自动进行 IL2CPP 的构建。也就是说，团结引擎执行完导出工程步骤后，IL2CPP 的构建就已经完成了，DevEco Studio 只需要进行打包即可。

因为导出代码的路径是导出路径同级的 Il2CppBackup 目录，所以在处理工作流时，应该注意不同项目导出路径的分割，避免同步进行时出现冲突。

配置包名、应用名和图标

AppScope/app.json5 中，看起来可以配置包名、应用名和图标，但实际上只有包名生效。

根据 IDE 提示可以确定：如果要修改应用名，去修改 string: "app_name"；图标则是 media/app_icon.png。但修改后并不会生效，因为实际上获取的是其他路径下的图标。

这里只有启动窗口图标的修改会生效：media/start_icon.png，这个图片是应用运行起来后首先显示的图片。

应用名和 icon 则需要转到 entry 这个模块下进行修改。打开 entry/src/main/module.json5 可以查看相关信息，IDE 会提示应用名（label）和图标（icon）的修改位置。

应用名需要修改以下三个文件：

entry/src/main/resources/base/element/string.json
entry/src/main/resources/zh_CN/element/string.json
entry/src/main/resources/en_US/element/string.json

对应的字段是 EntryAbility_label。

图标对应的目录是 entry/src/main/resources/base/media。其中，默认的图标是目录下的 icon.png。但国内大多数渠道都会要求自适应 icon，所以推荐修改成自适应 icon，也就是把配置改为 layeredIcon，对应的前景和背景图片分别是 ic_launcher_foreground.png 和 ic_launcher_background.png。

除此之外，这个目录下还有 app_splash.png，它的显示时机在 start_icon 之后、游戏启动之前。显示时长不确定，因此推荐使用暗色纯色图片，防止黑屏时突然出现其他颜色的情况。