Flutter 转 HarmonyOS（1）：Windows 从零搭建 Flutter-OH 3.41，跑通第一个 HAP

先给结论： Flutter 项目迁移到 HarmonyOS，不是把 APK、AAB 或 Android 工程“转换”为 HAP。本文使用的是社区维护的 Flutter-OH 适配链路：尽量复用 Dart 与 Flutter UI，再为 OpenHarmony/HarmonyOS 工具链补齐平台工程、插件、权限、签名和真机验证。

这篇文章以 GitCode 上的《鸿蒙版 Flutter 环境 3.35 版本搭建指南》为原始资料，但没有原样照抄。该文件名写 3.35，正文标题仍是 3.32 / Mac 版，示例使用已经迁移的旧仓库与 3.35.7-dev 开发分支。为了让 Windows 小白今天仍能复现，本文保留它的“DevEco Studio → Flutter-OH → doctor”主线，把仓库入口、稳定版本、Windows 路径、签名、设备运行和 HAP 验收更新到 2026 年 7 月 31 日可核对的一手资料。

本文不会承诺你的旧项目“一次编译就成功”。我能给你的，是一条可以逐步判断问题属于环境、签名、设备、插件还是业务代码的最小闭环。

先把最重要的事实讲清楚

截至本文校对日期，Flutter 官方的支持平台列表列出了 Android、iOS、Windows、macOS、Linux 和 Web，没有列出 HarmonyOS。

因此，下面三句话必须分开：

Flutter 官方支持 HarmonyOS：当前不能这样说。
社区提供了 Flutter 对 OpenHarmony/HarmonyOS 工具链的适配：可以这样说，入口是 CPF-Flutter/flutter_flutter。
某个 Flutter 应用一定能低成本迁移并上架：不能提前承诺，要看插件、原生代码、系统能力和真机结果。

Flutter-OH 仓库已经迁移到 CPF-Flutter 组织，旧仓库不再作为维护入口。更容易踩坑的是：新仓库当前默认 HEAD 仍指向较旧的 br_3.27.4-ohos-1.0.4。如果新手只执行不带版本的 git clone，拿到的未必是应该用于新项目的版本。

本文固定使用当日查到的最新非 Beta/Canary 稳定标签：

3.41.10-ohos-1.0.0

版本会继续变化。以后阅读本文时，先到仓库的 Tags 与版本规划确认稳定版本，不要把“数字最大”等同于“最适合你的插件组合”。

这条路线适不适合你

先做 3 分钟适用性自测

主要业务是否写在 Dart 中，而不是 Android Java/Kotlin 中？
UI 是否主要由 Flutter Widget 渲染？
你是否已经列出相机、定位、推送、支付、登录、WebView 等插件？
关键插件是否能在 Flutter-OH 三方库适配表中找到？
应用是否强依赖 Google Play Services、Firebase 原生能力或仅 Android SDK？
你是否有可用于最终验收的 HarmonyOS/OpenHarmony 设备？

前两项为“是”、第 4 项有答案、且第 5 项为“否”，通常适合先做 Flutter-OH 试点。插件很多、原生代码很多或强依赖 GMS 时，应先迁移一个关键流程，再决定继续 Flutter-OH、混合开发还是 ArkTS/ArkUI 原生重写。

一个实际项目可以先按下表分类：

分类	典型内容	处理方式
通常可复用，但仍要构建验证	纯 Dart 模型、算法、JSON 解析、业务规则、普通 Widget、主题、纯 Dart 状态层	先原样接入，再跑分析、测试与设备验证
需要适配	原生插件、Platform 分支、MethodChannel、权限、图标、启动页、签名、bundleName、生命周期	查适配版本；没有就替换或实现 OHOS 端
不可直接复用	Java/Kotlin、Gradle、AndroidManifest、APK/AAB、Android-only 插件、GMS 原生能力	改用 HarmonyOS 能力、社区插件或重写
必须真机验证	相机、相册、定位、通知、推送、支付、登录、WebView、后台任务、文件路径、输入法、旋转、无障碍、性能	模拟器通过不算完成

完成这篇后，什么才算“跑通”

不要用“DevEco Studio 能打开目录”当成功标准。至少要看到以下证据：

