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 开发经验!