基于Flutter开发应用如何快速适配HarmonyOS

当前已有适配HarmonyOS的ohos Flutter SDK，依托该SDK，众多Flutter应用已成功上架鸿蒙应用市场。

目前可直接使用的稳定版本包括 3.7.12 →、3.22 →、3.27 →；3.32 → 版本处于Beta测试阶段，可按需尝鲜。

本文将从以下核心维度，详解Flutter应用适配HarmonyOS的全流程：

整体方案
版本选择
技术架构选型
工作量评估
环境准备
命令行工具
调试方法
三方库替换
应用权限申请
打包和发布

一、整体方案

Flutter应用适配HarmonyOS的核心流程可分为8个步骤，确保从环境配置到发布上架的全链路覆盖：

版本与环境配置 ：选定目标HarmonyOS Flutter SDK版本，完成下载与配置，开发时需切换至该SDK，可通过 flutter doctor -v 命令校验环境。
技术架构选型：延续Android/iOS平台的架构选型，支持两种模式
- 纯Flutter App模式：在现有项目根目录执行命令
  复制代码
```
flutter create --platforms ohos --t app ./
```
  自动生成与ios、android目录同级的HarmonyOS工程目录ohos。
- Flutter Module混合开发模式 ：参考在HarmonyOS上集成Flutter module，将Module打包为har包供HarmonyOS工程引用（类比Android平台的AAR包集成逻辑）。
三方库鸿蒙化替换：优先选用已适配HarmonyOS的三方库，且需通过Git依赖方式引入。
未适配库替代方案：无鸿蒙化版本的三方库，替换为功能等价的同类鸿蒙适配库。
自研插件适配：在自研插件工程根目录执行命令
复制代码
```
flutter create --platforms ohos --t plugin ./
```
自动生成ohos平台代码目录，与android、ios目录同级。
平台代码迁移：原Android平台的Java代码，需重写为HarmonyOS支持的ArkTS代码。
打包方案选择：支持两种流水线策略
- 一套代码，一套流水线：鸿蒙版Flutter SDK可直接编译生成Android/iOS平台的APK/IPA包，使用方式与原生Flutter SDK完全一致。
- 一套代码，两套流水线：HarmonyOS与Android/iOS分别使用对应版本的Flutter SDK编译构建，最大化代码复用率。
测试与发布：完成功能与兼容性测试后，按鸿蒙应用市场要求提交发布。

二、版本选择

适配HarmonyOS的关键是选择与现有Flutter版本差异最小的鸿蒙化SDK版本，降低升级成本，具体选择策略如下：

1. 版本对应关系

已适配HarmonyOS的Flutter SDK版本，与社区版的对应关系如下：

鸿蒙化Flutter SDK版本	社区版对应版本	状态
3.7.12-ohos-1.1.7	3.7.12	稳定版
3.22.1-ohos-1.0.7	3.22.1	稳定版
3.27.5-ohos-1.0.1	3.27.5	稳定版
3.32.4-ohos-0.0.1	3.32.4	Beta版

2. 版本切换建议

升级前务必备份项目代码，避免版本切换导致的代码丢失。
遵循最小适配成本原则，按当前项目版本选择目标鸿蒙化版本：
- 当前版本 < 3.7 → 升级至 3.7.12
- 3.7 < 当前版本 < 3.22 → 升级至 3.22.0
- 3.22 < 当前版本 < 3.27 → 升级至 3.27.4
- 当前版本 > 3.27 → 降级至 3.27.4
跨版本升级时，需关注中间所有版本的破坏性改动，参考官方文档：
升级中遇到的Dart语法错误，可通过 dart fix 命令自动修复，大部分破坏性改动均支持该工具修复。

三、技术架构选型

Flutter应用适配HarmonyOS支持纯Flutter App 和混合开发两种架构，需根据项目现状选择，具体对比与选型建议如下：

对比维度	纯Flutter APP	混合开发（Flutter Module + 鸿蒙原生）
开发范围	全栈Flutter开发，HarmonyOS仅作为运行容器	鸿蒙原生工程为主，Flutter负责部分功能模块
原生功能适配难度	较高（需通过Platform Channel调用鸿蒙原生能力）	较低（直接调用鸿蒙原生API）
开发/维护成本	低（单一技术栈，跨端一致性强）	高（需维护Flutter与ArkTS双技术栈）

