Windows系统搭建Flutter鸿蒙环境完整指南

TrisighT
159 阅读7分钟

Windows系统搭建Flutter鸿蒙环境完整指南

前言

随着鸿蒙操作系统的快速发展，越来越多的开发者希望将Flutter应用集成到鸿蒙项目中。本文将为开发者提供一份详细的指南，帮助您从零开始搭建Flutter鸿蒙环境，并成功创建Flutter模块在鸿蒙项目中运行。

环境准备与检查

前置条件确认

在开始之前，请确保您的开发环境已具备以下条件：

  • ✅ Windows 10/11 操作系统
  • ✅ 鸿蒙开发环境（DevEco Studio）已安装并配置完成
  • ✅ Git 环境已安装
  • ✅ 鸿蒙模拟器或真机调试环境

系统要求检查

# 检查Windows版本
winver
​
# 检查Git版本
git --version
​
# 检查DevEco Studio是否正常
# 打开DevEco Studio，确保能正常创建鸿蒙项目

image.png

Flutter SDK安装与配置

1. 下载Flutter SDK

通过代码工具包下载当前仓库代码git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git， 并切换到dev分支，本人用的3.22版本，区别不大

# 创建Flutter安装目录
mkdir C:\flutter
cd C:\flutter
​
# 下载Flutter SDK鸿蒙适配版
# 下载地址：https://gitcode.com/openharmony-tpc/flutter_flutter.git

2. 解压并配置环境变量

# 解压Flutter SDK到 C:\flutter 目录
# 解压后目录结构应为：C:\flutter\flutter\bin\flutter.exe

配置系统环境变量：

  1. 右键"此电脑" → "属性" → "高级系统设置" → "环境变量"
  2. 在"系统变量"中找到"Path"，点击"编辑"
  3. 添加新路径：C:\flutter\【flutter sdk目录】\bin
  4. 点击"确定"保存

image.png

3. Flutter安装

# 重新打开命令行窗口
flutter --version
​
# 运行Flutter诊断
flutter doctor

预期输出示例：

Flutter 3.22.1-ohos-1.0.4 • channel [user-branch] • https://gitcode.com/openharmony-tpc/flutter_flutter.git
Framework • revision c4a66f77d0 (4 months ago) • 2025-07-01 10:13:30 +0800
Engine • revision f6344b75dc
Tools • Dart 3.4.0 • DevTools 2.34.1

4. 配置Flutter国内镜像

还需要配置一下国内的镜像源以防万一

PUB_HOSTED_URL
https://pub.flutter-io.cn
​
FLUTTER_STORAGE_BASE_URL
https://storage.flutter-io.cn

image.png

5. 配置JDK

官网地址在这，现在好像需要注册账号了，邮箱注册就行 !

image.png 安装时记得记下安装路径，安装完成了配置环境变量 !

image.png 以防万一path里面也加上 !

image.png

6. 其他环境变量

有些情况下打包的时候会报错，提示缺少DEVECO_SDK_HOME的环境，所以得加上 这个就是DevEco编辑器的sdk位置

DEVECO_SDK_HOME
C:\Program Files\Huawei\DevEco Studio\sdk

此外还有下载flutter的git地址，因为鸿蒙版flutter迁移到华为自己的GitCode里面去了，原先的Gitee好像没更新了 本人这里是从GitCode克隆的，所以填的这个链接，看你们从哪克隆就填什么地址链接

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

除了这些还有hdc跟flutter以防万一也在外面配置下，最好是配置，不然可能会有很多奇奇怪怪的坑

HDC_HOME
C:\Program Files\Huawei\DevEco Studio\sdk\default\hms\toolchains
​
HOST_FLUTTER
C:\Users\ThinkPad\harmony_flutter\flutter_flutter\bin

7. 小结

image.png

Flutter鸿蒙支持配置

1. 检查flutter环境配置

# 检查鸿蒙平台支持
flutter doctor -v

确保输出中包含鸿蒙相关信息：

image.png

创建Flutter鸿蒙模块

1. 创建鸿蒙项目

首先创建一个标准的鸿蒙项目作为宿主项目：

