摘要：随着 OpenHarmony 生态的不断发展，Flutter 对鸿蒙的支持也日益完善。本文记录了在 Windows 10 环境下，从零开始搭建 Flutter for OpenHarmony 开发环境的全过程。内容涵盖环境准备、源码获取、环境变量配置（含踩坑点）、DevEco Studio 设置以及首个应用的运行。

前言

Flutter 适配 OpenHarmony 的相关技术虽然官方仓库有相关文档，但在实际的 Windows 环境搭建过程中，仍然遇到了一些细节坑点，特别是环境变量配置和工具链版本对齐的问题。

为了方便后续查阅，也为了给同样感兴趣的同学提供参考，特整理了这份详细的搭建指南。本文将尽量还原真实的操作步骤，并重点标注容易出错的地方。

---

一、 环境准备

在开始之前，我们需要确保电脑满足以下基础要求，并安装好必要的依赖软件。

1. 硬件与系统要求

• 操作系统：Windows 10 或 Windows 11（64位）。本文演示环境为 Windows 10。
• 内存：建议 16GB 及以上。
• 硬盘：预留至少 20GB 的可用空间。

2. 核心软件依赖

在搭建 Flutter 环境前，必须先安装以下工具：

• Git：用于克隆源码和版本管理。
• Java JDK 17： DevEco Studio 和许多构建工具依赖 Java 17。请勿使用 Java 8 或其他版本，以免出现兼容性问题。
  • 验证命令：java -version
    
• Visual Studio Code (可选且推荐)：作为轻量级代码编辑器，配合 Flutter 插件开发体验极佳。

---

二、 获取 OpenHarmony 版 Flutter SDK

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

1. 选定安装目录

建议选择一个路径简短且无中文、无空格的目录，例如 D:\Work\flutter_ohos。路径过长或包含特殊字符可能会导致编译报错。

2. 克隆代码仓库

打开 Git Bash 或 CMD，进入你选定的目录，执行以下命令：

git clone -b master https://atomgit.com/openharmony-sig/flutter_flutter.git

注意：这里推荐使用 CSDN 旗下的 AtomGit 镜像源，国内访问速度极快且稳定。

下载完成后，你会看到一个 flutter_flutter 文件夹。

---

三、 关键步骤：环境变量深度配置

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

1. 打开环境变量设置

右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”。
或者直接于电脑搜索栏搜索

2. 配置国内镜像源 (加速下载)

在“用户变量”或“系统变量”中新建以下变量，解决依赖包下载慢的问题：

变量名	变量值	说明
PUB_HOSTED_URL	https://pub.flutter-io.cn	Dart 包镜像
FLUTTER_STORAGE_BASE_URL	https://storage.flutter-io.cn	Flutter 依赖镜像

3. 配置 Flutter 路径

在 Path 变量中，添加刚才克隆的 Flutter SDK 的 bin 目录路径。

• 例如：D:\Work\21days\flutter_ohos\flutter_flutter\bin
  

4. 配置 HarmonyOS SDK 相关变量

为了让 Flutter 找到鸿蒙的 SDK 和构建工具，我们需要配合 DevEco Studio 的安装路径进行配置（假设 DevEco Studio 安装在默认路径）。

建议新建一个变量 TOOL_HOME 指向 DevEco Studio 根目录，方便管理：

• TOOL_HOME: D:\DevEco Studio (请根据个人实际安装位置修改)

接着配置 DEVECO_SDK_HOME：

• DEVECO_SDK_HOME: %TOOL_HOME%\sdk

最后，在 Path 中追加以下关键工具路径：

1. %TOOL_HOME%\tools\ohpm\bin (包管理器)
2. %TOOL_HOME%\tools\hvigor\bin (构建工具)
3. %TOOL_HOME%\tools\node (自带 Node环境)

避坑指南：系统可能已经安装了其他版本的 Node.js。为了避免版本冲突导致编译失败，强烈建议将 DevEco Studio 自带的 node 路径放在 Path 变量列表的较前位置，确保优先使用 IDE 自带的稳定环境。

---

四、 安装 DevEco Studio 与 SDK

DevEco Studio 是鸿蒙开发的官方 IDE，我们需要它来提供 SDK 和模拟器。

1. 下载安装：前往 HarmonyOS 开发者官网下载最新版 DevEco Studio。
2. SDK 下载：首次启动时，按照向导下载 OpenHarmony SDK (API 11 或 12) 以及 HarmonyOS SDK。确保勾选 Toolchains。
3. 确认路径：确保下载位置与我们在第三步中配置的 DEVECO_SDK_HOME 对应的物理路径一致。

---

五、 环境验证与问题排查

配置完成后，我们需要验证环境是否健康。

打开 CMD 或 PowerShell，输入：

flutter doctor -v

常见问题排查

1. Android toolchain - develop for Android devices

   • 报错：cmdline-tools component is missing
   • 解决：打开 Android Studio -> SDK Manager -> SDK Tools，勾选 Android SDK Command-line Tools (latest) 并安装。
   • 报错：Android license status unknown
   • 解决：运行 flutter doctor --android-licenses，一路输入 y 同意协议。

2. HarmonyOS 识别问题

   • 如果 flutter doctor 没有显示 OpenHarmony/HarmonyOS 相关条目，请检查 flutter 命令是否指向了我们下载的 flutter_flutter 目录，而不是系统里可能存在的旧版标准 Flutter。

成功状态：
当看到所有勾选均为绿色（或至少 Flutter 和 OpenHarmony/HarmonyOS 为绿色）时，恭喜你，环境搭建完成！

---

六、 实战：创建并运行第一个鸿蒙 Flutter 应用

终于到了激动的 Hello World 环节。

1. 创建项目

在终端中执行以下命令，创建一个支持 OpenHarmony 平台的项目：

flutter create --platforms ohos my_first_ohos_app
cd my_first_ohos_app

2. 启动模拟器

打开 DevEco Studio -> Tools -> Device Manager，启动一个 API 11+ 的本地模拟器（Local Emulator）。

3. 编译与运行

在项目根目录下，执行：

# 方式一：直接运行（会自动寻找设备）
flutter run

# 方式二：先构建 HAP 包
flutter build hap --debug

如果是第一次编译，系统会下载大量的 ohpm 依赖，速度可能较慢，请耐心等待。

编译成功后，应用将自动安装到模拟器上。你将看到熟悉的 Flutter 计数器应用运行在鸿蒙系统上！

---

七、 总结

至此，我们已经成功在 Windows 10 上搭建起了 Flutter for OpenHarmony 的开发环境，并跑通了 Hello World。虽然前期配置步骤稍显繁琐，特别是涉及 Git、JDK、SDK 以及各种环境变量的配置，但一旦打通，后续的开发体验还是相当不错的。

核心经验总结：

1. 路径问题：所有开发工具路径尽量不含空格和中文。
2. 版本对齐：Node.js 和 Java 版本要严格遵循官方建议（使用 DevEco 自带 Node 和 Java 17）。
3. 镜像加速：国内开发务必配置 Pub 镜像

希望这篇文章能对正在尝试鸿蒙跨平台开发的同学有所帮助，也欢迎大家在评论区交流踩坑经验。
欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net

---

参考资源与社区

• OpenHarmony SIG Flutter 仓库 (AtomGit):
  • https://atomgit.com/openharmony-sig/flutter_flutter
• OpenHarmony 开发者社区:
  • https://www.openharmony.cn/

本文代码及操作均在 Windows 10 + DevEco Studio Next 环境下实测通过。