flutter --version 显示你固定的 Flutter-OH 版本，而不是电脑里另一个官方 Flutter。
flutter doctor -v 的 Flutter 与 HarmonyOS/OpenHarmony 工具链不再报阻塞错误。
flutter devices 能看到你准备使用的设备或当前版本确实支持的模拟器。
最小工程能通过 flutter run --debug -d <deviceId> 启动。
flutter build hap --debug 成功，并实际找到生成的 .hap 文件。
DevEco Studio 的签名配置与当前包名、团队和设备匹配。

验证边界： 本文核对了当日仓库 refs、README、Flutter 官方平台列表、Flutter-OH 环境/构建文档和华为工具文档；它不是对你的电脑、账号、模拟器或真机做过的现场证明。版本、SDK 与设备组合仍需以你执行命令后的真实输出为准。

第 0 步：先准备一个不会互相污染的目录

Windows 下建议把 SDK 与项目放在短路径，避免 Flutter Engine 仓库的深层目录触发路径过长。

D:\dev\flutter-ohos
D:\work\hello_ohos

不要把 Flutter-OH 覆盖到你正在用于 Android/iOS 生产项目的官方 Flutter SDK 目录。两套 SDK 分开，切换时先用 where.exe flutter 确认当前命令到底来自哪里。

需要准备：

Windows 10/11 64 位。
Git。
JDK 17。
DevEco Studio 与匹配的 HarmonyOS/OpenHarmony SDK。
至少约 100GB 可用磁盘空间。华为当前 DevEco Studio 页面对 Windows 还给出了 16GB 及以上内存的建议。
可用于最终验收的设备；没有设备时可先确认所选 Flutter-OH 版本、主机架构与 DevEco 模拟器的支持组合。

先逐个验证基础命令，而不是一次配置十个变量后猜哪一个错了：

git --version
java -version
where.exe git
where.exe java

预期：Git 能显示版本；Java 应为 17 系列；where.exe 返回的路径与你刚安装的位置一致。

第 1 步：安装 DevEco Studio 和 SDK

从华为官方 DevEco Studio 页面下载安装。首次启动后，让 IDE 完成 SDK、Node、ohpm、Hvigor 与 toolchains 的下载。

安装完成后，先找到实际目录。不同版本和自定义安装位置可能不同，下面只是结构示意：

C:\Program Files\Huawei\DevEco Studio
├─ sdk
└─ tools
   ├─ node
   ├─ ohpm\bin
   └─ hvigor\bin

不要直接复制示例路径。用资源管理器确认你自己的 sdk、ohpm、hvigor 和 node 确实存在。

第 2 步：下载并锁定 Flutter-OH 稳定标签

在 PowerShell 执行：

git clone --branch 3.41.10-ohos-1.0.0 --depth 1 https://gitcode.com/CPF-Flutter/flutter_flutter.git D:\dev\flutter-ohos

这里有三个关键点：

--branch 明确固定标签，不使用默认旧分支。
--depth 1 只拉取当前快照，减少第一次下载量。
D:\dev\flutter-ohos 路径短、无中文、无空格，能减少 Windows 路径问题。

如果提示文件名过长，先确认目录足够短。仍失败时再了解并启用 Windows/Git 长路径支持，不要为了一个报错随意修改整个系统后继续盲跑。

当前 PowerShell 会话中，先临时把它放到 PATH 最前面：

$env:Path = "D:\dev\flutter-ohos\bin;$env:Path"

where.exe flutter
flutter --version

预期：where.exe flutter 的第一条是 D:\dev\flutter-ohos\bin\flutter.bat；版本输出包含 Flutter-OH 对应版本。不是这个路径，就先停止，不要继续。

第 3 步：用临时变量验证工具链

先在当前 PowerShell 窗口临时配置。确认全部通过后，再通过“系统属性 → 环境变量”保存，排错会简单很多。

请把下面两个路径改成你的真实位置：

$env:JAVA_HOME = "C:\Program Files\Java\jdk-17"
$env:TOOL_HOME = "C:\Program Files\Huawei\DevEco Studio"
$env:DEVECO_SDK_HOME = "$env:TOOL_HOME\sdk"

