Flutter for HarmonyOS 开发指南（一）：环境搭建与项目创建

前言

在开始之前，我们需要明白：标准的 Flutter SDK（Google 官方版）目前并不直接支持 ohos 平台。
我们需要使用由华为和社区定制的Flutter 鸿蒙专用版 SDK，它在引擎层（Engine）增加了对鸿蒙系统渲染（ArkUI/XComponent）和插件能力的适配。

准备工作：硬件与软件要求

1. 操作系统：macOS (推荐, 支持 iOS/鸿蒙) 或 Windows 10/11。

2. DevEco Studio：建议安装最新的5.0 Release或更高版本（匹配 HarmonyOS NEXT）。

3. Node.js & ohpm：鸿蒙包管理器，随 DevEco Studio 安装。

4. Java SDK：建议 JDK 17。

鸿蒙版 Flutter 环境 3.35.7 版本搭建指南（Mac 版）

仓库地址：https://atomgit.com/openharmony-tpc/flutter_flutter/tree/oh-3.35.7-dev

一：下载安装最新的鸿蒙开发套件

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

二：下载鸿蒙版 Flutter（3.35.7 版本）

1.git克隆项目

项目地址：https://atomgit.com/openharmony-tpc/flutter_flutter/tree/oh-3.35.7-dev

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

2.验证下载

2.1执行命令

cd flutter_flutter git checkout -b oh-3.35.7-dev origin/oh-3.35.7-dev ./bin/flutter --version

2.2成功结果

三：环境变量配置

1. 配置文件选择

# 编辑zsh配置文件（推荐） open ~/.zshrc # 或者使用命令行编辑 nano ~/.zshrc

2. 环境变量配置

在配置文件中添加以下环境变量：

# DevEco Studio配置 export TOOL_HOME=/Applications/DevEco-Studio.app/Contents export DEVECO_SDK_HOME=$TOOL_HOME/sdk # 工具路径配置 export PATH=$TOOL_HOME/tools/ohpm/bin:$PATH export PATH=$TOOL_HOME/tools/hvigor/bin:$PATH export PATH=$TOOL_HOME/tools/node/bin:$PATH # Flutter路径配置（请根据实际路径修改） export PATH=/Users/dududu/Desktop/harmony/flutter/flutter_flutter/bin:$PATH # Flutter镜像配置（加速下载） export PUB_HOSTED_URL=https://pub.flutter-io.cn export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn # Flutter Git配置（解决警告） export FLUTTER_GIT_URL=git@gitcode.com:openharmony-tpc/flutter_flutter.git

3. 刷新配置

配置完成后，刷新环境变量

source ~/.zshrc

四：环境监测

1.执行检测

flutter doctor -v

2.检测结果（下图示成功）

3.结果分析

正常配置的组件：

HarmonyOS toolchain 鸿蒙开发工具链正常

Android toolchain 安卓开发工具链正常

Xcode IOS开发工具链正常

Chrome web开发环境正常

Connected device 设备连接正常

提示的问题：

Flutter (Channel [user-branch] - 这是正常的，因为使用的是鸿蒙定制版本

异常组件：

Network resource 网络资源异常 - 推荐的国内镜像，检查代理软件设置

五：创建与运行第一个鸿蒙 Flutter 项目

1. 创建项目

指定平台包含 ohos：

flutter create --platforms ohos,android,ios --org com.yourcompany my_harmony_app

编译：（生成的HAP文件位于ohos/entry/build目录下）

2. 编译 HAP 包

进入项目根目录，执行构建命令（生成的 .hap 文件位于 ohos/entry/build 目录下）：

flutter build hap --release

3. 运行至设备

确保你的鸿蒙设备（或模拟器）已连接并开启调试模式：

flutter run -d 127.0.0.1:5555

效果预览

六、 常见问题排查 (FAQ)

Q1：编译时报错 “Could not find Java” 或 Java 版本冲突？

现象：虽然安装了 Android Studio，但终端无法正确识别 Java。
解决：建议手动安装JDK 17，并在 .zshrc 中明确配置 JAVA_HOME。

编译报错：

检测识别不到j本地ava，前面由于单独安装了android Studio,自带了java环境。还是需要单独安装一个java jdk。

Q2：flutter doctor 识别不到鸿蒙设备？

解决：需要先完成3.2环境变量配置，然后再进行检测。

结语
搭建鸿蒙版 Flutter 环境虽然比标准版稍显复杂，但随着华为对 HarmonyOS NEXT 生态的持续投入，这套工具链正在变得越来越成熟。如果你在搭建过程中遇到其他问题，欢迎在评论区交流！

欢迎加入开源鸿蒙跨平台社区
https://openharmonycrossplatform.csdn.net