2026 年如何上车 Flutter-OH：环境搭建与上手流程

本文面向 2026 年打算开始使用或迁移到 Flutter-OH 的开发者，按「下载物料 → 配置环境 → 验证环境 → 创建工程 → 可选：适配三方库」的顺序，梳理从零到跑通的第一条链路，并给出版本选择与延伸学习建议。

一、上车前先搞清楚两件事

1. 我该用哪个 Flutter-OH 版本？

场景	推荐版本	说明
生产 / 正式项目	3.27.4-ohos 系列（如 1.0.3）	稳定、有发版说明，适合商业项目
学习 / 尝鲜 / 跟最新能力	oh-3.35.7-dev	技术预览分支，可体验新特性，不建议直接用于生产

2026 年 Flutter-OH 会按季度发版，与上游 Flutter 的滞后会逐步缩短，选稳定版可减少后续升级成本。详见 Flutter OH 版本演进与分支策略。

2. 我需要准备哪些东西？

操作系统：Windows / macOS（本文以常见环境为例）
IDE：DevEco Studio（开发、调试、签名鸿蒙应用）
Flutter-OH SDK：从 OpenHarmony 社区仓库按分支或 tag 获取
鸿蒙设备或模拟器：真机需开启开发者模式并配置签名

二、下载物料

1. DevEco Studio

下载并安装 DevEco Studio（建议 6.x，如 6.0.2 Release 或更高）
安装时勾选 HarmonyOS SDK，或安装后在 IDE 内通过 SDK 管理下载

参考：华为开发者官网 - DevEco Studio

2. Flutter-OH SDK

根据你在「一」中的选择，二选一即可。

方式 A：生产推荐 ------ 3.27.4 系列（稳定版）

bash 复制代码

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
cd flutter_flutter
git checkout oh-3.27.0-release

方式 B：学习 / 尝鲜 ------ oh-3.35.7-dev

bash 复制代码

git clone https://gitcode.com/openharmony-tpc/flutter_flutter.git
cd flutter_flutter
git checkout -b dev origin/oh-3.35.7-dev

也可只拉取单一分支以节省空间，例如：

bash 复制代码

git clone -b oh-3.35.7-dev --single-branch https://gitcode.com/openharmony-tpc/flutter_flutter.git

三、配置环境

1. 将 Flutter-OH 加入 PATH

把上面 clone 的 flutter_flutter 目录下的 bin 加入系统 PATH，确保终端中执行的是 Flutter-OH 的 flutter，而不是官方 Flutter。

macOS / Linux ：在 ~/.zshrc 或 ~/.bashrc 中增加
export PATH="<你的路径>/flutter_flutter/bin:$PATH"
Windows ：在系统环境变量中增加 <你的路径>\flutter_flutter\bin

2. 配置 ohos-sdk 路径（重要）

让 Flutter-OH 使用 DevEco Studio 自带的 HarmonyOS SDK，避免路径不一致导致报错。

清空当前配置：flutter config --ohos-sdk=''
查看 DevEco 的 SDK 路径：
- macOS/Linux：echo $DEVECO_SDK_HOME
- Windows(PowerShell)：echo $env:DEVECO_SDK_HOME
  若为空，请在 DevEco Studio：File → Settings → SDK 中查看并复制路径。
写回 Flutter 配置：flutter config --ohos-sdk=<上一步得到的路径>

详细说明可参考项目内的环境配置。

四、检查环境

在终端执行：

bash 复制代码

flutter doctor

或查看详情：

bash 复制代码

flutter doctor -v

需要重点关注的两项：

Flutter ：应指向你配置的 Flutter-OH 目录，版本号带 ohos（如 3.35.8-ohos-0.0.x 或 3.27.x-ohos）
HarmonyOS toolchain ：应为 [✓]，若为 [!] 请根据提示检查 ohos-sdk 路径与 DevEco 安装

其他项（如 Android、iOS、Chrome）按需配置即可；若只做鸿蒙开发，只要 Flutter 与 HarmonyOS toolchain 正常即可继续。

