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开发环境

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

📋 安装前准备

在开始之前，请确保：

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

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

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

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

📌 步骤 1：打开系统属性

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

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

方法二：通过设置应用

1. 按Win + I打开设置
2. 搜索“高级系统设置”
3. 点击打开系统属性面板

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

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

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

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

📌 步骤 3：配置 TOOL_HOME 变量

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

1. ➕ 在“系统变量”区域，点击“新建（W）…”按钮

2. 📝 填写变量信息：

   • 变量名（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

3. ✅ 点击“确定”按钮保存

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

📌 步骤 4：配置 DEVECO_SDK_HOME 变量

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

1. ➕ 在“系统变量”区域，点击“新建（W）…”按钮

2. 📝 填写变量信息：

   • 变量名（N）：DEVECO_SDK_HOME
   • 变量值（V）：%TOOL_HOME%\sdk

   💡小提示：%TOOL_HOME%会引用之前设置的TOOL_HOME变量值，这样如果 DevEco Studio 安装路径改变，只需要修改TOOL_HOME即可。

3. ✅ 点击“确定”按钮保存

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

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

1. 🔍 在“系统变量”区域，找到“Path”变量名

2. ✏️ 点击“编辑（I）…”按钮，打开编辑环境变量窗口

3. ➕ 点击“新建”按钮，依次添加以下三个路径（分别添加，每次点击新建）：

   • %TOOL_HOME%\tools\ohpm\bin- OpenHarmony 包管理器
   • %TOOL_HOME%\tools\hvigor\bin- 构建工具
   • %TOOL_HOME%\tools\node- Node.js 运行时

4. ✅ 点击“确定”按钮保存

⚠️重要提示：

• 必须添加这三个路径，否则后续构建会失败
• 确保路径顺序正确，建议将这三个路径放在 PATH 的前面
• 如果 PATH 中已经有其他 Node.js 路径，建议保留 DevEco Studio 自带的版本

📌 步骤 6：配置 HDC_HOME 变量

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

1. ➕ 在“系统变量”区域，点击“新建（W）…”按钮

2. 📝 填写变量信息：

   • 变量名（N）：HDC_HOME
   • 变量值（V）：%DEVECO_SDK_HOME%\default\openharmony\toolchains

3. ✅ 点击“确定”按钮保存

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

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

1. ✅ 依次点击所有打开的窗口的“确定”按钮，保存所有配置

2. 🔄重要：关闭所有已打开的命令提示符窗口

3. 🆕 重新打开命令提示符，环境变量才会生效

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

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

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

📌 步骤 1：选择存储位置

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

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

💡小提示：

• 选择一个路径后，后续配置环境变量时会用到这个路径
• 建议路径中不要包含中文字符，避免潜在问题
• 确保选择的磁盘有足够的空间（至少 2 GB）

📌 步骤 2：克隆仓库

1. 🔍 打开命令提示符（CMD）或 Git Bash

2. 📂 切换到你想存放 Flutter 源码的目录，例如：

   cdC:\Tools

3. 📥 执行克隆命令：

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

   💡小提示：

   • 也可以使用https://atomgit.com/openharmony-tpc/flutter_flutter作为仓库地址
   • 克隆过程可能需要几分钟，取决于网络速度
   • 如果克隆失败，检查网络连接或尝试使用代理

📌 步骤 3：查看可用分支

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

cdflutter_fluttergitbranch -a

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

📌 步骤 4：查看版本标签

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

gittag

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

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

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

gitcheckout -b oh-3.32.4-dev origin/oh-3.32.4-dev

或者如果分支已存在：

gitcheckout oh-3.32.4-dev

验证当前分支：

gitbranch

💡小提示：

• -b参数会创建新分支并切换过去
• 如果分支已存在，直接使用git checkout即可
• 当前分支前会有*标记
• 建议使用最新的稳定分支，可以在仓库页面查看推荐分支

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

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

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

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

📌 步骤 2：配置 PUB_CACHE 变量

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

1. ➕ 在“系统变量”区域，点击“新建（W）…”按钮

2. 📝 填写变量信息：

   • 变量名（N）：PUB_CACHE
   • 变量值（V）：C:\PUB（或你自定义的路径）

3. ✅ 点击“确定”按钮保存

💡小提示：

• C:\PUB是推荐的路径，你也可以选择其他位置
• 确保路径存在，如果不存在，系统会自动创建
• 这个目录会存储下载的 Flutter 包，建议选择空间充足的磁盘

📌 步骤 3：配置 PUB_HOSTED_URL 变量

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

1. ➕ 在“系统变量”区域，点击“新建（W）…”按钮

2. 📝 填写变量信息：

   • 变量名（N）：PUB_HOSTED_URL
   • 变量值（V）：https://pub.flutter-io.cn

3. ✅ 点击“确定”按钮保存

💡小提示：

• 这是 Flutter 中国镜像源，访问速度更快
• 如果镜像源不可用，可以尝试其他镜像或使用官方源

📌 步骤 4：配置 FLUTTER_STORAGE_BASE_URL 变量

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

1. ➕ 在“系统变量”区域，点击“新建（W）…”按钮