选型策略

全新项目，无存量代码 ：优先选择纯Flutter App模式，最大化发挥"一套代码跨多端"优势，避免混合开发的集成成本，提升迭代效率。
已有成熟原生APP，新增Flutter功能 ：选择混合开发模式，仅需将现有Android/iOS原生代码迁移为ArkTS代码，新功能通过Flutter Module实现，兼顾存量业务与跨端需求。
需深度调用鸿蒙平台特性 ：选择混合开发模式，复杂原生能力（如硬件交互、系统级服务）通过ArkTS实现更稳定，Flutter专注上层UI开发，减少跨通道通信的性能损耗与调试复杂度。

四、工作量评估

适配工作量主要集中在三方库替换 、平台代码迁移 、C++模块适配三个方面，可结合项目规模与技术储备评估成本：

三方库替换
- 已适配鸿蒙的Flutter插件列表可参考GitCode归档，使用方法详见Flutter三方库依赖引用及常见问题。
- 未适配插件可通过鸿蒙开发者论坛提交适配需求，或替换为功能等价的鸿蒙化插件。
- 自研插件需自行适配，参考文档开发plugin。
平台代码适配 原Android平台的Java代码需迁移为ArkTS代码，根据经验统计：ArkTS代码行数 ≈ 0.7 × Java代码行数，可按此比例估算迁移工作量。
C++相关适配 分为SO文件移植 和源码编译两种场景：
- SO文件：需将源码交叉编译为HarmonyOS兼容的SO文件，通过 dart:ffi 调用，参考文档Dart FFI调用鸿蒙SO。
- 源码：通过FFI插件封装，在HarmonyOS平台使用CMake编译构建。

五、环境准备

适配HarmonyOS的Flutter开发环境需安装以下工具，步骤如下：

安装最新稳定版 DevEco Studio，用于鸿蒙原生代码开发与打包。
下载鸿蒙化Flutter SDK：ohos Flutter SDK。
由于DevEco Studio暂不支持Dart开发，需额外安装 VSCode 或 Android Studio，搭配Dart插件完成Flutter代码编写与调试。
配置环境变量，具体步骤参考鸿蒙Flutter SDK环境配置文档。

完成以上步骤后，即可启动Flutter应用的HarmonyOS适配开发。

六、命令行工具

鸿蒙化Flutter SDK的命令行工具与原生Flutter用法一致，支持创建工程、构建打包、设备调试等核心功能，常用命令如下表所示：

指令	功能描述	使用示例
`doctor`	检测开发环境配置完整性	`flutter doctor -v`
`create`	创建纯Flutter应用工程	`flutter create --platforms ohos,android,ios --org com.example my_app`
`create`	创建Flutter Module工程	`flutter create -t module my_module`
`create`	创建Flutter插件工程	`flutter create -t plugin --platforms ohos,android,ios my_plugin`
`create`	创建FFI插件工程	`flutter create -t plugin_ffi --platforms ohos,android,ios my_ffi_plugin`
`devices`	列出已连接的鸿蒙设备/模拟器	`flutter devices`
`build hap`	构建鸿蒙调试包	`flutter build hap --debug --target-platform ohos-arm64`
`build hap`	构建鸿蒙正式包	`flutter build hap --release --target-platform ohos-arm64`
`run`	在连接设备上运行应用	`flutter run`
`attach`	附加调试器到运行中的应用	`flutter attach`
`pub get`	拉取项目依赖	`flutter pub get`
`clean`	清除项目构建缓存	`flutter clean`
`pub cache clean`	清除全局Flutter依赖缓存	`flutter pub cache clean`

完整命令列表可参考鸿蒙Flutter SDK命令文档

七、调试方法

由于DevEco Studio与Dart开发工具的分工差异，调试需结合两个IDE协同完成，分两种工程类型说明：

1. 纯Flutter App类型

调试ArkTS代码（鸿蒙原生部分）
1. 连接鸿蒙真机或启动模拟器，开启开发者选项 与USB调试 ，参考文档鸿蒙开发者模式配置。
2. 在DevEco Studio中打开项目的ohos目录，配置调试签名。
3. 在Flutter工程根目录执行 flutter build hap 构建调试包。
4. 在ArkTS代码中打断点，点击DevEco Studio的Debug按钮启动调试。
调试Dart代码（Flutter部分）
1. 使用Android Studio/VSCode打开Flutter工程，定位到main.dart文件。
2. 直接点击Debug按钮运行应用，支持断点调试与热重载。

