Flutter for OpenHarmony 开发环境搭建指南

本文基于多篇实战经验总结，详细介绍如何在 Windows/macOS 环境下搭建 Flutter for OpenHarmony 开发环境。

一、 前言

随着鸿蒙生态的发展，Flutter 对 OpenHarmony 的支持也日益成熟。华为和社区定制了 Flutter 鸿蒙专用版 SDK，在引擎层增加了对鸿蒙系统渲染（ArkUI/XComponent）和插件能力的适配。

二、 环境准备

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

1. 操作系统与硬件

• 操作系统：Windows 10/11 (64位) 或 macOS。
• 内存：建议 16GB 及以上。
• 硬盘：预留至少 20GB 可用空间。

2. 核心软件依赖

• Git：用于代码版本管理。
• Java JDK 17：DevEco Studio 和构建工具强依赖 JDK 17，请勿使用 Java 8。
  • 下载地址：Oracle JDK 17
  • 配置：确保设置 JAVA_HOME 环境变量。
• Visual Studio Code (可选)：推荐安装 Flutter 插件配合使用。

3. DevEco Studio

DevEco Studio 是鸿蒙应用开发的官方 IDE。

• 下载：建议下载最新版本（5.0 Release 或更高）。
• 安装：安装过程中会提示下载 OpenHarmony SDK (API 11/12) 和 Node.js/ohpm 工具，请记住安装路径。

---

三、 获取 Flutter for OpenHarmony 源码

标准的 Google Flutter SDK 尚未原生完全支持 OpenHarmony，我们需要使用社区维护的版本。

1. 选择安装目录

建议选择路径简短、无中文、无空格的目录（例如 C:\Tools）。

2. 克隆代码

打开终端（CMD/PowerShell/Terminal），执行以下命令：

# 从 AtomGit 克隆（国内速度快）
git clone https://atomgit.com/openharmony-tpc/flutter_flutter.git

# 进入目录
cd flutter_flutter

# 切换到开发分支 (推荐使用 oh-3.32.4-dev 或最新稳定分支)
git checkout -b oh-3.32.4-dev origin/oh-3.32.4-dev

四、 配置环境变量 (关键步骤)

这是最容易出错的环节，需要配置 Flutter 自身环境以及它依赖的鸿蒙工具链。

1. 配置鸿蒙工具链变量

假设 DevEco Studio 安装在 D:\Huawei\DevEco Studio (请根据实际情况修改)：

• Windows 配置示例：

变量名	变量值示例	说明
TOOL_HOME	D:\Huawei\DevEco Studio	DevEco Studio 安装根目录
DEVECO_SDK_HOME	%TOOL_HOME%\sdk	SDK 存储目录
HDC_HOME	%DEVECO_SDK_HOME%\default\openharmony\toolchains	HDC 工具路径

2. 配置 Flutter 镜像源

为了加速依赖包下载，建议配置国内镜像：

变量名	变量值	说明
PUB_HOSTED_URL	https://pub.flutter-io.cn	Dart 包镜像
FLUTTER_STORAGE_BASE_URL	https://storage.flutter-io.cn	Flutter 存储镜像
PUB_CACHE	C:\PUB (可选)	自定义缓存路径

3. 更新 Path 变量

将以下路径添加到系统的 Path 环境变量中：

1. Flutter Bin 目录：D:\flutter_ohos\flutter_flutter\bin (你克隆的源码路径)
2. 鸿蒙包管理器：%TOOL_HOME%\tools\ohpm\bin
3. 鸿蒙构建工具：%TOOL_HOME%\tools\hvigor\bin
4. Node.js (IDE自带)：%TOOL_HOME%\tools\node\bin

五、 环境验证

配置完成后，重启终端，运行以下命令进行自检：

flutter doctor -v

正常结果应包含：

• HarmonyOS toolchain：显示打钩 [✓]
• Android toolchain / Xcode：如果需要开发其他平台，也应配置好。

---

六、 创建与运行第一个鸿蒙 Flutter 项目

1. 创建项目

flutter create my_harmony_app
cd my_harmony_app

2. 编译 HAP 包

# 编译 debug 版本
flutter build hap --debug

生成的 .hap 文件通常位于 ohos/entry/build/default/outputs/default/entry-default-signed.hap。

3. 运行到设备

确保真机或模拟器已连接（使用 hdc list targets 检查），然后运行：

七、 常见问题排查 (FAQ)

Q1: flutter doctor 报错 “Ohpm is missing”？

• 解决：检查 Path 中是否正确添加了 ohpm\bin 的路径，并确保重启了终端。

Q2: 报错 “cmdline-tools component is missing”？

• 解决：打开 Android Studio -> SDK Manager -> SDK Tools，勾选安装 Android SDK Command-line Tools。

Q3: 报错 “Android license status unknown”？

• 解决：运行 flutter doctor --android-licenses 并一路输入 y 同意。

Q4: Windows 下运行脚本报错或换行符问题？

• 解决：部分脚本可能需要 Unix 换行符 (LF)。如果在 Windows 下遇到脚本执行错误，尝试检查文件编码或使用 Git Bash 运行。

Q5: 编译时出现堆栈溢出 (Stack Overflow)？

• 解决：这可能是工具链版本或 Gradle/Hvigor 配置问题，建议清理缓存 (flutter clean) 重试，或检查 JDK 版本是否严格为 17。

---

欢迎加入开源鸿蒙跨平台社区： https://openharmonycrossplatform.csdn.net
祝你的 Flutter for OpenHarmony 开发之旅顺利！