鸿蒙与Flutter的混合开发

tips

以前实践过Android/iOS 混合开发模式,鉴于历史债务,老项目难以移植为纯Flutter Application类型的项目,只能在原有项目基础上将Flutter module嵌入为aar 或 framework,或干脆以源码模式引入, 然后到了鸿蒙时代,这个问题依然照旧,所以就照旧吧,将Flutter module嵌入到 ohos 中

Flutter + 鸿蒙混合开发实践:Flutter Module 集成到鸿蒙原生应用

随着鸿蒙生态的发展,越来越多开发者希望将 Flutter 这一跨平台技术引入到鸿蒙应用中,以提升开发效率和多端统一体验。本文结合实践经验和社区分享,系统讲解如何在鸿蒙原生应用中集成 Flutter Module,并深入分析可能遇到的问题及解决方案。


技术准备

1. 使用鸿蒙定制版 Flutter SDK

官方和社区共同维护了适配鸿蒙的 Flutter SDK:gitcode.com/openharmony...

具体配置可以看上边链接,单独取出来我需要的mac本地的环境配置

环境配置示例:
bash 复制代码
 #依赖缓存
 export PUB_CACHE=D:/PUB(自定义路径)

 # 国内镜像
 export PUB_HOSTED_URL=https://pub.flutter-io.cn
 export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

 # 拉取下来的flutter_flutter/bin目录
 export PATH=/home/<user>/ohos/flutter_flutter/bin:$PATH

 # HamonyOS SDK
 export TOOL_HOME=/Applications/DevEco-Studio.app/Contents # mac环境
 export DEVECO_SDK_HOME=$TOOL_HOME/sdk # command-line-tools/sdk
 export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH # command-line-tools/ohpm/bin
 export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH # command-line-tools/hvigor/bin
 export PATH=$TOOL_HOME/tools/node/bin:$PATH # command-line-tools/tool/node/bin

示例输出:

csharp 复制代码
Flutter 3.27.4-dev on OpenHarmony 3.2
Dart 3.2.3

注意事项:

  • 必须配置 PATH 环境变量。
  • IDE 推荐使用 DevEco Studio。

👉 思考: 鸿蒙对 Flutter 引擎进行了修改,因此不能直接用官方 Flutter SDK,否则运行时会缺少必要适配层。


集成方式对比:源码集成 vs HAR 包集成

方式一:源码集成

  • 将 Flutter Module 作为子模块引入鸿蒙工程。
  • 鸿蒙原生端通过 FlutterBoost 启动 Flutter 页面。
bash 复制代码
flutter create -t module flutter_module
text 复制代码
entry/
├── src/main/ets
├── flutter_module -> /actual/path/to/flutter_module

✅ 优势:

  • 支持热重载。
  • 修改灵活,开发效率高。

❌ 缺点:

  • 工程结构复杂,容易踩坑。
  • 编译速度较慢。

方式二:HAR 包集成

bash 复制代码
cd flutter_module
flutter build har

生成:

bash 复制代码
build/flutter_module/flutter_module.har

.har 拷贝到鸿蒙宿主 libs 目录,并在 build.gradle 中声明依赖:

gradle 复制代码
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.har'])
}

✅ 优势:

  • 模块解耦。
  • 发布更方便。

❌ 缺点:

  • 无法热重载。
  • 迭代更新成本高。

👉 建议: 开发阶段源码集成,发布阶段 HAR 集成。


项目结构示意图

css 复制代码
my_harmony_app/
├── entry/
│   ├── src/main/ets/
│   ├── libs/
│   │   └── flutter_module.har
│   └── build.gradle
└── flutter_module/   (源码集成时)

实践步骤详解

step 1 总体目录

本示例的目录名为 ohos_flutter_module_demo, 我们将原生鸿蒙工程和 Flutter 模块都在这个目录下创建。

Step 2:创建 Flutter Module

bash 复制代码
flutter create -t module flutter_module

总体目录如下

bash 复制代码
ohos_flutter_module_demo
├── my_flutter_module
├── ohos_app

问题

假如你执行flutter create... 的时候报错了,例如

vbnet 复制代码
Building flutter tool...

Resolving dependencies... (2:07.3s)

