前言

随着 HarmonyOS NEXT 正式进入纯鸿蒙时代，越来越多企业开始将已有 Flutter 项目迁移至 HarmonyOS NEXT，实现 Android + iOS + HarmonyOS 三端统一开发。

Flutter 本身官方并未直接支持 HarmonyOS，因此鸿蒙团队提供了适配版本：

Flutter for OpenHarmony（Flutter OHOS）

通过该版本，可以让 Flutter Engine 运行在 HarmonyOS NEXT 上。

本文将从 零开始，详细介绍 HarmonyOS Flutter 环境搭建流程，包括：

• Flutter 与 HarmonyOS 的关系
• 环境安装
• SDK 下载
• DevEco Studio 配置
• flutter doctor
• 创建 Flutter 项目
• 运行到真机
• 常见问题解决

全文约 20000 字。

---

一、HarmonyOS 能运行 Flutter 吗？

答案：

可以。

但是需要注意：

HarmonyOS NEXT 并不是直接运行官方 Flutter，而是运行：

Flutter OpenHarmony

或者叫：

Flutter OHOS

其整体架构如下：

Flutter App
        │
 Dart
        │
 Flutter Framework
        │
 Flutter Engine(OpenHarmony)
        │
 ArkUI Native
        │
 HarmonyOS NEXT

因此：

不是修改 Flutter。

而是：

替换 Flutter Engine。

---

二、Flutter OHOS 的特点

支持：

✅ Dart

✅ StatefulWidget

✅ Material

✅ Cupertino

✅ Animation

✅ CustomPaint

✅ MethodChannel

✅ Plugin

✅ PlatformView

✅ 热重载（Hot Reload）

目前已经可以满足绝大多数 Flutter 项目。

---

三、环境要求

建议配置：

软件	推荐版本
macOS	13+
Windows	Win11
DevEco Studio	5.x
HarmonyOS SDK	API12+
Node.js	18+
Git	最新版
Flutter OHOS	最新版

---

四、安装 DevEco Studio

首先安装：

DevEco Studio

安装完成以后：

SDK Manager

安装：

HarmonyOS SDK

建议安装：

API12

ArkTS

Toolchains

Native

Previewer

安装完成以后确认：

~/Huawei/Sdk

目录存在。

例如：

Sdk
 ├──12
 ├──toolchains
 ├──previewer
 ├──openharmony

---

五、安装 Git

Flutter 需要 Git。

Mac：

brew install git

Windows：

官网下载：

Git for Windows

验证：

git --version

输出：

git version 2.x.x

---

六、安装 Node.js

HarmonyOS 构建依赖 Node。

安装：

Node.js LTS

验证：

node -v

例如：

v20

再验证：

npm -v

---

七、安装 Python（可选）

部分脚本需要：

Python3

验证：

python3 --version

---

八、下载 Flutter OHOS

与官方 Flutter 不同。

需要下载：

Flutter OpenHarmony SDK

解压：

~/development/flutter_ohos

例如：

flutter
    bin
    cache
    packages

---

九、配置环境变量

Mac：

编辑：

~/.zshrc

增加：

export PATH=$PATH:/Users/xxx/flutter/bin

刷新：

source ~/.zshrc

Windows：

环境变量：

PATH

D:\flutter\bin

---

十、验证 Flutter

执行：

flutter --version

输出：

Flutter 3.x

然后：

flutter doctor

正常情况下：

No issues found!

---

十一、配置 Harmony SDK

Flutter 需要知道：

Harmony SDK

位置。

例如：

/Users/xxx/Huawei/Sdk

或者：

C:\Huawei\Sdk

配置：

HOS_SDK_HOME

例如：

export HOS_SDK_HOME=/Users/test/Huawei/Sdk

---

十二、安装 OHOS Target

执行：

flutter doctor

看到：

OHOS Toolchain

如果：

✗

说明：

没有配置成功。

---

十三、检查 Doctor

执行：

flutter doctor -v

例如：

Flutter

Android toolchain

