Windows 11 OpenHarmony 版 Flutter 开发环境搭建完整指南

📝 适合人群 ：鸿蒙跨平台应用开发者

⏱️ 预计时间 ：1-2 小时（包含下载时间）

🎯 学习目标：成功搭建OpenHarmony版Flutter开发环境

📖 什么是OpenHarmony版Flutter？

Flutter是Google开发的跨平台UI框架，可以一套代码同时运行在 Android、iOS、Web 等平台。

OpenHarmony版Flutter 是Flutter针对OpenHarmony系统的适配版本，让你可以用Flutter开发HarmonyOS/OpenHarmony应用。

主要优势：

✅ 一套代码，多平台运行（Android、iOS、HarmonyOS）
✅ 高性能的 UI 渲染
✅ 丰富的组件库和插件生态
✅ 热重载，快速开发调试

🖥️ 测试环境

本文档基于以下环境进行测试：

💻 设备规格 ：
- 处理器：13th Gen Intel® Core™ i5-13500H (3.19 GHz)
- 内存：16.0 GB
- 系统类型：64 位操作系统, 基于 x64 的处理器
🪟 Windows规格 ：
- 版本：Windows 11 家庭版
- 版本号：25H2

📋 前置条件

在开始搭建环境之前，请确保已经完成以下软件的安装：

✅ Windows 11 安装 Visual Studio Code 完整指南 - 代码编辑器
✅ Windows 11 安装 Git 完整指南 - 版本控制工具
✅ Windows 11 安装 DevEco Studio 完整指南 - HarmonyOS/OpenHarmony开发IDE
✅ Windows 11 安装 Java 17 完整指南 - Java开发环境
Windows 11安装Android Studio完整指南

⚠️ 重要提示：请按照顺序完成前置软件的安装，特别是DevEco Studio和Java 17，它们是必需的。

📋 安装前准备

在开始之前，请确保：

✅ 已完成所有前置软件的安装
✅ 已注册并实名认证华为开发者账号（用于签名和模拟器）
✅ 网络连接正常（需要下载大量文件）
✅ 至少10 GB可用磁盘空间（包含 SDK、Flutter、模拟器等）
✅ 管理员权限（配置环境变量需要）

💡 小提示：整个搭建过程需要下载约 5-10 GB 的文件，建议在网络较好的环境下进行。

⚙️ 第一步：配置HarmonyOS SDK和环境变量

为了让 Flutter 能够找到HarmonyOS SDK和相关工具，我们需要配置一些环境变量。这些变量告诉系统在哪里找到 DevEco Studio 的安装路径和 SDK。

📌 步骤 1：打开系统属性

方法一：通过开始菜单（推荐）

🖱️ 右键点击 "开始" 按钮（或按 Win + X）
👆 在列表中点击 "系统" 打开系统面板
📋 下拉找到并点击 "高级系统设置"，打开系统属性面板

方法二：通过设置应用

按 Win + I 打开设置
搜索 "高级系统设置"
点击打开系统属性面板

💡 小提示：两种方法都可以，选择你觉得方便的即可。

📌 步骤 2：打开环境变量设置

🔧 在系统属性面板中，点击 "环境变量（N）..." 按钮
📋 打开环境变量设置界面

💡 小提示 ：环境变量分为用户变量 和系统变量 ，我们配置系统变量（对所有用户生效）。

📌 步骤 3：配置 TOOL_HOME 变量

TOOL_HOME 指向 DevEco Studio 的安装目录，这是其他环境变量的基础。

➕ 在 "系统变量" 区域，点击 "新建（W）..." 按钮
📝 填写变量信息：
- 变量名（N） ：TOOL_HOME
- 变量值（V）：DevEco Studio 的实际安装路径
💡 如何找到 DevEco Studio 安装路径？
- 默认路径通常是：C:\Users\你的用户名\AppData\Local\Huawei\DevEco Studio
- 或者在文件资源管理器中找到 DevEco Studio 的安装文件夹
- 复制完整路径，注意路径中不要有多余的空格
示例：C:\Tools\Huawei\DevEco Studio 或 C:\Users\张三\AppData\Local\Huawei\DevEco Studio
✅ 点击 "确定" 按钮保存

⚠️ 注意：路径中如果包含空格（如 DevEco Studio），确保完整复制，不要修改。

📌 步骤 4：配置 DEVECO_SDK_HOME 变量

DEVECO_SDK_HOME 指向 SDK 的存储目录，通常位于 DevEco Studio 安装目录下的 sdk 文件夹。

➕ 在 "系统变量" 区域，点击 "新建（W）..." 按钮
📝 填写变量信息：
- 变量名（N） ：DEVECO_SDK_HOME
- 变量值（V） ：%TOOL_HOME%\sdk
💡 小提示 ：%TOOL_HOME% 会引用之前设置的 TOOL_HOME 变量值，这样如果 DevEco Studio 安装路径改变，只需要修改 TOOL_HOME 即可。
✅ 点击 "确定" 按钮保存

