鸿蒙应用采用混合开发模式集成 Flutter Module，主要是为了解决代码复用、跨平台一致性以及利用 Flutter 丰富的 UI 生态。对于已有 Flutter 业务（如复杂动画、图表组件）或需要同时覆盖 Android、iOS 和鸿蒙的场景，直接复用 Flutter 模块能极大降低开发成本，避免重复造轮子。

以下以 HarmonyOS NEXT 为例，手把手教你如何通过源码集成的方式将 Flutter Module 嵌入到鸿蒙原生项目中。

---

一、 开发环境准备（关键前置步骤）

在开始之前，必须确保电脑上同时存在两套环境，因为鸿蒙和 Flutter 的工具链目前是独立的。

环境组件	版本/类型要求	作用
DevEco Studio	5.0.0 Beta2 及以上	鸿蒙官方 IDE，用于开发原生工程。
Flutter SDK	3.24.0 及以上（适配 OpenHarmony）	包含 Dart 编译器和鸿蒙构建工具。
JDK	JDK 17	开发运行基础环境。
Node.js	v14.x+	部分构建脚本依赖。

特别注意：下载 Flutter SDK 时，务必确认该版本已包含 OpenHarmony 支持（通常由官方或社区适配版本提供）。安装完成后，需配置环境变量，确保命令行输入 flutter doctor 能检测到鸿蒙设备（显示为 HarmonyOS support installed）。

---

二、 创建 Flutter Module 模块

Flutter Module 是一个专门用于被其他原生项目引用的 Flutter 项目模板，它不能独立运行，但可以被编译成动态库或静态库。

1. 创建命令：
   打开终端（CMD 或 PowerShell），执行以下命令创建一个名为 my_flutter_module 的模块：

   # 创建 Flutter Module 
   flutter create --template=module my_flutter_module
   

2. 编写测试代码：
   进入 my_flutter_module/lib/main.dart，修改默认代码，以便后续验证集成效果。

   // my_flutter_module/lib/main.dart
   import 'package:flutter/material.dart';
   
   void main() => runApp(MyFlutterApp());
   
   class MyFlutterApp extends StatelessWidget {
     @override
     Widget build(BuildContext context) {
       return MaterialApp(
         home: Scaffold(
           appBar: AppBar(title: Text('Flutter 混合页面')),
           body: Center(
             child: Text('这是来自 Flutter 的内容！', style: TextStyle(fontSize: 24)),
           ),
         ),
       );
     }
   }
   

---

三、 在鸿蒙原生项目中集成 Module

这里我们采用源码集成的方式，这种方式调试最方便，适合开发阶段。

1. 创建鸿蒙工程

使用 DevEco Studio 创建一个标准的 "Empty Ability" 工程，命名为 HarmonyFlutterMix。

2. 配置项目依赖

我们需要在鸿蒙工程的 oh-package.json5 文件中声明对 Flutter Module 的本地路径依赖。

• 打开文件：HarmonyFlutterMix/oh-package.json5

• 添加依赖：在 dependencies 字段中添加如下配置。注意路径要指向你的 Flutter Module 根目录。

  {
    "name": "harmonyfluttermix",
    "version": "1.0.0",
    "description": "Please describe the basic information.",
    "main": "",
    "author": "",
    "license": "",
    "dependencies": {
      // 添加本地 Flutter Module 依赖
      "@ohos/flutter_module": "file:../../my_flutter_module",
      // ... 其他依赖
    },
    "devDependencies": {
      "@ohos/hypium": "1.0.18"
    }
  }
  

• 同步依赖：保存文件后，点击 DevEco Studio 编辑器右上角的 Sync Now 按钮。IDE 会自动将 Flutter Module 的代码链接到鸿蒙工程中，并生成必要的 .har 包索引。

---

四、 修改入口 Ability 以加载 Flutter

这是混合开发最核心的一步。我们需要将默认的 UIAbility 改造为继承自 FlutterAbility，以便应用启动时能初始化 Flutter 引擎。

1. 修改 EntryAbility.ets

找到 entry/src/main/ets/entryability/EntryAbility.ets，进行如下修改：

// entry/src/main/ets/entryability/EntryAbility.ets
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import { FlutterAbility } from '@ohos/flutter_ohos'; // 引入 Flutter 基类 

export default class EntryAbility extends FlutterAbility { // 继承 FlutterAbility 而非 UIAbility
  // FlutterAbility 内部已处理了引擎的生命周期，通常只需保留默认实现
  // 如果需要获取 engine 实例进行插件注册，可重写 onCreate
  onCreate(want, launchParam) {
    super.onCreate(want, launchParam);
    console.info('FlutterAbility onCreate');
  }

  onDestroy() {
    super.onDestroy();
    console.info('FlutterAbility onDestroy');
  }
}

2. 配置 module.json5

为了确保 FlutterAbility 正常工作，需要检查 entry/src/main/module.json5 中的配置。

• 删除 pages 配置：Flutter 页面由引擎管理，通常不需要在这里配置原生 pages 路由。
• 保留 launchType：确保为 standard。

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "default",
      "tablet"
    ],
    // 注意：如果应用完全由 Flutter 接管，这里可以清空 pages
    // "pages": [], 
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:entryability_desc",
        "icon": "$media:icon",
        "label": "$string:entry_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "launchType": "standard" // 标准启动模式
      }
    ]
  }
}

---

五、 运行与验证

1. 连接设备/模拟器：确保 DevEco Studio 已连接鸿蒙真机或模拟器（API 12+）。
2. 运行项目：点击 DevEco Studio 的运行按钮。
3. 预期结果：
   • 应用启动后，首先会显示一个短暂的鸿蒙启动页（如有配置）。
   • 随后，屏幕上会出现我们在 main.dart 中编写的 Flutter 界面（带有 "Flutter 混合页面" 标题和文本）。

---

六、 为什么使用混合开发？（原理解析）

通过上述步骤，我们实际上是在鸿蒙应用内部启动了一个 Flutter Engine（引擎）。这个引擎负责渲染 Flutter 的 UI，并将其绘制在鸿蒙提供的 Surface 上。

优势	详细解释
极致的 UI 复用	Flutter 的 Skia 渲染引擎保证了 UI 在 Android、iOS 和 HarmonyOS 上的一致性。一套代码，三端运行，无需针对鸿蒙重绘复杂的自定义控件。
平滑迁移	对于成熟的 App，不需要推倒重来。可以将新增模块用 Flutter 开发，或者逐步将旧页面迁移到 Flutter Module 中，实现“渐进式重构”。
高性能渲染	Flutter 采用 AOT 编译和原生渲染，在处理复杂列表、动画（如 Lottie 动画）时，通常比 WebView 混合开发方案更流畅，体验接近原生。
生态互补	鸿蒙原生擅长处理系统能力调用（如蓝牙、NFC、分布式流转），Flutter 擅长 UI 交互和业务逻辑。两者结合，可以发挥各自的长处。

七、 常见问题与进阶

• 插件兼容性：如果 Flutter 代码中使用了第三方插件（如 shared_preferences），必须确保该插件支持 OpenHarmony 平台。如果不支持，需要在鸿蒙侧编写原生代码并通过 Platform Channel（平台通道）自行实现。
• 内存管理：Flutter 引擎会占用一定的内存（通常在 20MB-40MB 起步）。在低端机型上，需要注意及时销毁引擎实例（FlutterEngine.destroy()）以释放资源。

通过以上步骤，即使是零基础的小白，也能成功搭建起鸿蒙与 Flutter 的混合开发环境，体验双端技术融合带来的开发效率提升。