# 在DevEco Studio中创建新项目
# 选择 Application → Empty Ability
# 项目名称：HarmonyFlutterDemo
# Bundle Name：com.example.harmonyflutterdemo

2. 创建Flutter模块

在鸿蒙项目目录下创建Flutter模块：

# 进入鸿蒙项目根目录
cd HarmonyFlutterDemo
​
# 创建Flutter模块
flutter create -t module my_flutter_module
​
# 进入Flutter模块目录
cd my_flutter_module

3. 构建Flutter HAR包

# 在Flutter模块目录下执行构建
flutter build har --release
​
# 构建完成后，HAR文件位置：
# build/har/release/my_flutter_module.har

image.png

集成Flutter模块到鸿蒙项目

方式一：开发阶段 - 源码引用（推荐用于开发调试）

1. 修改 oh-package.json5

在鸿蒙项目根目录的 oh-package.json5 文件中添加依赖：

{
  "name": "harmonyflutterdemo",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {
    "my_flutter_module": "file:./my_flutter_module"
  }
}
2. 修改 build-profile.json5

在项目的 build-profile.json5 文件中配置模块：

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.0(12)",
        "runtimeOS": "HarmonyOS"
      }
    ],
    "buildModeSet": [
      {
        "name": "debug"
      },
      {
        "name": "release"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    },
    {
      "name": "my_flutter_module",
      "srcPath": "./my_flutter_module",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    }
  ]
}

方式二：发版阶段 - HAR引用（推荐用于生产环境）

1. 复制HAR文件
# 创建libs目录
mkdir entry\libs
​
# 复制HAR文件到libs目录
copy my_flutter_module\build\har\release\my_flutter_module.har entry\libs\
2. 配置HAR依赖

在 entry/oh-package.json5 中添加：

{
  "name": "entry",
  "version": "1.0.0",
  "description": "Please describe the basic information.",
  "main": "",
  "author": "",
  "license": "",
  "dependencies": {},
  "overrides": {
    "my_flutter_module": "file:./libs/my_flutter_module.har"
  }
}

代码实现与配置

1. 创建Flutter Entry类

在 entry/src/main/ets/entryability/ 目录下创建 MyFlutterEntry.ets：

import { GeneratedPluginRegistrant } from 'my_flutter_module';
import { FlutterManager } from '@ohos/flutter_ohos';
​
export default class MyFlutterEntry extends FlutterEntry {
  configureFlutterEngine(flutterEngine: FlutterEngine): void {
    super.configureFlutterEngine(flutterEngine);
    GeneratedPluginRegistrant.registerWith(flutterEngine);
    this.delegate?.addPlugin(new BatteryPlugin());
  }
}

2. 修改EntryAbility

修改 entry/src/main/ets/entryability/EntryAbility.ets：

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { FlutterManager } from '@ohos/flutter_ohos';
import { ExclusiveAppComponent } from '@ohos/flutter_ohos';
​
export default class EntryAbility extends UIAbility implements ExclusiveAppComponent<UIAbility> {
  detachFromFlutterEngine(): void {
    // throw new Error('Method not implemented.');
  }
​
  getAppComponent(): UIAbility {
    return this;
  }
​
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    FlutterManager.getInstance().pushUIAbility(this);
  }
​
  onDestroy(): void | Promise<void> {
    FlutterManager.getInstance().popUIAbility(this);
  }
​
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.getMainWindowSync().setWindowLayoutFullScreen(true);
    FlutterManager.getInstance().pushWindowStage(this, windowStage);
    windowStage.loadContent('pages/Index');
  }
​
  onWindowStageDestroy() {
    FlutterManager.getInstance().popWindowStage(this);
  }
}

3. 创建Flutter页面

修改 entry/src/main/ets/pages/Index.ets：