📌 步骤 5：配置 PATH 变量（重要）

PATH 变量告诉系统在哪里查找可执行文件。我们需要添加 DevEco Studio 的工具路径。

🔍 在 "系统变量" 区域，找到 "Path" 变量名
✏️ 点击 "编辑（I）..." 按钮，打开编辑环境变量窗口
➕ 点击 "新建" 按钮，依次添加以下三个路径（分别添加，每次点击新建）：
- %TOOL_HOME%\tools\ohpm\bin - OpenHarmony 包管理器
- %TOOL_HOME%\tools\hvigor\bin - 构建工具
- %TOOL_HOME%\tools\node - Node.js 运行时
✅ 点击 "确定" 按钮保存

⚠️ 重要提示：

必须添加这三个路径，否则后续构建会失败

确保路径顺序正确，建议将这三个路径放在 PATH 的前面

如果 PATH 中已经有其他 Node.js 路径，建议保留 DevEco Studio 自带的版本

📌 步骤 6：配置 HDC_HOME 变量

HDC_HOME 指向 HarmonyOS 设备连接工具（HDC）的路径，用于连接真机或模拟器。

➕ 在 "系统变量" 区域，点击 "新建（W）..." 按钮
📝 填写变量信息：
- 变量名（N） ：HDC_HOME
- 变量值（V） ：%DEVECO_SDK_HOME%\default\openharmony\toolchains
✅ 点击 "确定" 按钮保存

💡 小提示：这个路径依赖于 SDK 的下载，如果还没有下载 SDK，请先完成 DevEco Studio 的 SDK 下载步骤。

📌 步骤 7：保存并验证配置

✅ 依次点击所有打开的窗口的 "确定" 按钮，保存所有配置
🔄 重要：关闭所有已打开的命令提示符窗口
🆕 重新打开命令提示符，环境变量才会生效

⚠️ 必须重新打开命令提示符：配置环境变量后，必须关闭所有已打开的命令提示符窗口，然后重新打开，环境变量才会生效！

📥 第二步：克隆 OpenHarmony 版 Flutter 源码

OpenHarmony 版 Flutter 的源码托管在开源仓库中，我们需要使用 Git 将其克隆到本地。

📌 步骤 1：选择存储位置

首先决定将 Flutter 源码克隆到哪里。建议选择一个空间充足的磁盘位置，例如：

C:\Tools\flutter_flutter（推荐）
D:\Development\flutter_flutter
E:\Flutter\flutter_flutter

💡 小提示：

选择一个路径后，后续配置环境变量时会用到这个路径

建议路径中不要包含中文字符，避免潜在问题

确保选择的磁盘有足够的空间（至少 2 GB）

📌 步骤 2：克隆仓库

🔍 打开命令提示符（CMD）或 Git Bash
📂 切换到你想存放 Flutter 源码的目录，例如：
bash 复制代码
```
cd C:\Tools
```
📥 执行克隆命令：
bash 复制代码
```
git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
```
💡 小提示：
- 也可以使用 https://atomgit.com/openharmony-tpc/flutter_flutter 作为仓库地址
- 克隆过程可能需要几分钟，取决于网络速度
- 如果克隆失败，检查网络连接或尝试使用代理

📌 步骤 3：查看可用分支

克隆完成后，进入 Flutter 目录并查看所有分支：

bash 复制代码

cd flutter_flutter
git branch -a

💡 小提示 ：-a 参数会显示所有分支（包括远程分支）。

📌 步骤 4：查看版本标签

查看可用的版本标签（tag）：

bash 复制代码

git tag

💡 小提示：标签通常对应稳定的版本，分支用于开发版本。

📌 步骤 5：切换到开发分支

根据你的需求选择合适的分支。本文以 oh-3.32.4-dev 分支为例：

bash 复制代码

git checkout -b oh-3.32.4-dev origin/oh-3.32.4-dev

或者如果分支已存在：

bash 复制代码

git checkout oh-3.32.4-dev

验证当前分支：

bash 复制代码

git branch

💡 小提示：

-b 参数会创建新分支并切换过去

如果分支已存在，直接使用 git checkout 即可

当前分支前会有 * 标记

建议使用最新的稳定分支，可以在仓库页面查看推荐分支

⚙️ 第三步：配置 Flutter 环境变量

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

📌 步骤 1：打开环境变量设置

按照第一步的方法，打开环境变量设置界面（如果已经打开，可以继续使用）。

📌 步骤 2：配置 PUB_CACHE 变量

PUB_CACHE 是 Flutter/Dart 包的缓存目录。

➕ 在 "系统变量" 区域，点击 "新建（W）..." 按钮
📝 填写变量信息：
- 变量名（N） ：PUB_CACHE
- 变量值（V） ：C:\PUB（或你自定义的路径）
✅ 点击 "确定" 按钮保存

💡 小提示：

C:\PUB 是推荐的路径，你也可以选择其他位置

确保路径存在，如果不存在，系统会自动创建

这个目录会存储下载的 Flutter 包，建议选择空间充足的磁盘

