鸿蒙 + Flutter 混合开发环境从零配置到项目建立

鸿蒙 + Flutter 混合开发环境从零配置

这份文档教你从一台干净的 Windows 电脑开始，把鸿蒙原生工程和 Flutter 混合开发环境搭起来，直到能在真机上跑出一个 Flutter 页面。

下面是已经在本机验证通过的一套版本组合。如果你照着装成完全一样的版本，能少踩很多坑。

一、已验证的版本清单

工具 具体版本 用途 是否需要单独装
DevEco Studio 6.0.2.660 鸿蒙开发工具，内含 SDK、JDK、ohpm、hvigor 需要
Flutter 3.27.5-ohos-1.0.4 鸿蒙专用 Flutter SDK 需要
Dart 3.6.2 随 Flutter 自带 不需要
Java（JBR） 17 DevEco Studio 内置，负责编译 一般不需要
OpenHarmony SDK API 22（默认） 随 DevEco Studio 下载 不需要
ohpm 6.0.1 鸿蒙依赖管理 随 DevEco 内置
Node.js v24.19.0 hvigor 构建需要 随 DevEco 内置

最关键的版本点：Flutter 必须用带 -ohos 的鸿蒙版，不能装官网普通 Flutter。

二、安装 DevEco Studio 6.0.2

2.1 下载地址

华为开发者官网的 DevEco Studio 下载页：

https://developer.huawei.com/consumer/cn/deveco-studio/

选择 Windows 版，版本选 6.0.x（本机是 6.0.2.660）。

2.2 安装

  1. 双击安装包，一路下一步。
  2. 安装完成后打开 DevEco Studio，首次启动会引导下载 SDK。
  3. 在设置里确认 SDK 的默认版本是 API 22。
  4. DevEco Studio 会自动带上下面这些东西，不用再单独装：
OpenHarmony SDK：
D:\dev\DevEco Studio\sdk

内置 Java（JBR 21.0.8）：
D:\dev\DevEco Studio\jbr

ohpm：
D:\dev\DevEco Studio\tools\ohpm\bin\ohpm.bat

hvigor：
D:\dev\DevEco Studio\tools\hvigor\bin\hvigorw.bat

Node.js：
D:\dev\DevEco Studio\tools\node

三、Java 怎么处理

这里单独说明，因为 Java 版本最容易踩坑，如果需要单独安装，请下载安装java jdk17版本（ https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html ）。

正常情况：不需要单独装 Java。

鸿蒙 Flutter-OH 开发用的 Java 是 DevEco Studio 自带的 JBR，版本是：

Java 21.0.8（JBR-21.0.8+1-1038.71-jcef）

DevEco Studio 6.0 已经内置了它，命令行构建 hvigor 也会走这套环境。

什么时候需要单独装：

如果你在命令行里跑 hvigorw 时报 JDK 相关错误，或者系统里装了很老的 Java 8 干扰了构建，才需要手动装一个独立 JDK 并配置 JAVA_HOME。

推荐装 JDK 17（和 DevEco Studio 6.0 内置版本一致）。

3.1 下载地址

推荐 Adoptium Temurin 21，免费、不需要登录：

https://adoptium.net/temurin/releases/?version=21&os=windows&arch=x64&package=jdk

也可以去 Oracle 官方下 JDK 21：

https://www.oracle.com/java/technologies/downloads/#java21

3.2 用命令行安装（Windows 11 自带 winget）

winget install EclipseAdoptium.Temurin.21.JDK

3.3 配置环境变量

装好后设两个环境变量：

JAVA_HOME = C:\Program Files\Eclipse Adoptium\jdk-21.0.x-hotspot

并把下面这行加到 Path：

%JAVA_HOME%\bin

验证：

java -version

应该输出类似：

openjdk version "21.0.x"

注意：如果系统里同时有 Java 8，不要让它抢在 JDK 21 前面，否则 hvigor 构建可能报错。

四、安装 Flutter-OH SDK

4.1 下载方式

鸿蒙版 Flutter 必须用 git clone 拉取，不要下载 zip，否则 git 子模块会丢失，后面编译会报错。

仓库地址：

https://gitcode.com/openharmony-tpc/flutter_flutter.git

4.2 安装命令

