Flutter 应用如何快速适配 HarmonyOS

本文原创发布在华为开发者联盟社区，欢迎前往与更多开发者进行互动。更多相关问题可点击原帖进行交流：Flutter应用如何快速适配HarmonyOS 。

概述

当前已有适配了 HarmonyOS 的ohos Flutter SDK，当前已有众多 Flutter 应用基于此版本上架鸿蒙应用市场。

目前可使用的有3.7.12、3.22及3.27三个版本，3.32也已经在 Beta 中。

本文旨在介绍如何将 Flutter 应用快速适配 HarmonyOS，包含以下几个方面：

• 整体方案

• 版本选择

• 技术架构选型

• 工作量评估

• 环境准备

• 命令行工具

• 如何调试

• 三方库替换

• 应用权限申请

• 打包和发布

整体方案

1. 先选择确认要使用的 HarmonyOS Flutter SDK 的版本，然后下载配置好开发环境，在进行 HarmonyOS Flutter 应用开发时记得切换 SDK，可以使用 flutter doctor -v 进行检查

   确认架构选型，是使用 Flutter App 还是采用 Flutter module 混合开发，一般延用 Android/IOS 上的选型

• flutter app 方式：可以在原先项目根目录执行命令 flutter create --platforms ohos --t app ./，会自动创建 HarmonyOS 底座工程目录 ohos，与 ios 和 android 目录并列

• flutter module 方式：参考在HarmonyOS上集成Flutter module，最终会将 module 打包成 har 包，供 HarmonyOS 工程引用，类比于 Flutter module 在 Android 上会被构建成 AAR 包，供 APK 集成。

1. 三方库替换成鸿蒙化的版本，需采用 Git 依赖的方式

   未适配的三方库一般替换成同类功能的库

   自研的插件需要自行适配，可以在原先插件工程的根目录下执行命令 flutter create --platforms ohos --t plugin ./，也会自动创建插件鸿蒙平台代码目录 ohos，与 android 和 ios 并列

   平台代码重写，例如原来在 Android 平台上开发的 Java 代码，适配时需要重写成 ArkTS 代码

   打包验证，目前也有两种方案：

• 一套代码，一套流水线：鸿蒙版 Flutter SDK 也可以编译打包支持 Android/IOS 平台运行的包（APK 或 ipa），使用方便，与普通版本完全一致

• 一套代码，两套流水线：HarmonyOS 和 Android/ios 分别采用不同的 Flutter SDK 编译构建，最大程度复用代码

1. 测试与发布

版本选择

之前在 Android/IOS 上使用的 Flutter 版本可能与适配 HarmonyOS 的 Flutter 版本不同，这需要做版本的升级，当前有三个版本适配了 HarmonyOS，分别对应社区 Flutter SDK 的：3.7.12、3.22.0和3.27.4

切换建议：

• 升级前做好备份

• 选择与当前版本差异最小的版本，逐步升级

• 做好测试用例保护

Flutter 版本升级存量项目或历史版本需先调整至上述支持版本，按“最小适配成本” 选择，由于小版本升级不会有破坏性改动，所以仅关注版本号前两位即可：

• 当前版本< 3.7 → 升级至 3.7.12

• 3.7 < 当前版本 < 3.22 → 升级至 3.22.0

• 3.22 < 当前版本 < 3.27 → 升级至 3.27.4

• 当前版本> 3.27 → 降级至 3.27.4

在升级 Flutter 时遇到的 Dart 错误，可以使用dart fix命令自动修复代码，大多数破坏性改动是支持自动修复的，具体可以参考 Flutter 官方提供的升级指导：

• 3.7破坏性改动
  

• 3.22破坏性改动
  

• 3.27破坏性改动
  

注意当升级跨多个版本时，需要关注这中间多个版本的破坏性改动

技术架构选型

Flutter 开发 App 有 2 种模式：纯 Flutter APP 和混合开发。纯 Flutter APP 和混合开发对比：

选型策略：

• 全新项目，无存量代码：推荐选纯 Flutter APP 模式，从零开始用 Flutter 可最大化发挥 “一套代码跨多端” 的优势，避免混合开发的集成成本，迭代效率更高。

• 已有成熟原生 APP，新功能使用 Flutter 开发：仅需适配现有安卓 ios 代码为 HarmonOS 代码，原生开发更便捷，新业务需求集成 Flutter 代码，实现跨端开发。

• 需深度利用平台特性：推荐使用混合开发，复杂原生功能通过原生代码实现更稳定，Flutter 仅负责上层 UI，避免通过 Platform Channel 频繁通信导致的性能损耗和调试复杂度。

工作量评估

适配过程中，工作量主要有以下几部分组成：

• 三方库替换

• Flutter Plugin 中会涉及到平台代码，当适配 HarmonyOS 时，也需要对这些 plugin 也进行鸿蒙化。根据使用量排序已经适配了一批 plugin，归档在GitCode上，使用方法可以参考Flutter三方库依赖引用及常见问题
  

• 针对尚未适配的插件可以去官方开发者论坛提需求，会有官方技术支持响应评估，可以选择功能相同或类似的鸿蒙化插件进行替换

• 针对自研插件，需要自行适配，文档可以参考开发plugin
  

• 平台代码适配

Android 或者 IOS 上可能开发了一些平台代码（Java、swift 等），在适配时，需要将此部分代码使用 ArkTS 重写，经验评估： ArkTS 代码行数 = 0.7 * Java 代码行数

