鸿蒙与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 混合开发实战

鸿蒙工程集成 Flutter Module 踩坑总结

Flutter Module 打包为 HAR 发布到鸿蒙

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