Flutter × OpenHarmony 开发日记 Day1：从克隆仓库到环境就绪

日期 ：2026年6月2日

目标 ：搭建 Flutter-OH 开发环境，完成第一个鸿蒙应用

版本：Flutter 3.35.8-ohos-1.0.1 / Dart 3.9.2 / OpenHarmony SDK 6.0.1

---

一、开篇：为什么选择 Flutter + OpenHarmony？

2026年，OpenHarmony 生态已进入成熟期，Flutter 作为 Google 推出的跨平台 UI 框架，凭借自绘引擎的极致性能，已成为追求高流畅度、高定制 UI 应用的首选。其鸿蒙适配版（Flutter-OH）正致力于将这一体验无缝延伸至鸿蒙设备，实现"一次开发，多平台部署"的愿景。

今天，我正式踏上了 Flutter-OH 的开发之旅，目标是搭建完整的开发环境并跑通第一个应用。

---

二、克隆 Flutter-OH SDK

Flutter 的鸿蒙定制版本需要从 OpenHarmony-TPC 官方仓库获取，而非 Google 官方仓库。我使用以下命令克隆指定版本：

git clone --depth 1 --branch 3.35.8-ohos-1.0.1 https://gitcode.com/openharmony-tpc/flutter_flutter.git

参数说明：

• --depth 1：浅克隆，只拉取最新提交，大幅节省时间和磁盘空间
• --branch 3.35.8-ohos-1.0.1：锁定到特定稳定版本，避免后续版本升级带来的兼容性问题
• 仓库地址：https://gitcode.com/openharmony-tpc/flutter_flutter.git（OpenHarmony 官方 TPC 仓库）

⚠️ 路径警告 ：克隆位置不要包含中文或空格 ，否则可能导致后续构建工具（如 hvigor）解析路径异常。建议选择纯英文路径，例如 C:\flutter_flutter 或 ~/dev/flutter_flutter。
💡 版本选择建议：当前社区推荐版本为 Flutter 3.35.7/3.35.8 系列，这是目前最稳定的适配版本。

---

三、环境配置

3.1 前置依赖

在配置 Flutter-OH 之前，需要确保以下环境已就绪：

依赖项	版本要求	说明
JDK	17	必须安装，Flutter 插件编译 HAP 及 DevEco 工具链均依赖 Java 17
DevEco Studio	6.0.1+	鸿蒙官方 IDE，内置 OpenHarmony SDK
Node.js	18+	hvigor 构建工具依赖
Git	任意	代码管理

💡 JDK 特别提醒 ：即使你使用 VS Code + Flutter 插件运行鸿蒙应用，JDK 17 仍是必需项。Flutter-OH 在后台调用 DevEco 工具链和 hvigor 构建时，会依赖 Java 环境进行编译和签名。

3.2 环境变量配置

将克隆好的 Flutter 目录添加到系统环境变量：

macOS / Linux：

export PATH="$HOME/flutter_flutter/bin:$PATH"
export PUB_HOSTED_URL="https://pub.flutter-io.cn"
export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"
export FLUTTER_GIT_URL="git@gitcode.com:openharmony-tpc/flutter_flutter.git"
export DEVECO_SDK_HOME="/path/to/your/DevEcoStudio/Sdk"
export JAVA_HOME="/path/to/jdk-17"  # 例如 /Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home

Windows ：

在系统环境变量 Path 中添加 flutter_flutter\bin 路径，并新建以下系统变量：

变量名	变量值	说明
DEVECO_SDK_HOME	C:\Users\<用户名>\AppData\Local\OpenHarmony\Sdk	DevEco Studio SDK 根目录
JAVA_HOME	C:\Program Files\Java\jdk-17	JDK 17 安装目录

💡 关于 DEVECO_SDK_HOME ：该变量指向 DevEco Studio 内置的 OpenHarmony SDK 根目录，Flutter-OH 编译 HAP 包时会自动读取此路径定位工具链。若未设置，可能出现 ohos-sdk not found 报错。
💡 关于 JAVA_HOME ：确保 JAVA_HOME/bin 也在系统 Path 中，以便命令行直接调用 java 和 javac。

3.3 配置鸿蒙 SDK 路径

flutter config --ohos-sdk=/path/to/your/OpenHarmony/Sdk

---

四、验证环境

4.1 检查 Flutter 版本

flutter --version

预期输出：

Flutter 3.35.8-ohos-1.0.1 • channel [user-branch] •
https://gitcode.com/openharmony-tpc/flutter_flutter.git
Framework • revision xxxxxxxxxx
Engine • hash 6b24e1b529bc46df7ff397667502719a2a8b6b72
Tools • Dart 3.9.2 • DevTools 2.48.0

4.2 运行 Flutter Doctor

flutter doctor -v

关键检查项：

• ✅ Flutter - SDK 版本和路径正确
• ✅ Java binary - JDK 17 已正确识别
• ✅ HarmonyOS toolchain - OpenHarmony SDK 和工具链就绪
  
• ⚠️ Android toolchain / Xcode 显示 [!] 可忽略（仅鸿蒙开发无需处理）

---

五、创建第一个鸿蒙应用

