本次训练营 DAY1 的核心目标是帮助开发者快速掌握Flutter for OpenHarmony的开发环境搭建流程，理解其底层适配逻辑，并成功创建、运行第一个跨平台项目。相比原生 Flutter 或纯 OpenHarmony 开发，该技术栈的核心是通过定制化引擎适配鸿蒙系统，新手需重点关注版本匹配和环境配置，这是避免 80% 实操报错的关键。

一、先搞懂核心架构

不是 “插件”，是 “引擎适配” 很多新手会误以为 Flutter for OpenHarmony 是一个简单的鸿蒙插件，实则不然： 底层逻辑：它是基于 Flutter 官方源码定制的鸿蒙专属引擎，核心是适配 OpenHarmony 的渲染管线（渲染、布局、事件处理），而非简单的 API 调用； 项目结构：采用「OpenHarmony Stage 模型 + Flutter 模块标准结构」的组合形式，既遵循鸿蒙的应用工程规范，又保留 Flutter 的跨端开发特性。 理解这一点，能帮你后续快速定位 “引擎不兼容”“渲染异常” 等核心问题。 二、环境搭建：硬性要求（版本错了必报错） 以下配置是经过验证的稳定版本组合，建议设备内存≥16G（内存不足会导致 DevEco Studio 卡顿、SDK 编译失败）

二、环境搭建：硬性要求（版本错了必报错） 

组件	推荐版本	关键注意事项
操作系统	Windows 10/11（64 位）、macOS 12+	不支持 32 位 Windows，macOS 需关闭系统完整性保护（SIP）
JDK	OpenJDK 17	必须是 17 版本（8/11 版本会直接导致 HAP 包编译失败）
DevEco Studio	5.0 Release 及以上	优先选 API 12/13 适配版本，需提前安装鸿蒙 SDK（API 12/13）
Node.js	复用 DevEco Studio 自带版本	无需单独下载，直接引用 IDE 内置路径即可（避免版本冲突）
鸿蒙 SDK	API 12/13	需在 DevEco Studio 的「Settings > Appearance & Behavior > System Settings > HarmonyOS SDK」中下载

三、获取鸿蒙定制版 Flutter SDK

 原生 Flutter SDK 不兼容 OpenHarmony，必须使用华为 / 开源社区维护的定制版，步骤如下（建议用 Git 命令行操作，避免手动下载包缺失）：

1. 克隆源码仓库

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

2. 切换到稳定分支

分支名称会随鸿蒙版本迭代更新，当前推荐的稳定分支为oh-3.22.0-dev：

3. 常见问题：克隆失败 / 分支切换报错

问题 1：git clone速度慢 / 超时 

解决方案：配置 Git 代理，或直接从开源仓下载压缩包（https://atomgit.com/openharmony-tpc/flutter_flutter/-/archive/oh-3.22.0-dev/flutter_flutter-oh-3.22.0-dev.zip）；

问题 2：origin/oh-3.22.0-dev不存在

解决方案：先执行git fetch拉取最新分支列表，再确认分支名称是否更新。

四、第二步：配置环境变量（分系统细化）

环境变量配置是核心步骤，需同时配置 Flutter SDK 和鸿蒙相关路径，以下分系统说明：

1. Windows 系统配置 （1）打开环境变量设置 右键「此电脑」→「属性」→「高级系统设置」→「环境变量」。

（2）系统变量新增 / 修改

变量名	变量值（示例）	说明
FLUTTER_HOME	D:\flutter_flutter（你的 SDK 克隆路径）	指向定制版 Flutter SDK 根目录
PATH	% FLUTTER_HOME%\bin（追加到 PATH 末尾）	让系统识别 flutter 命令
JAVA_HOME	D:\DevEco Studio\jdk\17.0.9（DevEco 内置 JDK 路径）	指向 JDK 17 安装目录
OH_FLUTTER_SDK_PATH	%FLUTTER_HOME%	鸿蒙识别 Flutter SDK 的专属变量

（3）验证配置是否生效

重启终端，执行以下命令，返回版本信息即配置成功：

2. macOS 系统配置

（1）编辑环境变量配置文件

打开终端，执行以下命令（以 zsh 为例，bash 需修改为～/.bash_profile）：

（2）添加配置内容

在文件末尾追加以下内容（替换为你的实际路径）：

（3）生效配置并验证

五、第三步：创建并运行第一个 Flutter for OpenHarmony 项目

1. 用 DevEco Studio 创建项目

1. 打开 DevEco Studio，选择「Create New Project」；
2. 模板选择：找到「Flutter for OpenHarmony」分类（若无该模板，需在 DevEco 插件市场安装「Flutter OH Plugin」）；
3. 填写项目信息：项目名（如first_oh_flutter）、保存路径、选择 API 版本（12/13）；
4. 点击「Finish」，等待项目初始化（首次初始化会下载依赖，需耐心等待）。

2. 运行项目

方式 1：DevEco Studio 可视化操作

1. 顶部工具栏选择运行设备：可选择「鸿蒙模拟器」（需提前在 DevEco 中创建 API 12/13 模拟器）或「真实鸿蒙设备」（需开启开发者模式）；
2. 点击「运行」按钮（绿色三角），等待编译、安装、运行。