克隆 oh-3.27.4-dev 分支（这个分支对应 3.27.x 的鸿蒙版本）：

git clone -b oh-3.27.4-dev https://gitcode.com/openharmony-tpc/flutter_flutter.git D:\flutter_flutter

或者先克隆仓库，再切换到指定标签：

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git D:\flutter_flutter
cd D:\flutter_flutter
git checkout 3.27.5-ohos-1.0.4

本机验证过的版本是：

Flutter 3.27.5-ohos-1.0.4
Dart 3.6.2

4.3 验证

D:\flutter_flutter\bin\flutter.bat --version

输出里带 -ohos 就说明装对了。

五、配置环境变量

把下面两个变量加到系统环境变量：

HOS_SDK_HOME = D:\dev\DevEco Studio\sdk
DEVECO_SDK_HOME = D:\dev\DevEco Studio\sdk

再把下面四个目录追加到 Path：

D:\flutter_flutter\bin
D:\dev\DevEco Studio\tools\ohpm\bin
D:\dev\DevEco Studio\tools\hvigor\bin
D:\dev\DevEco Studio\tools\node

PowerShell 里临时生效：

$env:HOS_SDK_HOME = 'D:\dev\DevEco Studio\sdk'
$env:DEVECO_SDK_HOME = 'D:\dev\DevEco Studio\sdk'
$env:PATH = 'D:\flutter_flutter\bin;D:\dev\DevEco Studio\tools\ohpm\bin;D:\dev\DevEco Studio\tools\hvigor\bin;D:\dev\DevEco Studio\tools\node;' + $env:PATH

六、验证环境

flutter doctor -v

重点看这一行是绿色对勾：

[√] HarmonyOS toolchain - develop for HarmonyOS devices

还能看到设备：

[√] Connected device
• 3AQ0224B14026838 (mobile) • ohos-arm64 • OpenHarmony-6.1.1.120 (API 24)

Android、Windows、Visual Studio 那些是叉属于正常，不影响鸿蒙开发。

七、创建鸿蒙原生工程

  1. 打开 DevEco Studio，新建工程。
  2. 模板选 Empty Ability。
  3. 工程名填 FlutterMyApplication。
  4. 创建后，根目录会有 entry 模块，这就是原生 App 入口。

工程根的 build-profile.json5 里，targetSdkVersion 用 API 22：

{
  "app": {
    "products": [
      {
        "name": "default",
        "targetSdkVersion": "6.0.2(22)",
        "compatibleSdkVersion": "5.0.5(17)"
      }
    ]
  }
}

八、创建 Flutter Module

在原生工程根目录执行：

flutter create --template module flutter_module

生成 flutter_module 目录，里面的 lib/main.dart 就是 Flutter 页面。

它的 pubspec.yaml 里要有鸿蒙 bundle 名：

flutter:
  module:
    ohosBundleName: com.example.flutter_module

九、把 Flutter 编译成 HAR

cd flutter_module
flutter build har --debug

成功后生成三个文件：

flutter_module/build/ohos/har/debug/flutter_embedding_debug.har
flutter_module/build/ohos/har/debug/arm64_v8a_debug.har
flutter_module/build/ohos/har/debug/flutter_module.har

十、让原生工程认识 Flutter 模块

10.1 根目录 oh-package.json5

加 overrides，指到刚才生成的 HAR：

{
  "overrides": {
    "@ohos/flutter_ohos": "file:./flutter_module/build/ohos/har/debug/flutter_embedding_debug.har",
    "flutter_native_arm64_v8a": "file:./flutter_module/build/ohos/har/debug/arm64_v8a_debug.har",
    "@ohos/flutter_module": "file:./flutter_module/build/ohos/har/debug/flutter_module.har"
  }
}

10.2 entry 模块 oh-package.json5

在 dependencies 加三行：

{
  "dependencies": {
    "@ohos/flutter_ohos": "",
    "flutter_native_arm64_v8a": "",
    "@ohos/flutter_module": ""
  }
}

十一、改造原生入口，让 Flutter 能启动

11.1 EntryAbility 生命周期

import { UIAbility } from '@kit.AbilityKit';
import { ExclusiveAppComponent, FlutterManager } from '@ohos/flutter_ohos';