5.1 初始化项目

# 创建仅支持鸿蒙的项目
flutter create --platforms ohos my_ohos_app
cd my_ohos_app

5.2 项目结构

my_ohos_app/
├── lib/              # Dart 业务代码
├── ohos/             # 鸿蒙原生代码（ArkTS）
│   ├── entry/        # 入口模块
│   └── ...
├── android/          # Android 平台代码
├── ios/              # iOS 平台代码
├── pubspec.yaml      # 依赖配置
└── ...

5.3 编译并运行

# 查看已连接设备
flutter devices

# 一键运行（自动编译+安装+启动）
flutter run --debug -d <device-id>

或者先编译 HAP 包：

flutter build hap --debug

产物路径：my_ohos_app/ohos/entry/build/default/outputs/default/entry-default-signed.hap

---

六、真机运行：配置签名

真机运行前必须在 DevEco Studio 中配置签名 ，否则安装时会报 INSTALL_FAILED_APP_SOURCE_NOT_TRUSTED 错误。

6.1 自动签名（推荐）

1. 用 DevEco Studio 打开项目的 ohos 目录
2. 点击顶部菜单 File → Project Structure → Project → Signing Configs
3. 勾选 Automatically generate signature
4. 点击 Apply 后 IDE 会自动生成调试证书并配置到 ohos/entry/build-profile.json5

💡 原理：DevEco Studio 会向华为开发者联盟申请临时调试证书，自动完成证书、私钥和 Profile 文件的配置。

6.2 手动签名（企业/发布场景）

如需使用正式证书：

1. 在 华为开发者联盟 申请应用 ID、调试/发布证书和 Profile 文件
2. 在 DevEco Studio 的 Signing Configs 中手动导入 .p12（证书）、.csr（私钥）和 .p7b（Profile）
3. 确保证书指纹与真机设备的 UDID 已绑定

6.3 签名后的构建

配置签名后，重新执行：

flutter build hap --debug
# 或
flutter run --debug -d <device-id>

此时构建出的 HAP 包已包含有效签名，可直接安装到真机。

---

七、今日踩坑记录

⚠️ 坑1：网络超时

flutter doctor 检查 GitHub 时可能出现 "信号灯超时时间已到"。解决方案：

• 配置国内镜像源（PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL）
• 或设置代理

⚠️ 坑2：JDK 版本不匹配或缺失

如果 flutter doctor 提示 Java 错误，或 VS Code 运行时报 java: command not found：

java -version
# 必须输出 Java 17

• 若未安装 JDK，请先下载 Oracle JDK 17 或 Eclipse Temurin 17
• 安装后务必配置 JAVA_HOME 环境变量，并重启终端/IDE

💡 特别注意：部分开发者误以为"用 Flutter 插件就不需要装 JDK"，这是错误的。Flutter-OH 的后端编译流程深度依赖 Java 工具链。

⚠️ 坑3：ohpm/hvigor 未找到

确保 DevEco Studio 的 tools/ohpm/bin 和 tools/hvigor/bin 已添加到系统 Path 中。

⚠️ 坑4：DEVECO_SDK_HOME 未设置导致构建失败

如果执行 flutter build hap 时提示找不到 SDK 或 hvigor 报错，请检查：

1. 系统环境变量中是否已添加 DEVECO_SDK_HOME
2. 该路径是否指向 DevEco Studio 安装目录下的 Sdk 文件夹（包含 toolchains、previewer 等子目录）
3. 路径中是否含有中文或空格

⚠️ 坑5：真机安装报 INSTALL_FAILED_APP_SOURCE_NOT_TRUSTED

原因 ：HAP 包未签名或签名无效。

解决：参考第六节，在 DevEco Studio 中配置自动签名后重新构建。

---

八、多版本管理（进阶）

如果你同时维护官方 Flutter 和 Flutter-OH，推荐使用 FVM 管理多版本 SDK：

# 安装 FVM
brew tap leoafarias/fvm
brew install fvm

# 安装 Flutter-OH 到 FVM 管理目录
cd ~/fvm/versions
git clone -b 3.35.8-ohos-1.0.1 https://gitcode.com/openharmony-tpc/flutter_flutter.git
mv flutter_flutter custom_3.35.8_ohos

# 切换使用
fvm global custom_3.35.8_ohos
fvm flutter doctor

---

九、Day1 总结

任务	状态
克隆 Flutter-OH SDK	✅ 完成
配置环境变量	✅ 完成
运行 flutter doctor	✅ 通过
创建第一个鸿蒙应用	✅ 完成
配置真机签名	✅ 完成
成功运行到设备	⏳ 待验证

---

参考资源

• 📦 官方仓库：openharmony-tpc/flutter_flutter
• 📚 开源鸿蒙跨平台开发者社区：openharmonycrossplatform.csdn.net

---

📝 写在最后：Flutter-OH 的生态正在快速发展，FOHWG（Flutter-OpenHarmony 工作组）正主导标准化推进，计划2026年完成轻量级 Embedder 接口规范制定。作为开发者，现在正是入场的最佳时机。

---

本博客持续更新中，欢迎关注 Day2 的进阶实践！