本篇将详细介绍如何搭建 Flutter for HarmonyOS 的开发环境并创建第一个项目。以下是主要内容概览：
| 阶段 | 关键任务 | 核心要点 |
|---|---|---|
| 1. 环境准备 | 安装基础工具与SDK | JDK 17、特定版本Flutter SDK (3.22.x-ohos)、DevEco Studio 5.0+、Node.js (v14.19.1+) |
| 2. 环境配置 | 设置路径与变量 | 配置Flutter、HarmonyOS SDK、ohpm、hvigor等环境变量 |
| 3. 项目创建 | 初始化与平台支持 | 使用 flutter create --platforms ohos创建项目，生成ohos目录 |
| 4. 项目运行 | 构建与安装 | 使用 flutter build hap编译HAP包，通过 flutter run -d harmony运行 |
一、环境准备：安装必要工具与SDK
在开始之前，需要准备以下基础软件，这是构建Flutter鸿蒙应用的基石 ：
Java环境：确保已安装 JDK 17。可通过命令行
java -version验证 。HarmonyOS开发工具：安装 DevEco Studio 5.0或更高版本，它集成了HarmonyOS SDK、ohpm（HarmonyOS包管理器）、hvigor（构建工具）和Node.js环境 。
Flutter SDK（鸿蒙特供版）：这是关键一步。由于官方Flutter SDK尚未正式支持HarmonyOS，你需要使用由OpenHarmony-SIG社区维护的特定版本。目前推荐的稳定版本是 3.22.x-ohos系列。
获取方式：通过Git克隆指定仓库并切换到对应分支。
git clone https://gitcode.com/openharmony-sig/flutter_flutter.git cd flutter_flutter git checkout 3.22.1-ohos-1.0.0 # 或最新的ohos分支版本管理建议：为了避免与你可能已安装的标准Flutter SDK产生冲突，强烈建议使用 **FVM (Flutter Version Management)**来管理多个Flutter版本 。你也可以考虑将鸿蒙版Flutter的可执行文件重命名（例如改为
hflutter）以方便区分 。
二、环境配置：设置系统变量
安装完成后，需要配置系统环境变量，以便在终端中能够顺利调用各种命令 。
- Flutter SDK路径：将你克隆的Flutter SDK的
bin目录路径添加到系统的PATH变量中。 - HarmonyOS开发工具路径：将DevEco Studio安装目录下的相关工具路径添加到
PATH中，通常包括：$TOOL_HOME/tools/ohpm/bin$TOOL_HOME/tools/hvigor/bin$TOOL_HOME/tools/node/bin（其中TOOL_HOME是DevEco Studio的安装路径）。 - HDC端口号：为方便调试，建议设置
HDC_SERVER_PORT环境变量，值可设置为如7035等未被占用的端口 。
配置完成后，在终端执行 flutter doctor -v命令来验证环境是否配置成功。理想的输出结果应显示Flutter SDK版本为鸿蒙分支，并且HarmonyOS工具链各项前面有对勾(√)表示就绪 。
三、项目创建与结构解析
环境配置无误后，即可开始创建你的第一个Flutter鸿蒙项目。
创建新项目：使用以下命令创建一个支持HarmonyOS平台的新项目 。
flutter create --platforms ohos,android,ios --org com.yourcompany my_harmony_app参数
--platforms ohos表示项目将包含鸿蒙平台的原生支持代码。为现有项目添加鸿蒙支持：如果你已有一个Flutter项目，可以在项目根目录下执行以下命令来添加鸿蒙平台支持 。
flutter create --platforms ohos .项目结构解析：命令执行成功后，项目目录下会生成一个
ohos文件夹，这就是鸿蒙平台的宿主工程，其结构遵循HarmonyOS应用的标准规范 。entry/src/main/ets/: 存放ArkTS原生代码的入口，例如生成的Flutter页面承载组件Index.ets。build-profile.json5: 鸿蒙项目的构建配置文件，可在此配置应用签名、目标设备类型（如手机、平板、PC需添加"2in1"）等 。oh-package.json5: 鸿蒙项目的依赖管理文件，类似于Android的build.gradle或Flutter的pubspec.yaml。
四、项目运行与调试
项目创建完成后，可以尝试运行到设备上。
构建HAP包：使用以下命令可以编译生成HarmonyOS的应用安装包（HAP） 。
flutter build hap --release生成的HAP文件位于
ohos/entry/build目录下。运行到设备：将鸿蒙真机通过USB连接电脑并开启调试模式，或启动模拟器。然后使用以下命令运行应用 。
flutter run -d harmony你可以通过
flutter devices命令查看当前已连接且可用的设备列表及其ID 。可能遇到的问题： 设备识别：如果Android Studio或DevEco Studio无法识别鸿蒙设备，确保已正确安装HDC驱动并设置了
HDC_SERVER_PORT环境变量 。 签名问题：首次在真机上运行调试版应用可能需要配置调试签名。可以在DevEco Studio中打开ohos目录，在File > Project Structure > Signing Configs中自动生成调试签名 。
完成以上步骤，你应该就能在鸿蒙设备或模拟器上看到默认的Flutter计数器应用在运行了，这标志着你的Flutter for HarmonyOS开发环境已经成功搭建！
本篇重点在于环境的准备和第一个项目的成功运行。在后续文章中，我们将深入探讨Flutter与HarmonyOS原生能力的交互、UI适配以及更复杂的应用场景。请注意，社区版本的Flutter for HarmonyOS仍在快速发展中，相关命令和配置可能随版本更新有所调整，建议随时关注OpenHarmony-SIG社区的官方文档和更新日志 。