import { FlutterView } from '@ohos/flutter_ohos';
import { MyFlutterEntry } from '../entryability/MyFlutterEntry';
​
@Entry
@Component
struct Index {
  private context = getContext(this) as common.UIAbilityContext
  private flutterEntry: FlutterEntry | null = null;
  private flutterView?: FlutterView
​
  aboutToAppear() {
    Log.d("Flutter", "Index aboutToAppear===");
    this.flutterEntry = new MyFlutterEntry(getContext(this))
    this.flutterEntry.aboutToAppear()
    this.flutterView = this.flutterEntry.getFlutterView()
  }
​
  aboutToDisappear() {
    Log.d("Flutter", "Index aboutToDisappear===");
    this.flutterEntry?.aboutToDisappear()
  }
​
  // Navigation的生命周期是onShown
  onPageShow() {
    Log.d("Flutter", "Index onPageShow===");
     FlutterManager.getInstance().setUseFullScreen(true)
    this.flutterEntry?.onPageShow()
  }
​
  // Navigation的生命周期是onHidden
  onPageHide() {
    Log.d("Flutter", "Index onPageHide===");
     FlutterManager.getInstance().setUseFullScreen(false)
    this.flutterEntry?.onPageHide()
  }
​
  build() {
    Stack() {
      FlutterPage({ viewId: this.flutterView?.getId() })
  }
​
  onBackPress(): boolean {
    this.context.eventHub.emit('EVENT_BACK_PRESS')
    return true
  }
}

运行与测试

1. 启动鸿蒙模拟器

# 在DevEco Studio中启动模拟器
# 工具栏 → Device Manager → 选择模拟器 → Start

2. 配置自动签名

在DevEco Studio中：

  1. File → Project Structure → Project → Signing Configs
  2. 勾选"Automatically generate signature"
  3. 点击"OK"

3. 运行项目

# 方式一：在DevEco Studio中点击运行按钮
​
# 方式二：使用命令行
cd HarmonyFlutterDemo
hvigor assembleHap --mode module -p module=entry@default -p product=default

4. 验证运行结果

成功运行后，您应该能看到：

  • 鸿蒙应用正常启动
  • Flutter页面在应用中正确渲染
  • Flutter组件响应正常

image.png

常见问题与解决方案

问题1：Flutter Doctor检查失败

症状： flutter doctor 显示鸿蒙工具链未找到

解决方案：

# 检查DevEco Studio安装路径
flutter config --harmony-sdk C:\Users[用户名]\AppData\Local\Huawei\Sdk
​
# 重新检查
flutter doctor -v

问题2：HAR构建失败

症状： flutter build har 命令执行失败

解决方案：

# 清理Flutter缓存
flutter clean
​
# 获取依赖
flutter pub get
​
# 重新构建
flutter build har --release --verbose

问题3：模块依赖无法解析

症状： 编译时提示找不到Flutter模块

解决方案：

  1. 检查 oh-package.json5 中的路径是否正确
  2. 确保Flutter模块已正确构建
  3. 重新同步项目：Build → Refresh Linked C++ Projects

问题4：运行时Flutter页面空白

症状： 应用启动正常，但Flutter页面显示空白

解决方案：

// 检查FlutterEntry是否正确初始化
// 确保在EntryAbility中正确注册了FlutterManager
FlutterManager.getInstance().pushUIAbility(this);
​
// 检查FlutterView的配置
FlutterView({
  entry: this.flutterEntry,
  initialRoute: '/' // 确保路由正确
})

问题5：签名配置问题

症状： 安装应用时提示签名错误

解决方案：

  1. 在DevEco Studio中重新配置自动签名
  2. 清理项目：Build → Clean Project
  3. 重新构建：Build → Rebuild Project

总结

通过本指南，您已经学会了：

  1. ✅ 在Windows系统上配置Flutter鸿蒙开发环境
  2. ✅ 创建Flutter模块并构建HAR包
  3. ✅ 将Flutter模块集成到鸿蒙项目中
  4. ✅ 实现Flutter页面在鸿蒙应用中的渲染
  5. ✅ 解决常见的开发和运行问题

Flutter与鸿蒙的集成为跨平台开发提供了新的可能性。随着技术的不断发展，这种集成方式将为开发者带来更多便利和机会。

参考资料

注意： 本文档基于当前版本的Flutter和鸿蒙SDK编写，随着版本更新，部分配置可能会有所变化。建议在实际开发中参考最新的官方文档。

avatar
文章
阅读
粉丝