2. 📝 填写变量信息：

   • 变量名（N）：FLUTTER_STORAGE_BASE_URL
   • 变量值（V）：https://storage.flutter-io.cn

3. ✅ 点击“确定”按钮保存

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

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

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

1. 🔍 在“系统变量”区域，找到“Path”变量名

2. ✏️ 点击“编辑（I）…”按钮，打开编辑环境变量窗口

3. ➕ 点击“新建”按钮，添加 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

4. ✅ 点击“确定”按钮保存

⚠️重要提示：

• 确保路径正确，指向 Flutter 源码的bin目录
• 建议将 Flutter 路径放在 PATH 的前面，避免与其他工具冲突
• 配置完成后，必须重新打开命令提示符才能生效

📌 步骤 6：验证环境配置

1. 🔄 关闭所有已打开的命令提示符窗口

2. 🆕 重新打开命令提示符

3. ✅ 运行以下命令检查配置：

flutter doctor -v

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

⚠️如果遇到问题：

• 检查环境变量是否正确配置
• 确保重新打开了命令提示符
• 查看错误信息，参考 常见问题 部分
• 如果flutter命令找不到，检查 PATH 变量中的路径是否正确

🆕 第四步：创建 Flutter 工程

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

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

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

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

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

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

flutter create<自定义项目名称>

💡小提示：

• 项目名称使用小写字母和下划线，例如：my_first_app、harmony_app
• 如果只开发 HarmonyOS 应用，推荐使用方式一，项目结构更简洁
• 如果需要跨平台开发，使用方式二

示例：

# 只创建 OpenHarmony 平台flutter create --platforms ohos my_harmony_app# 创建多平台工程flutter create my_cross_platform_app

📌 步骤 2：进入项目目录

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

cd<项目名称>

例如：cd my_harmony_app

📌 步骤 3：编译 HAP 包

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

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

flutter build hap --debug

💡参数说明：

• --debug：编译调试版本（开发时使用）
• --release：编译发布版本（正式发布时使用）

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

💡小提示：

• 编译成功后，HAP 文件会生成在build/hap/debug目录下
• 如果编译失败，检查错误信息，参考 常见问题 部分

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

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

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

1. 🚀 打开 DevEco Studio

2. 📂 选择“Open”或“Open or Import”

3. 📁 导航到你的 Flutter 项目目录，选择其中的ohos文件夹打开

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

4. ⏳ 等待工程初始化完成（首次打开可能需要几分钟）

📌 步骤 2：打开设备管理界面

1. 🔍 在 DevEco Studio 顶部菜单栏，找到设备管理图标

2. 👆 点击打开设备管理界面

📌 步骤 3：配置模拟器存储路径（可选）

如果 C 盘空间不足，可以更改模拟器的存储路径：

1. ⚙️ 在设备管理界面，点击“Edit”按钮

2. 📂 选择一个新的存储路径（建议选择空间充足的磁盘）

3. ✅ 点击“OK”保存

📌 步骤 4：创建模拟器

1. ➕ 点击“+ New Emulator”按钮打开创建模拟器界面

2. 📂 如果需要，点击“Edit”更改模拟器镜像存储路径

3. 📱 找到名称为“Huawei_Phone”，版本号为“HarmonyOS 6.0.0(20)”的镜像

4. ⬇️ 点击该镜像行的下载按钮，开始下载

⏱️下载时间：镜像文件较大（约 1-2 GB），下载可能需要 10-30 分钟，请耐心等待。

📌 步骤 5：接受下载协议

1. 📄 在下载协议界面，勾选“Accept”表示同意协议

2. 👆 点击“Next”按钮开始下载

📌 步骤 6：配置模拟器

1. ✅ 镜像下载完成后，选择当前镜像

2. 👆 点击“Next”按钮进入模拟器配置界面

3. ⚙️ 保持默认配置即可（或根据需要调整）

4. ✅ 点击“Finish”按钮完成创建

📌 步骤 7：启动模拟器

1. 📱 模拟器创建完成后，会在设备管理界面显示

2. ▶️ 点击右侧的启动按钮启动模拟器

⏱️启动时间：首次启动模拟器可能需要 1-2 分钟，请耐心等待。

📌 步骤 8：配置应用签名

HarmonyOS 应用需要签名才能安装到设备上。

1. 📋 在 DevEco Studio 中，点击“File”→“Project Structure…”打开工程配置界面

2. 🔐 切换到“Signing Configs”页签

3. 👤 登录已经实名认证的华为开发者账号

4. ✅ 完成自动签名配置

⚠️重要提示：必须使用已实名认证的华为开发者账号才能完成签名。

📌 步骤 9：运行应用

1. ▶️ 点击 DevEco Studio 工具栏的运行/调试按钮（绿色三角形图标）

2. 📱 选择已启动的模拟器作为运行目标

3. ⏳ 等待应用编译和安装（首次运行可能需要几分钟）

4. 🎉 应用成功运行后，你会在模拟器上看到 Flutter 应用的界面！

💡小提示：

• 如果运行失败，检查错误信息
• 确保模拟器已完全启动
• 确保签名配置正确