鸿蒙 + Flutter 混合开发入门：从 0 到 1 搭建第一个跨端应用
鸿蒙 + Flutter 混合开发的核心是 “鸿蒙作为宿主，Flutter 作为模块嵌入”，通过FlutterEngine实现两者的通信；极简 Demo 的核心流程：创建鸿蒙工程→集成 Flutter 模块→编写 Flutter 页面→鸿蒙侧初始化引擎并加载 Flutter 页面；新手入门重点关注 “环境配置” 和 “引擎管理”，这是混合应用能正常运行的基础。
·
对于移动端开发初学者而言，鸿蒙（HarmonyOS）与 Flutter 的混合开发是兼具实用性和前瞻性的技术方向 —— 既可以复用 Flutter 的跨端优势，又能充分利用鸿蒙系统的原生能力。本文将以极简的方式，带大家从环境搭建到功能实现，快速完成一个能运行的鸿蒙 + Flutter 混合应用 Demo，代码量精简且注释清晰，重点聚焦核心流程，帮助初学者快速上手。
一、核心概念理解（新手必看）
在动手编码前，先理清两个关键概念，避免后续操作走弯路：
- 混合开发模式：本文采用 “鸿蒙原生工程为主，Flutter 作为模块嵌入” 的方式，即鸿蒙应用作为宿主，Flutter 负责部分页面 / 组件的开发，两者通过官方提供的通信通道交互。
- 核心依赖：需要安装 DevEco Studio（鸿蒙开发工具）、Flutter SDK（建议 3.10 + 版本），并确保环境变量配置正确（Flutter Doctor 检测无报错）。
二、环境准备（极简版）
1. 基础工具安装
- 安装 DevEco Studio 4.0+：官网下载对应系统版本，安装时勾选 “HarmonyOS SDK” 和 “Android SDK”；
- 安装 Flutter SDK：解压后配置
FLUTTER_HOME环境变量，添加flutter/bin到 PATH； - 验证环境：打开终端执行
flutter doctor，确保 “Android toolchain”“HarmonyOS toolchain” 均显示√。
2. 关键配置
在 DevEco Studio 中配置 Flutter 路径：
- 打开
File > Settings > Languages & Frameworks > Flutter； - 填写 Flutter SDK 路径，点击 “Apply” 完成配置。
三、创建混合工程（核心步骤）
1. 新建鸿蒙原生工程
- 打开 DevEco Studio，选择 “Create Project”；
- 模板选择 “Empty Ability”（空应用），点击 Next；
- 填写工程信息：
- Project name：HarmonyFlutterDemo
- Package name：com.example.harmonyflutterdemo
- Save location：自定义路径
- Language：ETS（鸿蒙主流开发语言）
- API Version：9+（建议）
- 点击 Finish，等待工程初始化完成。
2. 集成 Flutter 模块
- 打开终端，进入鸿蒙工程根目录，执行 Flutter 模块创建命令：
flutter create -t module flutter_module
执行完成后，工程目录下会新增flutter_module文件夹（Flutter 核心代码目录）。
- 配置鸿蒙工程依赖 Flutter：打开鸿蒙工程的
oh-package.json5文件，添加以下依赖：
{
"name": "harmony_flutter_demo",
"version": "1.0.0",
"dependencies": {
"@ohos/flutter": "file:./flutter_module"
}
}
- 同步依赖：点击 DevEco Studio 右上角的 “Sync Now”，等待依赖同步完成。
四、编写核心代码（极简版）
1. Flutter 侧：编写简单页面
进入flutter_module/lib/main.dart，替换原有代码为以下极简版（仅保留核心展示逻辑）：
import 'package:flutter/material.dart';
void main() => runApp(const MyFlutterApp());
// Flutter根组件
class MyFlutterApp extends StatelessWidget {
const MyFlutterApp({super.key});
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Flutter模块',
theme: ThemeData(primarySwatch: Colors.blue), // 主题色
home: const FlutterHomePage(), // 首页
);
}
}
// Flutter首页
class FlutterHomePage extends StatefulWidget {
const FlutterHomePage({super.key});
@override
State<FlutterHomePage> createState() => _FlutterHomePageState();
}
class _FlutterHomePageState extends State<FlutterHomePage> {
// 计数器（演示状态管理）
int _count = 0;
// 点击事件：计数器+1
void _incrementCount() {
setState(() {
_count++;
});
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(title: const Text('Flutter页面')),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
const Text(
'你点击按钮的次数：',
style: TextStyle(fontSize: 18),
),
// 显示计数器数值
Text(
'$_count',
style: const TextStyle(fontSize: 36, fontWeight: FontWeight.bold),
),
// 间隔
const SizedBox(height: 20),
// 文本展示（演示基础UI）
const Text(
'这是鸿蒙应用中嵌入的Flutter页面',
style: TextStyle(fontSize: 16, color: Colors.grey),
)
],
),
),
// 浮动按钮（演示交互）
floatingActionButton: FloatingActionButton(
onPressed: _incrementCount,
child: const Icon(Icons.add),
),
);
}
}
2. 鸿蒙侧：嵌入 Flutter 页面
- 打开鸿蒙工程的
entry/src/main/ets/MainAbility.ets，添加 Flutter 引擎初始化逻辑：
import Ability from '@ohos.application.Ability';
import window from '@ohos.window';
import { FlutterEngine, FlutterEngineManager } from '@ohos/flutter';
export default class MainAbility extends Ability {
// 全局Flutter引擎（复用引擎避免重复创建）
private flutterEngine: FlutterEngine | null = null;
onCreate(want, launchParam) {
super.onCreate(want, launchParam);
// 初始化Flutter引擎
this.initFlutterEngine();
}
// 初始化Flutter引擎
private initFlutterEngine() {
// 获取全局引擎管理器
const engineManager = FlutterEngineManager.getInstance();
// 创建Flutter引擎（指定入口）
this.flutterEngine = engineManager.createEngine('flutter_engine');
// 启动Flutter引擎（关联Flutter模块）
this.flutterEngine?.run({
bundleName: 'com.example.harmonyflutterdemo',
moduleName: 'flutter_module'
});
}
// 创建窗口时加载Flutter页面
async onWindowStageCreate(windowStage: window.WindowStage) {
super.onWindowStageCreate(windowStage);
// 获取窗口
const mainWindow = windowStage.getMainWindow();
if (mainWindow) {
// 加载Flutter页面到鸿蒙窗口
await mainWindow.loadContent('flutter://engine/flutter_engine');
// 显示窗口
windowStage.setUIContent(mainWindow);
}
}
// 销毁时释放Flutter引擎
onDestroy() {
super.onDestroy();
if (this.flutterEngine) {
FlutterEngineManager.getInstance().destroyEngine('flutter_engine');
this.flutterEngine = null;
}
}
}
- 配置鸿蒙工程的
module.json5（确保权限和入口正确）：打开entry/src/main/module.json5，确认abilities节点配置如下（无需额外修改，默认即可）：
"abilities": [
{
"name": "MainAbility",
"srcEntry": "./ets/MainAbility.ets",
"description": "$string:MainAbility_desc",
"icon": "$media:icon",
"label": "$string:MainAbility_label",
"type": "page",
"launchType": "standard"
}
]
五、运行应用（验证效果）
1. 选择运行设备
- 连接鸿蒙真机（开启开发者模式），或创建鸿蒙模拟器（DevEco Studio 中点击
Tools > Device Manager）； - 在 DevEco Studio 顶部选择对应的设备。
2. 启动应用
点击 DevEco Studio 右上角的 “Run” 按钮（绿色三角），等待编译和安装完成：
- 编译过程中会自动打包 Flutter 模块到鸿蒙应用中；
- 安装完成后，设备上会显示 “HarmonyFlutterDemo” 应用图标；
- 点击打开应用，即可看到嵌入的 Flutter 页面，点击浮动按钮可实现计数器加 1。
六、核心知识点解析（新手易懂）
1. Flutter 侧核心代码解析
| 代码片段 | 作用 |
|---|---|
StatelessWidget/StatefulWidget |
Flutter 的两种核心组件：无状态组件（静态 UI）、有状态组件（动态 UI，如计数器） |
setState() |
Flutter 状态更新方法，调用后会重新构建 UI，实现 “数据驱动视图” |
Scaffold |
Flutter 的基础页面骨架，包含 AppBar、Body、FloatingActionButton 等常用布局 |
MaterialApp |
Flutter 的应用根组件，配置主题、路由等全局信息 |
2. 鸿蒙侧核心代码解析
| 代码片段 | 作用 |
|---|---|
FlutterEngine |
鸿蒙与 Flutter 的通信核心，负责管理 Flutter 运行环境 |
createEngine() |
创建 Flutter 引擎实例（指定唯一标识，避免冲突） |
run() |
启动 Flutter 引擎，关联 Flutter 模块代码 |
loadContent('flutter://engine/xxx') |
将 Flutter 页面加载到鸿蒙窗口中 |
3. 常见问题与解决
- 编译报错 “找不到 Flutter 模块”：检查
oh-package.json5中的依赖路径是否正确，执行flutter pub get（进入 flutter_module 目录）； - 模拟器运行黑屏：确保模拟器版本为 HarmonyOS 3.0+，重启模拟器后重新运行；
- Flutter 页面样式异常：检查 Flutter SDK 版本与鸿蒙 Flutter 插件版本兼容（建议 Flutter 3.10+）。
七、扩展与进阶方向（新手可尝试）
完成基础 Demo 后，初学者可尝试以下简单扩展，加深理解：
- 添加原生交互：在鸿蒙页面添加按钮，点击后调用 Flutter 方法修改计数器数值；
- 更换 UI 样式：修改 Flutter 的主题色、按钮样式，观察鸿蒙应用中的显示效果；
- 添加简单布局：在 Flutter 页面中添加图片（
Image.network('图片URL')），实现图文展示。
总结
关键点回顾
- 鸿蒙 + Flutter 混合开发的核心是 “鸿蒙作为宿主，Flutter 作为模块嵌入”，通过
FlutterEngine实现两者的通信； - 极简 Demo 的核心流程：创建鸿蒙工程→集成 Flutter 模块→编写 Flutter 页面→鸿蒙侧初始化引擎并加载 Flutter 页面；
- 新手入门重点关注 “环境配置” 和 “引擎管理”，这是混合应用能正常运行的基础。
开源鸿蒙跨平台开发社区汇聚开发者与厂商，共建“一次开发，多端部署”的开源生态，致力于降低跨端开发门槛，推动万物智联创新。
更多推荐
11
0- 0
已为社区贡献33条内容
所有评论(0)