$env:Path = "$env:JAVA_HOME\bin;$env:TOOL_HOME\tools\node;$env:TOOL_HOME\tools\ohpm\bin;$env:TOOL_HOME\tools\hvigor\bin;D:\dev\flutter-ohos\bin;$env:Path"

flutter config --ohos-sdk "$env:DEVECO_SDK_HOME"

注意：

变量名是 JAVA_HOME，不是 JAVA-HOME。
JAVA_HOME 指向 JDK 根目录，不是 bin 目录。
HOST_FLUTTER 不是这条流程要求的标准变量，不需要照搬旧教程。
Flutter-OH 源码会识别 DEVECO_SDK_HOME、HOS_SDK_HOME 等位置；对新手而言，显式执行 flutter config --ohos-sdk 更容易检查。

逐项确认命令来源：

where.exe java
where.exe node
where.exe ohpm
where.exe hvigorw
where.exe hdc
where.exe flutter

java -version
node --version
flutter --version
flutter doctor -v

flutter doctor -v 是这一步的验收口，不是装饰命令。看到 [!] 或 [✗] 时，只处理它指出的那一层：

找不到 SDK：再次确认 flutter config --ohos-sdk 的目录中确实有 SDK 内容。
找不到 JDK：检查 JAVA_HOME 和 where.exe java。
找不到 ohpm/Hvigor/Node：检查 DevEco 的 tools 子目录是否存在，以及 PATH 是否加对层级。
Flutter 版本不对：先处理 PATH 顺序。

第 4 步：创建最小工程

不要直接拿复杂旧项目当环境测试。先创建只含 OHOS 平台的最小应用：

New-Item -ItemType Directory -Force D:\work | Out-Null
Set-Location D:\work

flutter create --platforms ohos --org cloud.adcaing hello_ohos
Set-Location .\hello_ohos
flutter pub get

预期至少出现：

hello_ohos
├─ lib
│  └─ main.dart
├─ pubspec.yaml
└─ ohos

如果没有 ohos 目录，先回头确认你调用的是 Flutter-OH SDK，而不是继续手工创建文件夹。

第 5 步：在 DevEco Studio 配置签名

用 DevEco Studio 打开 D:\work\hello_ohos\ohos，不是打开整个 Flutter 根目录。

根据当前 Flutter-OH 构建文档，进入项目签名配置，为工程选择与账号、团队和 bundleName 匹配的签名。华为的开发入门说明明确区分了预览/模拟器与真机：真机安装运行需要有效签名，证书与 Profile 共同约束应用。

这一步要检查：

DevEco Studio 已登录正确的华为开发者账号。
签名配置绑定到当前 product。
bundleName 没有和另一个应用冲突。
证书与 Profile 未过期，且设备/团队范围正确。
保存后让工程同步结束，不要在同步中途开始 Flutter 构建。

不要使用“关闭签名校验”作为通用解法。 它掩盖的是证书、Profile、包名或设备授权问题，不能代表可发布状态。

第 6 步：发现设备并运行

先让 hdc 看见设备，再让 Flutter 看见它：

hdc list targets
flutter devices

如果出现设备 ID，直接运行：

flutter run --debug -d <deviceId>

flutter run 本身会执行所需构建，不要求你固定“先 build 再 run”。首次运行时间较长很常见，但终端必须继续有下载、编译或安装输出；长时间完全无输出时才按网络、依赖或 Hvigor 层排查。

设备列表为空时，按顺序检查：

设备是否打开开发者模式。
USB 连接模式是否正确，设备是否弹出并接受调试授权。
where.exe hdc 是否指向当前 DevEco SDK。
hdc list targets 是否先能看到设备。
模拟器是否真的支持你选择的 Flutter-OH 版本、主机系统和 CPU 架构。

社区不同版本的文档对模拟器支持范围曾出现差异，所以本文不把“Windows 一定能用某个模拟器”写成恒定事实。真实项目最终仍以真机为验收基线。

第 7 步：单独构建并找到 HAP

运行成功后，再验证可重复构建：

flutter build hap --debug

社区文档在不同版本中出现过不完全相同的产物路径写法，不要把旧文章里的路径当永远不变。先看本次 CLI 末尾打印的真实路径，再用 PowerShell 搜索：

