将已有 Unity 项目迁移到 HarmonyOS，第一步不是接入 SDK，而是先让项目能在团结引擎中正常运行并成功导出 OpenHarmony 工程。本文从环境安装开始，依次梳理平台切换、基础代码适配、导出工程结构，以及包名、应用名、图标和模拟器等常用配置。

迁移背景

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

本系列将按照实际迁移顺序，介绍环境搭建、报错排查、SDK 适配和自动化构建。

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

环境与工具准备

安装团结引擎

  1. 下载并安装团结 Hub。
  2. 通过团结 Hub 安装团结引擎，并勾选 OpenHarmony Build Support 模块。

安装 DevEco Studio

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

  1. 前往华为开发者联盟下载 DevEco Studio。
  2. 首次打开团结引擎导出的工程时，如果 IDE 提示选择构建 SDK 版本，可选择自动同步，以使用与团结引擎匹配的 SDK。

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

项目分支选择

提审分支通常会裁剪玩法、数据上报等代码，不利于完整验证平台兼容性。建议从功能完整且相对稳定的正式版本分支开始迁移，再将适配结果合并到目标发布分支。

切换平台与基础设置

直接使用 OpenHarmony 平台打开项目，一路选择允许切换平台。

  • 插件适配：部分插件无法直接在 Unity 与团结引擎之间复用，例如 URP。如果插件包含自行修改的代码，需要先备份修改，再移除 Packages 目录中的原插件并安装兼容版本。
  • 平台选择：如果需要在模拟器进行测试，需要勾选 x86_64 平台；
  • 网络配置：如果项目仍需访问 HTTP 资源，在 Project Settings > Player > Other Settings 中将 Allow downloads over HTTP 设置为 Always allowed。正式环境仍建议优先使用 HTTPS。

处理宏报错

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

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

修复编辑器中可见的编译错误，并不代表平台适配已经完成。部分问题只会在导出工程、构建 HAP 或真机运行时出现，需要结合后续日志逐项排查。本篇先处理编辑器阶段的问题，运行时调试将在下一篇展开。

处理字体报错

团结引擎的默认字体，与Unity的默认字体不同，如果原有代码中有设置默认字体的逻辑，就会报错。需要根据团结引擎，选择另外的默认字体。

    if (m_font) return;

#if UNITY_OPENHARMONY
    m_font = Resources.GetBuiltinResource<Font>("LegacyRuntime.ttf");
#else
    m_font = Resources.GetBuiltinResource<Font>("Arial.ttf");
#endif

OpenHarmony 工程修改

处理完编辑器和导出阶段的错误后，通常就能生成 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

下面是 OpenHarmony 工程中需要额外关注的目录：

OpenHarmony 目录 作用
AppScope 全局资源、全局配置，类似 Android 中 Application 层面的资源和配置，但独立出来管理。
oh_modules 类似 Android 的 Gradle/Maven 依赖缓存（相当于 External Libraries），一般不需要提交到版本控制。
hvigor Hvigor 构建工具及相关文件。
.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 中包含应用级配置，但团结引擎导出工程的应用名和图标还会受到 entry 模块资源的影响，不能只修改这一处。

根据 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。如果发布渠道要求使用自适应图标，可将配置改为 layeredIcon，前景和背景资源分别使用 ic_launcher_foreground.png 与 ic_launcher_background.png。

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

另外，在配置打包签名后，再修改包名，会导致包名不一致。需要手动修改签名中的包名。

打开 File > Project Structure > Signing Configs，修改包名，然后点击 Apply 应用，即可同步签名中的包名。

如果 IDE 中的修改没有写入工程，可检查项目根目录的 build-profile.json5，确认 app.products.signingConfig 已指向新建的签名配置。

模拟器设置

默认模拟器的存储空间可能不足，安装较大的 HAP 时容易失败。创建模拟器时建议根据项目包体大小适当提高存储容量，并为后续多次安装预留空间。

小结

至此，迁移所需的基础环境、首轮代码适配和导出工程结构已经梳理完成。下一篇将进入构建与调试阶段，介绍如何查看设备文件和 HiLog、处理平台分支、连接远程设备，并将团结引擎日志转发到 HarmonyOS 原生层。