• C++相关适配分为 SO 和源码两种：

• SO 文件需要对源码进行交叉编译成 HarmonyOS 上可运行的 SO，再使用dart:ffi调用
  

• 源码可以使用FFI插件的方式，HarmonyOS 上需要使用 cmake 进行编译

可以结合自身对相关技术的掌握程度评估具体工作量

环境准备

1. 先安装好最新 release 版本的DevEco Studio
   

2. 下载鸿蒙版本的Flutter SDK
   

3. 由于当前 DevEco Studio 不支持 Dart 开发，还需要额外下载 VSCode 或者 Android Studio 进行 Dart 开发和调试

4. 以上完成后配置环境变量
   

以上完成后就可以开发 HarmonyOS 上的 Flutter 应用了

命令行工具

Flutter 命令行工具也做了鸿蒙化，使用起来和在 Android 上十分类似，环境配置完后即可使用，可以直接通过命令创建 Flutter 鸿蒙模板工程，打包成 har、hap 或者 app 包，或者运行程序等等。列举了一些常用的命令如下：

参考完整命令列表

如何调试

由于当前 DevEco Studio 无法调试 Dart 代码，因此日常开发调试需使用 2 个 IDE：Deveco Studio+Android Studio 或 VSCode。

• Flutter App 类型：

• 如何调试 ArkTS 代码

1. 连接真机或模拟器,真机需启用开发者选项，并打开USB调试，使用 Deveco Studio 打开 ohos 目录，并配置调试签名。

2. 在 Flutter 工程根目录下执行 flutter build hap 构建出 hap 包。

3. 在需要调试的 Arkts 代码行打上断点，点击第一步中 DevEco Studio 的右上角 debug 按钮运行应用程序，即可调试 ArkTS 代码。

• 如何调试 Dart 代码

1. 使用 Android Studio 打开工程，找到 main.dart 文件，debug 运行 main 方法。

2. 使用 VSCode 打开工程，找到 main.dart 文件，debug 运行 main 方法。

• 混合开发类型：

• 参考 app 类型如何调试 ArkTS 代码, debug 运行 ohos 工程。

• 调试 Dart 码时，使用 android studio 或 vscode，通过flutter attach连接已经运行的应用程序，此时可以断点调试 Dart，也可热重载 Dart 代码。

三方库替换

• 纯 Dart 库可以直接引用 pub 上的版本，不涉及 HarmonyOS 适配工作

• 已适配 HarmonyOS 三方库需要采用 git 方式进行引用，详细可以参考Flutter三方库依赖引用及常见问题
  

• 插件未适配可以去官方开发者论坛提需求，会有官方技术支持响应评估，可以选择功能相同或类似的鸿蒙化插件进行替换

• 自定义三方插件需要自行适配，文档可以参考开发plugin
  

申请应用权限

• 应用使用权限配置应用在申请权限时，需在项目的配置文件 module.json5 中逐个声明权限。用户权限申请需使用Permission_Handler插件。

• 受限权限申请受限开放的权限通常是不允许三方应用申请的：

• 需要评估当前应用场景是否可申请受限权限,如满足申请条件，可提供相关申请材料到应用市场申请相应权限

• 通常在三方插件中如 Wechat_Asset_Picker 等涉及受限权限，可考虑使用其它三方库替换，例如 image_picker

• 另外有些受限权限，文档建议使用安全控件替代，但是跨端框架无法使用安全控件，申请的时候可以注明此应用是跨端框架开发的应用，一般可以通过申请

打包和发布

• 测试/生产证书管理、环境隔离

• 自动签名：开发自测阶段，IDE 提供了自动签名方式快速签名，且开放了 ACL 权限，以及开通开能力（推送、地图等），方便开发者快速开发调试。

• 手动签名：发布上架应用阶段，需使用手动签名方式申请发布证书，需手动在 AGC 平台上申请ACL权限且审批通过，需开通开放能力。

• 构建 release 包

• 使用 Deveco Studio 构建 App 包：

1. 在 Flutter 工程中执行命令行 flutter build har --release 构建 har 包。

2. 参考打包APP使用 Deveco Studio 工具构建 App 包,打包产物路径 ohos/build/outputs/default/***.app。

• 使用 Flutter 构建 App 包(纯 Flutter 应用)：使用发布证书替换调试证书后，执行命令行 flutter build app --release 即可编译构建出 app 包，打包产物路径：ohos/build/outputs/default/***.app。

• 混合开发应用：

1. har 包引入：Flutter module 编译 release 的 har 包，替换 Ohos 工程中的 har 包，使用 Deveco Studio 构建 App 包。

2. 源码引入：直接使用 Deveco Studio 构建 App 包。

• 发布 AppGallery Connect

• 发布HarmonyOS应用:应用正式发布到华为应用市场前,AGC 审核人员会进行会审核开发者提交的所有信息。

• 邀请测试:正式版本发布之前，您可以选择特定用户群组来测试您的应用，以收集测试用户的反馈意见，助您提前发现问题，及时修复和优化版本体验

• 内部测试:可以将应用发布上传至您的服务器或者第三方云上，团队参与测试的人员可以将应用下载到授权的设备上测试。

• 蒲公英测试：蒲公英平台提供了分发 HarmonyOS 应用的服务，IOS 开发者能够快速的掌握分发测试 HarmonyOS 应用。