# Arkts-Flutter

**Repository Path**: wking123321/arkts-flutter

## Basic Information

- **Project Name**: Arkts-Flutter
- **Description**: 鸿蒙+flutter混合开发用例
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 鸿蒙 + 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） | 21.0.8 | 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 下载页：

```text
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 会自动带上下面这些东西，**不用再单独装**：

```text
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。**

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

```text
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 21**（和 DevEco Studio 6.0 内置版本一致）。

### 3.1 下载地址

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

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

也可以去 Oracle 官方下 JDK 21：

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

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

```powershell
winget install EclipseAdoptium.Temurin.21.JDK
```

### 3.3 配置环境变量

装好后设两个环境变量：

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

并把下面这行加到 `Path`：

```text
%JAVA_HOME%\bin
```

验证：

```powershell
java -version
```

应该输出类似：

```text
openjdk version "21.0.x"
```

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

---

## 四、安装 Flutter-OH SDK

### 4.1 下载方式

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

仓库地址：

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

### 4.2 安装命令

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

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

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

```powershell
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
```

本机验证过的版本是：

```text
Flutter 3.27.5-ohos-1.0.4
Dart 3.6.2
```

### 4.3 验证

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

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

---

## 五、配置环境变量

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

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

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

```text
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 里临时生效：

```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
```

---

## 六、验证环境

```powershell
flutter doctor -v
```

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

```text
[√] HarmonyOS toolchain - develop for HarmonyOS devices
```

还能看到设备：

```text
[√] 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：

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

---

## 八、创建 Flutter Module

在原生工程根目录执行：

```powershell
flutter create --template module flutter_module
```

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

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

```yaml
flutter:
  module:
    ohosBundleName: com.example.flutter_module
```

---

## 九、把 Flutter 编译成 HAR

```powershell
cd flutter_module
flutter build har --debug
```

成功后生成三个文件：

```text
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：

```json5
{
  "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` 加三行：

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

---

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

### 11.1 EntryAbility 生命周期

```typescript
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

```typescript
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

```typescript
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 页面。

---

## 十二、安装依赖并打包

回到原生工程根目录：

```powershell
ohpm install
```

再构建：

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

看到 `BUILD SUCCESSFUL` 就成功了。

生成的安装包：

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

---

## 十三、装到真机或模拟器

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

---

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

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

```powershell
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 会丢失子模块。