示例输出（节选）：

text 复制代码

[✓] Flutter (Channel xxx, 3.35.8-ohos-0.0.2, ...)
[✓] HarmonyOS toolchain - develop for HarmonyOS devices

五、创建 Flutter-OH 工程

1. 创建应用工程

仅鸿蒙平台：

bash 复制代码

flutter create --platforms ohos <projectName>
cd <projectName>

多平台（Android + iOS + ohos）：

bash 复制代码

flutter create <projectName>
cd <projectName>

编译 HAP：

bash 复制代码

flutter build hap --debug

产物默认在：<projectName>/ohos/entry/build/default/outputs/default/entry-default-signed.hap（若已配置签名）。

2. 创建 Flutter-OH 插件工程

bash 复制代码

flutter create --org com.nutpi --template=plugin --platforms=android,ios,ohos <plugin_name>

若已有插件只想增加 ohos 支持，可在插件根目录执行：

bash 复制代码

flutter create . --template=plugin --platforms=ohos

并在 pubspec.yaml 中增加 ohos 平台配置（可参考 Flutter-OH 标准化适配流程或官方示例）。

3. 运行与调试

连接真机或启动鸿蒙模拟器，执行：flutter devices 确认设备已识别。
运行应用：flutter run -d <deviceId>。
需在真机安装 HAP 时，可使用：hdc -t <deviceId> install <hap 路径>。

签名需在 DevEco Studio 中打开项目的 ohos 目录，在 Project Structure → Signing Configs 中配置。

六、可选：适配已有 Flutter 三方库到鸿蒙

若你希望把 pub.dev 上已有插件适配到 Flutter-OH，可参考以下流程（团队协作时可与仓库管理员约定分支与评审流程）。

1. 确定要适配的库

在 pub.dev 找到目标库。
在 OpenHarmony Flutter 三方库清单中确认是否已有社区适配，避免重复劳动。

2. 获取代码并添加 ohos 平台

从管理员提供的 AtomGit 仓库 fork 到个人账号，clone 到本地（或按团队约定方式获取）。
在插件根目录执行：
flutter create . --template=plugin --platforms=ohos
在 pubspec.yaml 中增加 ohos 平台配置（如 platforms 与 plugin 的 ohos 项）。

3. 实现 ohos 端逻辑

参考该库的 Android 或 iOS 实现 ，在 ohos/ 下用 ArkTS 完成等价能力（Method Channel、FFI 等）。
可结合官方 OH 平台适配 Flutter 三方库指导与示例工程。

4. 本地验证

bash 复制代码

flutter pub get

使用 DevEco Studio 打开 example/ohos，配置签名、连接真机，运行：

bash 复制代码

flutter run

在真机上反复调试直至功能与预期一致。

5. 文档与提交

在仓库根目录新增 README.OpenHarmony_CN.md 与 README.OpenHarmony.md（中英文适配说明）。
提交变更（通常包括）：
ohos/、example/ohos/、README.OpenHarmony_CN.md、README.OpenHarmony.md、pubspec.yaml，以及若有改动的 lib/ 等。
推送到个人 fork，在 AtomGit 上创建 Pull Request，由管理员审核合并。

七、延伸学习与参考

八、小结：2026 年上车 Flutter-OH 的推荐顺序

步骤	做什么
1	选定版本：生产用 3.27.4-ohos 系列，学习用 oh-3.35.7-dev
2	安装 DevEco Studio，下载并配置 Flutter-OH SDK，配置 PATH 与 ohos-sdk
3	`flutter doctor` 确认 Flutter 与 HarmonyOS toolchain 正常
4	`flutter create --platforms ohos <projectName>` 创建工程并 `flutter build hap`
5	真机/模拟器运行 `flutter run`，按需在 DevEco 中配置签名与调试
6	有需要时再按「六」参与三方库适配与社区贡献

按上述顺序走通一遍，即可在 2026 年快速「上车」Flutter-OH，并在此基础上做应用开发或插件适配。