本文原创发布在华为开发者联盟社区，欢迎前往与更多开发者进行互动。
更多相关问题可点击原帖进行交流：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进行检查
2. 确认架构选型，是使用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集成。
  3. 三方库替换成鸿蒙化的版本，需采用Git依赖的方式
  4. 未适配的三方库一般替换成同类功能的库
  5. 自研的插件需要自行适配，可以在原先插件工程的根目录下执行命令flutter create –platforms ohos –t plugin ./，也会自动创建插件鸿蒙平台代码目录ohos，与android和ios并列
  6. 平台代码重写，例如原来在Android平台上开发的Java代码，适配时需要重写成ArkTS代码
  7. 打包验证，目前也有两种方案：
• 一套代码，一套流水线：鸿蒙版Flutter SDK也可以编译打包支持Android/IOS平台运行的包（APK或ipa），使用方便，与普通版本完全一致
• 一套代码，两套流水线：HarmonyOS和Android/ios分别采用不同的Flutter SDK编译构建，最大程度复用代码
  8. 测试与发布

版本选择

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

切换建议：

• 升级前做好备份
• 选择与当前版本差异最小的版本，逐步升级
• 做好测试用例保护

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

• 当前版本 < 3.7 → 升级至 3.7.12
• 7 < 当前版本 < 3.22 → 升级至 3.22.0
• 22 < 当前版本 < 3.27 → 升级至 3.27.4
• 当前版本 > 3.27 → 降级至 3.27.4

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

• 7破坏性改动
• 22破坏性改动
• 27破坏性改动

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

技术架构选型

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

维度	纯 Flutter APP	混合开发
开发范围	全栈 Flutter，HarmonyOS仅作容器	部分Flutter + 主HarmonyOS工程
原生功能适配	较难（需通过通道调用）	便捷（原生模块直接调用）
开发 / 维护成本	低（单一技术栈）	高（多技术栈协作）

选型策略：

• 全新项目，无存量代码：推荐选纯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包，或者运行程序等等。列举了一些常用的命令如下：

指令名称	指令描述	使用说明
doctor	环境检测	flutter doctor -v
create	创建新项目	flutter create –platforms ohos,android,ios –org <org> <appName>
create	创建module模板	flutter create -t module <module_name>
create	创建plugin模板	flutter create -t plugin –platforms ohos,android,ios <plugin_name>
create	创建plugin_ffi模板	flutter create -t plugin_ffi –platforms ohos,android,ios <plugin_name>
devices	已连接设备查找	flutter devices
build	测试应用构建	flutter build hap –debug [–target-platform ohos-arm64]
build	正式应用构建	flutter build hap –release [–target-platform ohos-arm64]
run	应用运行	flutter run
attach	调试模式	flutter attach
pub	获取依赖	flutter pub get
clean	清除项目依赖	flutter clean
cache	清除全局缓存数据	flutter pub cache clean

参考完整命令列表

如何调试

由于当前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代码
  4. 使用Android Studio打开工程，找到main.dart文件，debug运行main方法。
  5. 使用VSCode打开工程，找到main.dart文件，debug运行main方法。
• 混合开发类型：

1. 参考app类型如何调试ArkTS代码, debug运行ohos工程。
2. 调试Dart码时，使用android studio或vscode，通过flutter attach连接已经运行的应用程序，此时可以断点调试Dart，也可热重载Dart代码。

三方库替换

• 纯Dart库
  可以直接引用pub上的版本，不涉及HarmonyOS适配工作
• 已适配HarmonyOS三方库
  需要采用git方式进行引用，详细可以参考Flutter三方库依赖引用及常见问题
• 插件未适配
  可以去官方开发者论坛提需求，会有官方技术支持响应评估，可以选择功能相同或类似的鸿蒙化插件进行替换
• 自定义三方插件
  需要自行适配，文档可以参考开发plugin

申请应用权限

• 应用使用权限配置
  应用在申请权限时，需在项目的配置文件json5中逐个声明权限。
  用户权限申请需使用Permission_Handler插件。
• 受限权限申请
  受限开放的权限通常是不允许三方应用申请的：

• 需要评估当前应用场景是否可申请受限权限,如满足申请条件，可提供相关申请材料到应用市场申请相应权限
• 通常在三方插件中如Wechat_Asset_Picker等涉及受限权限，可考虑使用其它三方库替换，例如image_picker
• 另外有些受限权限，文档建议使用安全控件替代，但是跨端框架无法使用安全控件，申请的时候可以注明此应用是跨端框架开发的应用，一般可以通过申请

打包和发布

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

• 自动签名：开发自测阶段，IDE提供了自动签名方式快速签名，且开放了ACL权限，以及开通开放能力（推送、地图等），方便开发者快速开发调试。
• 手动签名：发布上架应用阶段，需使用手动签名方式申请发布证书，需手动在AGC平台上申请ACL权限且审批通过，需开通开放能力。
  2. 构建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。
• 混合开发应用：
  3. har包引入：Flutter module编译release的har包，替换Ohos工程中的har包，使用Deveco Studio构建App包。
  4. 源码引入：直接使用Deveco Studio构建App包。

3. 发布AppGallery Connect

• 发布HarmonyOS应用:应用正式发布到华为应用市场前,AGC审核人员会进行会审核开发者提交的所有信息。
• 邀请测试:正式版本发布之前，您可以选择特定用户群组来测试您的应用，以收集测试用户的反馈意见，助您提前发现问题，及时修复和优化版本体验
• 内部测试:可以将应用发布上传至您的服务器或者第三方云上，团队参与测试的人员可以将应用下载到授权的设备上测试。
• 蒲公英测试：蒲公英平台提供了分发HarmonyOS应用的服务，IOS开发者能够快速的掌握分发测试HarmonyOS应用。