2. 混合开发类型

调试ArkTS代码：流程与纯Flutter App一致，在DevEco Studio中调试鸿蒙原生工程。
调试Dart代码：
1. 先通过DevEco Studio启动鸿蒙应用（已集成Flutter Module）。
2. 使用Android Studio/VSCode打开Flutter Module工程，执行 flutter attach 命令连接运行中的应用。
3. 连接成功后，即可断点调试Dart代码，并支持热重载。

八、三方库替换

三方库适配是Flutter应用迁移HarmonyOS的核心环节，需根据库类型采取不同策略：

库类型	适配策略	注意事项
纯Dart库	直接引用Pub仓库版本	无需适配，跨平台兼容性强
已适配鸿蒙的插件库	通过Git依赖方式引入	需在`pubspec.yaml`中配置Git仓库地址，示例： `dependencies:<br> fluro:<br> git:<br> url: https://gitcode.com/openharmony-tpc/flutter_fluro.git` 具体参考三方库依赖文档
未适配鸿蒙的插件库	替换为功能等价的鸿蒙化插件，或提交适配需求	需求提交地址：鸿蒙开发者论坛
自研插件库	自行适配鸿蒙平台	参考文档开发plugin

九、应用权限申请

HarmonyOS应用的权限管理严格遵循"声明即申请"原则，需完成配置声明 与代码申请两个步骤：

权限配置声明 在鸿蒙工程的module.json5配置文件中，逐个声明应用所需权限，参考文档鸿蒙应用权限声明。
权限动态申请 使用鸿蒙化插件 Permission_Handler 实现权限的动态申请，与Android平台的权限申请逻辑一致。
受限权限特殊处理 部分系统级权限（如系统相册管理、后台定位）属于受限权限，普通应用默认无法申请，处理策略如下：
- 评估应用场景是否符合权限申请条件，符合则准备材料向鸿蒙应用市场提交申请。
- 涉及受限权限的三方插件（如Wechat_Asset_Picker），优先替换为无受限权限的同类插件（如image_picker）。
- 跨端框架无法使用鸿蒙安全控件的，申请时需注明"应用基于Flutter跨端框架开发"，提高审批通过率。

十、打包和发布

Flutter应用适配HarmonyOS后的打包与发布流程，需区分测试阶段 与正式发布阶段，具体步骤如下：

1. 证书管理与环境隔离

阶段	签名方式	适用场景	配置要点
开发自测	自动签名	本地调试、功能验证	通过DevEco Studio开启自动签名，自动获取调试证书与ACL权限
正式发布	手动签名	应用市场上架	1. 在AGC平台申请发布证书 2. 提交ACL权限申请并通过审批 3. 开通应用所需的开放能力（如推送、地图）

2. 构建Release包

根据工程类型选择对应的打包方式：

纯Flutter应用
1. 替换调试证书为发布证书。
2. 执行命令构建App包：
  复制代码
```
flutter build app --release
```
3. 打包产物路径：ohos/build/outputs/default/*.app
混合开发应用
1. 将Flutter Module构建为Release版har包：
  复制代码
```
flutter build har --release
```
2. 在DevEco Studio中打开鸿蒙原生工程，替换原有har包。
3. 点击Build > Build App(s) 生成最终App包。
通过DevEco Studio打包（通用方式） 参考文档鸿蒙Flutter应用打包上架流程，直接通过IDE完成打包。

3. 应用发布

鸿蒙应用的发布渠道与流程如下：

正式发布 ：参考发布HarmonyOS应用，提交应用至AppGallery Connect，经审核后上架华为应用市场。
测试分发
- 邀请测试 ：参考邀请测试文档，指定用户群组进行灰度测试。
- 内部测试：将App包上传至自有服务器或第三方云平台，供团队内部测试。
- 蒲公英分发 ：参考蒲公英HarmonyOS应用分发，快速实现测试包的分发与管理。

欢迎大家加入开源鸿蒙跨平台开发者社区