Flutter 应用迁移至鸿蒙HarmonyOS

 

将 Flutter 应用适配到鸿蒙（HarmonyOS）主要有两种常用方式：源码集成 和 HAR 包集成。以下以 HAR 包集成为例，结合最新鸿蒙版 Flutter SDK（3.7.12 / 3.22 / 3.27.4）说明完整流程。

环境准备

• 安装 DevEco Studio（5.0+）并配置 JDK17

• 下载鸿蒙版 Flutter SDK：

git clone --branch oh-3.27.4-dev https://gitcode.com/openharmony-sig/flutter_flutter.git

　　

• 配置环境变量：

export FLUTTER_HOME=~/flutter_flutter
export FLUTTER_OHOS_STORAGE_BASE_URL=https://flutter-ohos.obs.cn-south-1.myhuaweicloud.com
export PATH=$FLUTTER_HOME/bin:$PATH

　　

创建 Flutter 模块并生成 HAR 包

• 创建模块：

flutter create --template=module my_flutter_module

　　

• 编译生成 HAR： flutter build har --release 会在 .ohos/har 下生成： flutter.har（引擎包） flutter_module.har（业务逻辑包）

鸿蒙应用集成

• 在鸿蒙工程中新建目录存放 HAR 包

• 在 oh-package.json5 中添加依赖：

{
 "dependencies": {
   "flutter": "file:./libs/flutter.har",
   "flutter_module": "file:./libs/flutter_module.har"
 }
}

　　

• 在 EntryAbility 中绑定 Flutter：

import { FlutterEntry, FlutterPage } from '@ohos/flutter_ohos';
@Entry
@Component
struct MyFlutterPage {
 private flutterEntry: FlutterEntry | null = null;
 private flutterView?: FlutterView;
 aboutToAppear() {
   this.flutterEntry = new FlutterEntry(getContext(this), {'route': '/home'});
   this.flutterView = this.flutterEntry.getFlutterView();
 }
 build() {
   Stack() {
     FlutterPage({ viewId: this.flutterView?.getId() })
   }
 }
}

　　

适配与调试建议

• 插件替换：纯 Dart 包可直接用，平台相关包需替换为鸿蒙版组件（参考 flutter_packages 鸿蒙适配列表）

• 调试：执行 flutter run 可热重载，首次需在 DevEco Studio 配置签名

• 平台判断：使用 Platform.isHarmonyOS 做条件分支，保持多端兼容

这样即可让现有 Flutter 应用快速运行在鸿蒙设备上，并调用原生能力。