Flutter for HarmonyOS 开发指南（一）：环境搭建与项目创建

本篇将详细介绍如何搭建 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社区的官方文档和更新日志 。