Get-ChildItem .\ohos\entry\build -Recurse -Filter *.hap

如需用 hdc 单独安装：

hdc -t <deviceId> install <实际的HAP完整路径>

华为官方也提供了 HAP 安装与 hdc 命令说明。安装完成只证明包可安装，不证明插件、权限、后台任务或发布审核已经通过。

第 8 步：再把现有 Flutter 项目接进来

最小工程全部通过后，回到真实项目。先建立可恢复的 Git 基线：

Set-Location D:\work\your_flutter_app

git status --short
git switch -c feat/flutter-ohos
git add -A
git commit -m "chore: baseline before Flutter-OH migration"

确认当前仍是 Flutter-OH SDK：

where.exe flutter
flutter --version

然后在项目根目录生成 OHOS 平台工程：

flutter create --platforms ohos .
flutter clean
flutter pub get

如果项目已经有 ohos 目录，不要直接覆盖。先在临时副本中重新生成，比较 ohos 目录里的签名、权限、bundleName、依赖和自定义原生代码，再决定合并方式。

接着跑最便宜的检查：

flutter analyze
flutter test
flutter build hap --debug

没有测试时，flutter test 可能没有可执行用例；这不等于业务已验证。至少保留 analyze、构建和关键流程的设备检查。

第 9 步：逐项审计依赖，不要批量祈祷

先导出依赖：

flutter pub deps --style=compact | Out-File -Encoding utf8 .\flutter-dependencies.txt

打开 pubspec.yaml 与依赖清单，逐项查询 CPF-Flutter 三方库适配表。

给每个包标记四种状态：

状态	判断方法	下一步
可复用	纯 Dart，无原生平台实现	固定版本后构建与回归
已有 OHOS 适配	适配表或包仓库明确给出 OHOS 实现	使用指定版本/Tag，检查示例与 issue
可替换	当前包无适配，但同能力有维护中的替代包	先做最小替换实验
阻塞	关键能力无适配，且不能降级	自研插件、混合开发或原生重写

“适配表里有”也不是最终结论。继续确认：

对应 Flutter-OH 大版本是否兼容。
最近一次提交与 issue 是否仍在维护。
Debug 与 Release 是否都能构建。
权限拒绝、后台恢复、冷启动和弱网是否正常。
真机架构是否覆盖你的目标设备。

第 10 步：处理平台判断和原生通道

旧代码里常见：

if (Platform.isAndroid) {
  // Android-only behavior
}

在 Flutter-OH 社区 fork 中，运行系统标识使用 ohos。应用侧可在非 Web 的 dart:io 场景显式判断：

import 'dart:io';

final bool isOhos = Platform.operatingSystem == 'ohos';

不要简单把所有 Platform.isAndroid 改成 “Android 或 OHOS”。先问这段逻辑属于：

纯业务差异：可能可以共用。
文件路径、权限、通知、后台或窗口行为：必须按 HarmonyOS 语义重新实现。
Android 原生 SDK：不能因为条件成立就复用。

MethodChannel 的 Dart 接口可能保留，但 Android 端的 Java/Kotlin 实现不会自动变成 OHOS 实现。你需要：

查找已有 OHOS 插件。
没有时，在插件的 OHOS 平台目录实现对应能力。
用 ArkTS/HarmonyOS API 处理权限、生命周期和系统服务。
为成功、拒绝、取消、超时和不可用状态定义统一返回值。

第 11 步：权限、资源与系统能力重新核对

Android 的 AndroidManifest.xml、Gradle、APK/AAB、Java/Kotlin 代码不能直接作为 HAP 的平台配置。至少重新检查：

ohos/entry/src/main/module.json5 中的权限与 ability 配置。
应用图标、启动页和多层图标资源。
bundleName、版本号、签名 product。
网络、文件、相机、定位、通知等权限。
用户拒绝权限后的可用路径，而不只是“申请成功”。
隐私政策、权限用途说明和应用市场要求。

Flutter 页面能显示，只证明渲染链路开始工作。平台能力正确，才算迁移开始成立。

常见错误：按层定位

1. `flutter`、`ohpm`、`hvigorw` 或 `hdc` 找不到

