Flutter for HarmonyOS 开发学习 DAY 1：搭建开发环境

随着鸿蒙系统（HarmonyOS）的不断发展，越来越多的开发者开始关注如何在鸿蒙平台上进行应用开发。Flutter 作为一种跨平台开发框架，为开发者提供了一种高效、便捷的方式来构建高性能的应用。本文将详细介绍如何在鸿蒙系统上搭建 Flutter 开发环境，并创建第一个鸿蒙 Flutter 项目。Flutter 是由 Google 开发的开源 UI 框架，用于构建跨平台的移动、Web 和桌面应用。鸿

2301_81312828

305人浏览 · 2026-01-23 12:18:34

2301_81312828 · 2026-01-23 12:18:34 发布

前言

随着鸿蒙系统（HarmonyOS）的不断发展，越来越多的开发者开始关注如何在鸿蒙平台上进行应用开发。Flutter 作为一种跨平台开发框架，为开发者提供了一种高效、便捷的方式来构建高性能的应用。本文将详细介绍如何在鸿蒙系统上搭建 Flutter 开发环境，并创建第一个鸿蒙 Flutter 项目。

一、Flutter for HarmonyOS 简介

Flutter 是由 Google 开发的开源 UI 框架，用于构建跨平台的移动、Web 和桌面应用。鸿蒙系统（HarmonyOS）是华为推出的面向全场景的分布式操作系统，具有低延迟、高并发和多设备协同的特点。为了在鸿蒙平台上使用 Flutter，华为和社区定制了 Flutter 鸿蒙专用版 SDK，它在引擎层增加了对鸿蒙系统渲染（ArkUI/XComponent）和插件能力的适配。

二、开发环境准备

在开始之前，确保你的开发环境满足以下要求：

1. 操作系统

推荐：macOS（支持 iOS/鸿蒙）
可选：Windows 10/11

2. DevEco Studio

DevEco Studio 是华为官方提供的鸿蒙应用开发工具，建议安装最新版本（5.0 Release 或更高版本）以匹配 HarmonyOS NEXT。

下载地址：https://developer.huawei.com/consumer/cn/deveco-studio/

3. Node.js 与 ohpm

ohpm 是鸿蒙包管理器，通常随 DevEco Studio 安装。如果未安装，可以通过以下链接下载：

Node.js 官网：https://nodejs.org/
ohpm 安装指南：https://atomgit.com/openharmony-tpc/ohpm/

4. Java SDK

建议安装 JDK 17，可以通过以下链接下载：

JDK 17 下载地址：https://www.oracle.com/java/technologies/javase-jdk17-downloads.html

三、下载与安装

1. 下载鸿蒙版 Flutter

鸿蒙版 Flutter 的代码托管在 AtomGit 上，可以通过以下命令克隆项目：

git clone https://atomgit.com/openharmony-tpc/flutter_flutte

进入项目目录并切换到鸿蒙专用分支：

cd flutter_flutter
//根据你的需求选择合适的分支。本文以 oh-3.32.4-dev 分支为例：
git checkout -b oh-3.32.4-dev origin/oh-3.32.4-dev

验证版本：

./bin/flutter --version

2. 配置环境变量

添加以下环境变量：

# DevEco Studio 配置
export TOOL_HOME=D:/Huawei/DevEco Studio //DevEco Studio 的实际安装路径
export DEVECO_SDK_HOME=$TOOL_HOME/sdk //指向 SDK 的存储目录，通常位于 DevEco Studio 安装目录下的 sdk 文件夹。
export HDC_HOME=%DEVECO_SDK_HOME%\default\openharmony\toolchains //指向 HarmonyOS 设备连接工具（HDC）的路径，用于连接真机或模拟器。

# 工具路径配置
export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH
export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH
export PATH=$TOOL_HOME/tools/node/bin:$PATH

配置 PATH 变量：

3.配置 Flutter 环境变量

为了让系统能够识别 Flutter 命令，我们需要配置 Flutter 相关的环境变量。

添加如下环境变量：

export PUB_CACHE=C:\PUB（或你自定义的路径）
export PUB_HOSTED_URL=https://pub.flutter-io.cn //PUB_HOSTED_URL 是 Dart 包的镜像源地址，使用国内镜像可以加快下载速度。
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn //FLUTTER_STORAGE_BASE_URL 是 Flutter 存储的镜像源地址。

export PATH=D:\Tools\flutter_flutter\bin:$PATH //替换为你实际克隆 Flutter 的路径

四、环境检测

运行以下命令检测开发环境是否配置正确：

flutter doctor -v

检测结果会显示各个组件的状态，正常配置的组件包括：

HarmonyOS toolchain（鸿蒙开发工具链）
Android toolchain（安卓开发工具链）
Xcode（iOS 开发工具链）
Chrome（Web 开发环境）
Connected device（设备连接）

五、创建第一个鸿蒙 Flutter 项目

1. 创建项目

运行以下命令创建一个新的 Flutter 项目，支持多平台包括鸿蒙（ohos）：

flutter create <自定义项目名称> //项目名称使用小写字母和下划线，例如：my_first_app、harmony_app

2. 编译 HAP 包

进入项目根目录，运行以下命令编译 HAP 文件（鸿蒙应用包）：

cd my_harmony_app
flutter build hap --debug

生成的 .hap 文件位于 ohos/entry/build 目录下。

3. 运行到设备

确保你的鸿蒙设备（或模拟器）已连接并开启调试模式，运行以下命令将应用安装到设备上：

六、常见问题排查

Q1：缺少 `cmdline-tools` 组件

解决：安装 Android Studio，或者直接从 Android 开发者网站下载 cmdline-tools。设置 ANDROID_HOME 环境变量：确保你的系统中设置了 ANDROID_HOME 环境变量，指向你的 Android SDK 目录。

Q2：Android license status unknown

这表示 Flutter 无法确定 Android SDK 许可证的状态。这可能是因为你没有接受许可证协议。

解决：运行 flutter doctor --android-licenses 命令来接受 Android SDK 的许可证。

Q3：spawn java ENOENT

解决：正确设置JAVA_HOME，如果JDK安装在 C:\Program Files\Java\jdk-17，那么 JAVA_HOME 就应该设置为这个路径。如未安装，可以参考https://blog.csdn.net/zl392321162/article/details/156153538

欢迎加入开源鸿蒙跨平台社区，获取更多支持和资源： https://openharmonycrossplatform.csdn.net