📌 步骤 3：配置 PUB_HOSTED_URL 变量

PUB_HOSTED_URL 是 Dart 包的镜像源地址，使用国内镜像可以加快下载速度。

➕ 在 "系统变量" 区域，点击 "新建（W）..." 按钮
📝 填写变量信息：
- 变量名（N） ：PUB_HOSTED_URL
- 变量值（V） ：https://pub.flutter-io.cn
✅ 点击 "确定" 按钮保存

💡 小提示：

这是 Flutter 中国镜像源，访问速度更快

如果镜像源不可用，可以尝试其他镜像或使用官方源

📌 步骤 4：配置 FLUTTER_STORAGE_BASE_URL 变量

FLUTTER_STORAGE_BASE_URL 是 Flutter 存储的镜像源地址。

➕ 在 "系统变量" 区域，点击 "新建（W）..." 按钮
📝 填写变量信息：
- 变量名（N） ：FLUTTER_STORAGE_BASE_URL
- 变量值（V） ：https://storage.flutter-io.cn
✅ 点击 "确定" 按钮保存

💡 小提示 ：这个变量和 PUB_HOSTED_URL 配合使用，都使用国内镜像可以显著提升下载速度。

📌 步骤 5：配置 PATH 变量（添加 Flutter）

将 Flutter 的 bin 目录添加到 PATH 变量中，这样你就可以在任何地方使用 flutter 命令了。

🔍 在 "系统变量" 区域，找到 "Path" 变量名
✏️ 点击 "编辑（I）..." 按钮，打开编辑环境变量窗口
➕ 点击 "新建" 按钮，添加 Flutter 的实际路径：
- C:\Tools\flutter_flutter\bin（替换为你实际克隆 Flutter 的路径）
⚠️ 重要：路径必须是 Flutter 源码目录下的 bin 文件夹，例如：
- 如果克隆到 C:\Tools\flutter_flutter，则添加 C:\Tools\flutter_flutter\bin
- 如果克隆到 D:\Flutter\flutter_flutter，则添加 D:\Flutter\flutter_flutter\bin
✅ 点击 "确定" 按钮保存

⚠️ 重要提示：

确保路径正确，指向 Flutter 源码的 bin 目录

建议将 Flutter 路径放在 PATH 的前面，避免与其他工具冲突

配置完成后，必须重新打开命令提示符才能生效

📌 步骤 6：验证环境配置

🔄 关闭所有已打开的命令提示符窗口
🆕 重新打开命令提示符
✅ 运行以下命令检查配置：

bash 复制代码

flutter doctor -v

期望输出 ：应该显示环境检查结果，Flutter、OpenHarmony、Android 都应该显示为 ✓ 或 ok。

⚠️ 如果遇到问题：

检查环境变量是否正确配置

确保重新打开了命令提示符

查看错误信息，参考常见问题部分

如果 flutter 命令找不到，检查 PATH 变量中的路径是否正确

🆕 第四步：创建 Flutter 工程

环境配置完成后，我们可以创建第一个 Flutter 项目了。

📌 步骤 1：选择项目创建方式

根据你的需求，有两种方式创建项目：

方式一：只创建 OpenHarmony 平台工程（推荐新手）

bash 复制代码

flutter create --platforms ohos <自定义项目名称>

方式二：创建多平台工程（Android、iOS、OpenHarmony）

bash 复制代码

flutter create <自定义项目名称>

💡 小提示：

项目名称使用小写字母和下划线，例如：my_first_app、harmony_app

如果只开发 HarmonyOS 应用，推荐使用方式一，项目结构更简洁

如果需要跨平台开发，使用方式二

示例：

bash 复制代码

# 只创建 OpenHarmony 平台
flutter create --platforms ohos my_harmony_app

# 创建多平台工程
flutter create my_cross_platform_app

📌 步骤 2：进入项目目录

创建完成后，进入项目目录：

bash 复制代码

cd <项目名称>

例如：cd my_harmony_app

📌 步骤 3：编译 HAP 包

HAP（HarmonyOS Ability Package）是 HarmonyOS 应用的安装包格式。

在项目根目录执行编译命令：

bash 复制代码

flutter build hap --debug

💡 参数说明：

--debug：编译调试版本（开发时使用）

--release：编译发布版本（正式发布时使用）

⏱️ 编译时间：首次编译可能需要几分钟，因为需要下载依赖和构建工具。
💡 小提示：

编译成功后，HAP 文件会生成在 build/hap/debug 目录下

如果编译失败，检查错误信息，参考常见问题部分

📱 第五步：使用模拟器验证应用

编译成功后，我们可以在模拟器或真机上运行应用进行验证。

📌 步骤 1：使用 DevEco Studio 打开项目

🚀 打开 DevEco Studio
📂 选择 "Open" 或 "Open or Import"
📁 导航到你的 Flutter 项目目录，选择其中的 ohos 文件夹打开

💡 小提示 ：Flutter 项目中的 ohos 文件夹是 HarmonyOS 平台的工程文件