根因通常是 PATH 层级或终端未刷新。先用 where.exe <命令>，确认文件真实存在，再关闭并重新打开 PowerShell。不要连续追加多个猜测路径。

2. doctor 提示找不到 HarmonyOS/OpenHarmony SDK

重新确认：

flutter config --ohos-sdk "C:\你的DevEco Studio\sdk"
flutter doctor -v

路径必须是实际 SDK 根目录，不是 DevEco 安装包、下载目录或某一个 toolchains 子目录。

3. Hvigor 提示需要 `.npmrc`

在确认公司代理和网络策略后，可按 Flutter-OH 项目 FAQ 在当前用户目录创建 .npmrc：

registry=https://repo.huaweicloud.com/repository/npm/
@ohos:registry=https://repo.harmonyos.com/npm/

如果你在企业网络或已有私有 registry，不要直接覆盖原配置；先合并并记录变更。

4. 切换 Flutter SDK 后出现 snapshot/version mismatch

先确认 where.exe flutter。Flutter-OH 与官方 Flutter 使用独立 SDK 目录，不要共享一个被反复覆盖的 bin\cache。确认路径后，对当前项目执行：

flutter clean
flutter pub get

仍然报错时，只清理你已确认的 Flutter-OH SDK 缓存，不要用模糊变量或递归命令删除整个开发目录。

5. HAP 签名校验失败

回到 DevEco Studio 检查证书、Profile、bundleName、团队、product 和设备授权。Debug 包能装不等于 Release 签名可上架；不要把关闭校验当修复。

6. 插件显示 “MissingPlugin” 或能力无响应

这通常不是 Dart UI 问题，而是插件没有注册 OHOS 实现、版本不匹配，或 MethodChannel 名称/参数不一致。先用一个最小页面只调用该插件，确认问题后再回到完整应用。

真机验收清单

至少把下面项目逐个记录为“通过 / 失败 / 未验证”：

首次安装、覆盖安装、卸载重装。
冷启动、热启动、前后台切换、系统回收后恢复。
返回键、手势返回、路由栈和弹窗关闭。
中文输入法、软键盘顶起、横竖屏与不同字号。
网络断开、弱网、超时、服务端错误。
权限首次申请、拒绝、永久拒绝、设置页恢复。
相机、相册、定位、通知、推送、支付、登录。
WebView、PlatformView、文件选择与分享。
Release HAP，而不只是 Debug。
内存、启动时间、长列表、动画和图片加载。
无障碍读屏、焦点顺序和动态字体。

模拟器适合提早发现布局和基础构建问题，不能替代真机的硬件、权限、性能与系统服务验证。

构建成功之后，离上架还有多远

flutter build hap --release 成功，只说明生成了 Release 产物。面向应用市场还需要：

正式签名与正确 bundleName。
目标 API、版本号与兼容设备范围。
隐私政策、权限用途和数据处理说明。
图标、截图、应用介绍与分类材料。
登录、支付、推送等生产配置。
功能、稳定性、功耗、安全与兼容性自测。
AppGallery Connect 的创建、上传、审核与问题整改。

所以不要把“Flutter 项目已迁移”定义为“首页能打开”。更可靠的定义是：关键业务在目标真机的 Release 包中通过，平台能力有拒绝与异常路径，发布材料和审核约束也完成核对。

最后给小白的执行顺序

用短路径安装两套互不覆盖的 Flutter SDK。
固定 Flutter-OH 稳定 Tag，不用默认分支。
逐项验证 JDK、DevEco SDK、Node、ohpm、Hvigor、hdc。
让 flutter doctor -v 先通过。
创建只含 OHOS 的最小项目。
配好签名，跑通一个设备。
构建并实际找到 Debug HAP。
给旧项目建立 Git 基线，再生成 ohos 平台。
按“可复用 / 已适配 / 可替换 / 阻塞”审计每个插件。
最后才做完整业务、Release、真机和上架验收。

这条顺序看起来慢，实际更快：每一步只有一个主要变量，出错时你知道该回到哪一层。

一手资料与继续阅读

Flutter and the related logo are trademarks of Google LLC. 本文与 Google LLC 无隶属或背书关系；HarmonyOS 为其权利人商标。文中的 Flutter-OH 指社区适配项目。