Git error. Command: `git clone --mirror https://gitcode.com/openharmony-sig/fluttertpc_dart_native /Users/moon/Documents/hmos/pub_cache/_temp/dirKwX3Yk`

stdout: 

stderr: Cloning into bare repository '/Users/moon/Documents/hmos/pub_cache/_temp/dirKwX3Yk'...

fatal: unable to access 'https://gitcode.com/openharmony-sig/fluttertpc_dart_native/': Failed to connect to 127.0.0.1 port 1087 after 0 ms: Couldn't connect to server

  


exit code: 128

Error: Unable to 'pub upgrade' flutter tool. Retrying in five seconds... (9 tries left)

Resolving dependencies... (1:04.0s)

Git error. Command: `git clone --mirror https://gitcode.com/openharmony-sig/fluttertpc_dart_native /Users/moon/Documents/hmos/pub_cache/_temp/dirkSMn2Y`

stdout: 

stderr: Cloning into bare repository '/Users/moon/Documents/hmos/pub_cache/_temp/dirkSMn2Y'...

fatal: unable to access 'https://gitcode.com/openharmony-sig/fluttertpc_dart_native/': Failed to connect to 127.0.0.1 port 1087 after 0 ms: Couldn't connect to server

则是因为你的ohos-flutter-sdk 里的pubspec.yaml 文件里的依赖因为代理问题下载不到了,位置如下目录

bash 复制代码
/flutter/packages/flutter_tools/pubspec.yaml

我的解决方案就是将(gitcode.com/openharmony... 引用

然后执行create module命令即可

sql 复制代码
Moon:FlutterHyOhos moon$ flutter create --template=module my_flutter_module

Building flutter tool...

Resolving dependencies... (11.1s)

Downloading packages... (8.5s)

Got dependencies.

**Flutter assets will be downloaded from https://storage.flutter-io.cn. Make sure you******

**trust this source!******

Downloading Material fonts...                                    2,367ms

Downloading Gradle Wrapper...                                      288ms

Downloading package sky_engine...                                   4.4s

Downloading package flutter_gpu...                                 359ms

Downloading flutter_patched_sdk tools...                         1,209ms

Downloading flutter_patched_sdk_product tools...                    5.6s

Downloading darwin-arm64 tools...                                   7.0s

Downloading libimobiledevice...                                    275ms

Downloading usbmuxd...                                             299ms

Downloading libplist...                                            275ms

Downloading openssl...                                             396ms

Downloading ios-deploy...                                          286ms

Downloading darwin-arm64/font-subset tools...                      483ms

Developer identity "Apple Development: xx" selected for iOS code

signing

Creating project my_flutter_module...

Resolving dependencies in `my_flutter_module`... (3.4s)

Downloading packages... (2.7s)

Got dependencies in `my_flutter_module`.

Developer identity "Apple Development: xx" selected for iOS code

signing

Developer identity "Apple Development: xx" selected for iOS code

signing

Wrote 12 files.

  


All done!

创建成功后目录如下

Step 3:引入到鸿蒙主工程

可以看到,我们将 Flutter 模块放在了与 ohos_app 项目同级。my_flutter_module 中自动创建了 .ohos 目录, 这也是一个简单的鸿蒙项目,不过会包含一个名为 flutter_module 的模块。

由于开源鸿蒙官方文档中给出的方案并不理想,这里我们使用软连接的方案,来实现基于源码的联动开发。

正常情况下,my_flutter_module 创建成功后,会包含一个 .ohos 目录,这个目录是一个鸿蒙工程(里面包含 flutter_module 模块),它可以做为 Flutter 的宿主运行。但是这个宿主工程,并不是我们期望的 ohos_app, 两个工程没有任何关联,所以也无法联动开发。

bash 复制代码
# ⚠️首先需要将flutter_module复制到鸿蒙宿主工程,避免出现错误 "Error: Parse ohos module.json5 error: Error: Can not found module.json5 at"
cp -r my_flutter_module/.ohos/flutter_module ohos_app/

# 进入目录 my_flutter_module,在此处创建软连接
cd my_flutter_module
#  删除 .ohos 目录
rm -rf .ohos
# 创建软连接至鸿蒙宿主工程,根据需要更改目录名称
ln -s ../ohos_app .ohos

Step 4:更新项目

arduino 复制代码
经过上操作后,我们运行 `flutter run` , 让 Flutter 来自动更新项目配置
flutter run

可以看到控制台的输出

sql 复制代码
Launching lib/main.dart on FMR0224904009635 in debug mode...
start hap build...
...
Running Hvigor task assembleHap...                                 95.7s
✓ Built ../ohos_app/entry/build/default/outputs/default/entry-default-signed.hap.
installing hap. bundleName: com.shaohushuo.ohos_app

Step 5:启动 Flutter 页面

app 启动后,你会发现,仍然是鸿蒙原生的界面 你需要 1 初始化Flutter引擎,将Ability 主页改为

scala 复制代码
import { FlutterAbility, FlutterEngine } from '@ohos/flutter_ohos';
import { GeneratedPluginRegistrant } from '@ohos/flutter_module';

export default class EntryAbility extends FlutterAbility {
  configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)
    GeneratedPluginRegistrant.registerWith(flutterEngine);
  }
}

