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

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

一、为什么是 Flutter for OpenHarmony？

Flutter for OpenHarmony——它和其他跨平台框架不一样，不是在鸿蒙系统上“套一层壳”，而是通过 XComponent 直接接入了鸿蒙的渲染管线。说白了，就是既能用上 Flutter 自带的 Skia/Impeller 自绘引擎，保证多端 UI 长得一模一样，又能不浪费鸿蒙系统本身的高性能，对新手来说，兼顾效率和体验，性价比拉满。

二、环境搭建：

1.Java 17
DevEco Studio强制依赖Java 17，低版本会导致flutter build hap报错（如堆栈溢出或类加载失败）。

2.社区版 SDK

这里要重点提醒：官方原版的 Flutter，是不直接支持 OpenHarmony 的！

3.DevEco Studio

三、 获取 Flutter for OpenHarmony 源码：

1. 选择安装目录

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

2. 克隆代码

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

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

cd flutter_flutter

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

四、配置变量

步骤1：配置鸿蒙工具链核心变量

1. 新建变量 TOOL_HOME：变量值填 DevEco Studio 根目录（示例：C:\Program Files\Huawei\DevEco Studio），避坑重点：必须是根目录，不可加 \bin 等子目录，否则后续 ohpm、hvigor 无法识别。

2. 新建变量 DEVECO_SDK_HOME：变量值填 %TOOL_HOME%\sdk，优势：通过环境变量引用，后续若修改 DevEco Studio 安装路径，无需重新配置此变量。

3. 新建变量 HDC_HOME：变量值填 %DEVECO_SDK_HOME%\default\openharmony\toolchains，作用：HDC 是鸿蒙设备调试工具，配置此路径，终端才能识别 hdc 相关命令，避免后续设备连接失败。

步骤2：配置 Flutter 镜像变量（3个，加速依赖下载）

1. 新建变量 PUB_HOSTED_URL，变量值：https://pub.flutter-io.cn（Dart 包镜像源，不可随意修改）。

2. 新建变量 FLUTTER_STORAGE_BASE_URL，变量值：https://storage.flutter-io.cn（与上一镜像源配套使用，确保下载稳定）。

3. 可选新建变量 PUB_CACHE，变量值填自定义缓存路径（示例：D:\Flutter\PubCache），作用：避免缓存文件占用 C 盘空间，无此需求可省略。

步骤3：配置 Path 系统变量

1. 打开系统变量中的 Path，点击「新建」，依次添加以下4个路径：

2. Flutter Bin 目录：C:\Tools\flutter_flutter\bin

3. 鸿蒙包管理器路径：%TOOL_HOME%\tools\ohpm\bin

4. 鸿蒙构建工具路径：%TOOL_HOME%\tools\hvigor\bin

5. IDE 自带 Node.js 路径：%TOOL_HOME%\tools\node\bin（最容易遗漏的坑）

五、验证环境

输入以下命令

flutter doctor -v

如结果包含HarmonyOS toolchain；Android toolchain / Xcode；则验证成功

六、成果验证

解决完上面所有的问题，终于顺利创建并编译出了第一个鸿蒙 Flutter 工程。

关键步骤（简化版，不流水账）：

1. 创建工程：终端执行flutter create --platforms ohos my_app（一定要加 --platforms ohos，不然默认不支持鸿蒙）

2. 编译 HAP 包：执行flutter build hap --debug，第一次编译可能有点慢

七、总结

第一天的任务，看似是“搭建环境”这种基础操作，实则是对细心程度的考验，踩了这么多坑，我总结出两个核心感悟，分享给大家：

1. 千万别轻视版本号！真的不是随便装个版本就行，比如API 12的SDK，就得配5.0以上的 DevEco Studio，差一个版本，可能就卡一下午，别偷懒，严格对齐版本。

2. Windows 环境的小坑：如果你在 Windows 上操作，遇到脚本报错，先别慌，检查一下文件的换行符——大概率是Git自动改成了CRLF，改成LF格式，基本就能解决。