Chrome

OHOS toolchain

DevEco Studio

全部：

✓

即可。

---

十四、创建 Flutter 项目

执行：

flutter create hello_harmony

目录：

android

ios

lib

pubspec.yaml

然后：

ohos

如果没有：

需要生成：

flutter create .

---

十五、项目目录介绍

hello

android

ios

ohos

linux

macos

windows

web

lib

test

新增：

ohos

就是鸿蒙工程。

---

十六、运行 Pub

flutter pub get

下载依赖。

---

十七、打开 DevEco

打开：

ohos

工程。

等待：

Sync

完成。

---

十八、配置签名

进入：

Project

Signing Configs

配置：

Debug

即可。

---

十九、连接真机

开启：

开发者模式

USB：

允许调试

查看：

hdc list targets

输出：

127.0.0.1

说明连接成功。

---

二十、运行 Flutter

执行：

flutter run

输出：

Launching lib/main.dart...

随后：

Installing...

最后：

Syncing files...

即可。

---

二十一、Hot Reload

修改：

Text("Hello")

变成：

Text("HarmonyOS")

按：

r

立即刷新。

---

二十二、Hot Restart

按：

R

重新启动。

---

二十三、Release 打包

执行：

flutter build hap

输出：

build/ohos

生成：

.hap

---

二十四、常见问题

1、找不到 Flutter

flutter command not found

解决：

检查：

PATH

---

2、Doctor 红叉

检查：

SDK

路径。

---

3、无法识别 hdc

配置：

toolchains

路径。

---

4、Pub 下载失败

配置国内镜像：

export PUB_HOSTED_URL=https://pub.flutter-io.cn

export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn

---

5、真机无法安装

检查：

签名

Bundle Name

SDK Version

---

二十五、Flutter 与 ArkUI 如何通信

Flutter 与 HarmonyOS 原生之间通常通过 Platform Channel（MethodChannel） 进行双向通信：

Flutter(Dart)
        │
MethodChannel
        │
ArkTS
        │
HarmonyOS API

常见场景包括：

• 调用相机
• 文件选择
• 蓝牙
• NFC
• 定位
• 推送
• 支付
• 系统能力调用

对于需要高性能或系统级能力的功能，建议封装为 HarmonyOS 原生插件，再通过 Flutter 调用。

---

二十六、Flutter 插件适配 HarmonyOS

并非所有 Flutter 插件都已适配 HarmonyOS。

建议优先选择：

• 已支持 OpenHarmony/HarmonyOS 的插件
• 官方或社区维护的 HarmonyOS 分支
• 自行实现 Platform Channel 适配层

对于仅依赖 Dart 层逻辑的插件（如网络请求、JSON 解析、状态管理等），通常无需修改即可使用。

---

二十七、开发建议

为了提升 Flutter + HarmonyOS 的开发效率，建议遵循以下实践：

• 保持 Flutter SDK 与 HarmonyOS Flutter SDK 版本一致。
• DevEco Studio 与 HarmonyOS SDK 使用官方推荐版本。
• 使用 Git 管理 Flutter 与鸿蒙适配代码。
• 优先在真机调试，避免仅依赖 Preview。
• 将原生能力封装成插件，保持 Dart 层业务代码统一。

---

总结

Flutter 与 HarmonyOS NEXT 混合开发已经具备较高的成熟度，通过 Flutter OpenHarmony（Flutter OHOS） 可以实现 Flutter 应用在 HarmonyOS NEXT 上运行，并复用大量现有业务代码。

完整的环境搭建流程可概括为：

1. 安装 DevEco Studio 与 HarmonyOS SDK。
2. 安装 Git、Node.js 等基础工具。
3. 下载并配置 Flutter OpenHarmony SDK。
4. 配置环境变量并通过 flutter doctor 检查环境。
5. 创建 Flutter 项目并生成 ohos 工程。
6. 配置签名、连接真机、运行调试。
7. 使用 flutter build hap 打包生成 HarmonyOS 安装包。