export default class EntryAbility extends UIAbility
  implements ExclusiveAppComponent<UIAbility> {

  detachFromFlutterEngine(): void {}

  getAppComponent(): UIAbility {
    return this;
  }

  onCreate(): void {
    FlutterManager.getInstance().pushUIAbility(this);
  }

  onDestroy(): void {
    FlutterManager.getInstance().popUIAbility(this);
  }

  onWindowStageCreate(windowStage): void {
    FlutterManager.getInstance().pushWindowStage(this, windowStage);
    windowStage.loadContent('pages/Index');
  }

  onWindowStageDestroy(): void {
    FlutterManager.getInstance().popWindowStage(this);
  }
}

11.2 新建 FlutterEntry

import {
  FlutterEngine,
  FlutterEntry,
} from '@ohos/flutter_ohos';
import { GeneratedPluginRegistrant } from '@ohos/flutter_module';

export default class MyFlutterEntry extends FlutterEntry {
  configureFlutterEngine(flutterEngine: FlutterEngine): void {
    super.configureFlutterEngine(flutterEngine);
    GeneratedPluginRegistrant.registerWith(flutterEngine);
  }
}

11.3 原生页面承载 Flutter

import { FlutterPage, FlutterView } from '@ohos/flutter_ohos';
import MyFlutterEntry from '../flutter/MyFlutterEntry';

@Entry
@Component
struct Index {
  private flutterEntry: MyFlutterEntry | undefined = undefined;
  private flutterView: FlutterView | undefined = undefined;

  aboutToAppear(): void {
    this.flutterEntry = new MyFlutterEntry(getContext(this));
    this.flutterEntry.aboutToAppear();
    this.flutterView = this.flutterEntry.getFlutterView();
  }

  aboutToDisappear(): void {
    this.flutterEntry?.aboutToDisappear();
  }

  build() {
    Column() {
      FlutterPage({ viewId: this.flutterView?.getId() ?? '' })
        .width('100%')
        .layoutWeight(1)
    }
    .width('100%')
    .height('100%')
  }
}

到这里，原生页面里就嵌进了一个完整的 Flutter 页面。

十二、安装依赖并打包

回到原生工程根目录：

ohpm install

再构建：

hvigorw assembleHap --mode module -p product=default -p module=entry@default -p buildMode=debug --no-daemon

看到 BUILD SUCCESSFUL 就成功了。

生成的安装包：

entry/build/default/outputs/default/entry-default-signed.hap

十三、装到真机或模拟器

  1. 手机打开开发者模式和 USB 调试。
  2. 连接电脑，DevEco Studio 里能看到设备。
  3. 点运行，或用 hdc 安装 HAP。

十四、以后改了 Flutter 代码怎么办

每次改完 flutter_module/lib/main.dart，重新走一遍：

cd flutter_module
flutter build har --debug
cd ..
ohpm install
hvigorw assembleHap --mode module -p product=default -p module=entry@default -p buildMode=debug --no-daemon

简单记：改 Dart → 重新编 HAR → 重新装依赖 → 重新打 HAP。

十五、常见问题

提示找不到 hvigorw

把 D:\dev\DevEco Studio\tools\hvigor\bin 加到 Path。

提示找不到 ohpm

把 D:\dev\DevEco Studio\tools\ohpm\bin 加到 Path。

flutter doctor 里 HarmonyOS toolchain 是叉

检查 HOS_SDK_HOME 和 DEVECO_SDK_HOME 是否都指向 DevEco Studio 的 sdk 目录。

hvigor 报 JDK 版本错误

确认系统默认 java -version 不是 Java 8。鸿蒙需要 JDK 21（DevEco 6.0 内置）或 JDK 17（旧版 DevEco）。装好 JDK 21 后设置 JAVA_HOME。

改了 Dart 代码但页面没变化

多半是忘了重新 flutter build har。

Flutter 版本不是 ohos 版

去装 OpenHarmony 社区的 Flutter，不要用官网普通 Flutter。

克隆 Flutter 时下载 zip 后编译报错

必须用 git clone，zip 会丢失子模块。

项目地址：
https://gitee.com/wking123321/arkts-flutter

posted @ 2026-09-09 15:18  带头大哥d小弟  阅读(4)  评论(0)    收藏  举报