但是我暂时不知道如何将默认页面直接加载Flutter page,因为涉及引擎问题,我测试新建一个FlutterAbility来承载FlutterView , 原生的EntryAbility 在引擎加载完毕后立刻启动FlutterAbility,

typescript 复制代码
import { FlutterEntry, FlutterPage, FlutterView } from '@ohos/flutter_ohos'

@Entry
@Component
struct Index {

  private flutterEntry?: FlutterEntry;
  private flutterView?: FlutterView;

  aboutToAppear() {
    this.flutterEntry = new FlutterEntry(getContext(this));
    this.flutterEntry.aboutToAppear();
    this.flutterView = this.flutterEntry.getFlutterView();
  }

  aboutToDisappear() {
    this.flutterEntry?.aboutToDisappear();
  }

  onPageShow() {
    this.flutterEntry?.onPageShow();
  }

  onPageHide() {
    this.flutterEntry?.onPageHide();
  }

  build() {
    RelativeContainer() {
      FlutterPage({ viewId: this.flutterView?.getId()})
    }
  }
}

跳转方法

css 复制代码
router.pushUrl({ url: 'pages/FlutterContainerPage'})

哦了,暂时粗略写这么多,以下都是些参考


常见问题与解决方案

问题 解决方案
找不到 Flutter SDK 确认 PATH 配置无误
软链接失效 改为物理复制或者 CI 自动同步
HAR 包运行闪退/白屏 检查 SDK 版本一致性、权限配置
热重载失败 只能在源码集成下生效
常见错误示例:
text 复制代码
[ERROR] Unable to locate Flutter Engine.
解决:确认使用的是鸿蒙 Flutter SDK。

自动化优化建议

  • 使用脚本自动创建软链或同步 Module 代码。
  • HAR 打包可以集成到 CI/CD 中,确保一致性。

示例脚本片段:

bash 复制代码
#!/bin/bash
ln -sf /Users/xxx/flutter_module ./entry/flutter_module

📌 参考阅读:


如果本文对你有帮助,欢迎点赞、转发、收藏,一起交流鸿蒙 + Flutter 开发经验!

相关推荐
Keya1 小时前
在HarmonyOS(鸿蒙)中H5页面中的视频不会自动播放
app·harmonyos·arkts
江上清风山间明月3 小时前
一周掌握Flutter开发--10. 结构与设计模式
flutter·设计模式·快速
HMS Core4 小时前
用AI重塑游戏体验:《诛仙2》携手HarmonyOS SDK实现性能与功耗双赢
人工智能·游戏·harmonyos
儿歌八万首4 小时前
HarmonyOS中各种动画的使用介绍
华为·harmonyos·arkts·arkui
dilvx4 小时前
配置鸿蒙 fastboot
华为·harmonyos
儿歌八万首4 小时前
HarmonyOS 中状态管理 V2和 V1 的区别
harmonyos·component·arkui
鸿蒙小林4 小时前
HarmonyOS应用开发者高级试题2025年7月部分单选题
harmonyos·开发者认证
zkmall5 小时前
鸿蒙商城开发:ZKmall开源商城系统特性适配与性能优化
性能优化·开源·harmonyos
HarmonyOS小助手6 小时前
从航旅纵横到东南亚Grab:鸿蒙生态的“星辰大海”,由开发者共绘
harmonyos·鸿蒙·鸿蒙生态