适合谁看

• 已经在鸿蒙真机上跑 Flutter 应用的开发者

• 想理解命令背后调用链的人

• 构建出错后想知道应该先查哪一层的人

问题背景

很多人第一次在鸿蒙真机上运行 Flutter 应用时，脑子里的模型还是：

• Flutter 编译

• 应用运行

这个模型对 Android 或 iOS 入门阶段还勉强够用。
但到了鸿蒙 Flutter 项目里，它就太粗了。

因为这条运行链路背后至少同时牵涉：

• 设备匹配

• Flutter 工具链

• HarmonyOS 壳工程

• 模块配置

• Hvigor 构建系统

• 签名与设备安装

所以一旦报错，真正困难的从来不是“命令忘了怎么写”，而是：

出问题的到底是哪一层。

项目中的真实场景

你这次给出的真实输出其实已经说明了一个很关键的事实：

• ohos 不是当前 Flutter 直接可匹配的设备 id

• 设备列表里真正能用的是像 2LQ0224125001188 这样的具体设备 id

• 平台列里会显示 ohos-arm64

也就是说，日常真正更稳的做法通常是：

flutter devices
flutter run -d 2LQ0224125001188

或者在你自己的机器上，把上面的 id 换成 flutter devices 输出的那一项。

食界探味当前的工程正好能把后续链路对应得很清楚：

• Flutter 主体代码在 app/lib/

• HarmonyOS 壳工程在 app/ohos/

• 根构建配置在 app/ohos/build-profile.json5

• Stage 模块配置在 app/ohos/entry/build-profile.json5

• 模块声明在 app/ohos/entry/src/main/module.json5

• 构建脚本在 app/ohos/hvigorfile.ts 和 app/ohos/entry/hvigorfile.ts

• 启动入口在 app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

换句话说，Flutter 在鸿蒙设备上运行，最终不是直接“跑 Dart”，而是把 Flutter 和鸿蒙壳工程一起串起来。

核心实现

先给一个更接近真实情况的理解：

flutter devices
-> 发现可用鸿蒙设备 id
flutter run -d <device-id>
-> Flutter 匹配目标设备
-> 检查 Flutter SDK 和项目依赖
-> 准备 Flutter 产物
-> 调起 HarmonyOS 壳工程构建
-> 读取 Hvigor、模块和签名配置
-> 生成并安装应用
-> 拉起 EntryAbility
-> 再由壳工程承接 Flutter 页面

只要先把这条链路想清楚，后面很多报错就不会再只会“盯着 run 命令本身”。

一、第一步并不是编译，而是设备匹配

真正的第一步不是编译，而是“你到底指定了哪个设备”。
也就是说，这一步不是“我要不要跑鸿蒙”，而是：

• 当前有没有可用的鸿蒙设备

• Flutter 能不能识别这台设备

• 你传给 -d 的值是不是设备列表里真实存在的 id 或 name

• 本机 Flutter SDK 和 HarmonyOS SDK 环境是否能对上

在食界探味的壳工程里，这一步至少和下面这个文件间接相关：

• app/ohos/local.properties

因为这里记录了：

• hwsdk.dir

• flutter.sdk

如果 SDK 路径不对，或者你传给 -d 的参数根本不是 Flutter 识别到的设备 id，后面很多看起来像“构建失败”的问题，其实在最开始就已经埋下了。

这也是为什么你这次实际看到的是：

• No supported devices found with name or id matching 'ohos'

但设备列表下面又明确出现了一台：

• 2LQ0224125001188 • ohos-arm64 • Ohos OpenHarmony-6.1.0.115 (API 23)

这类输出说明的不是“没有鸿蒙设备”，而是“命令里的设备匹配值写错了”。

二、第二步是 Flutter 侧准备应用主体

接下来 Flutter 仍然会做它熟悉的那一部分工作：

• 识别 Dart 工程

• 读取 pubspec.yaml

• 组织 Flutter 产物

• 准备应用主体运行所需内容

这一层主要还是围绕：

• app/lib/

• pubspec.yaml

• Flutter 侧依赖

所以如果问题落在 Dart 代码、Flutter 页面、Flutter 插件调用入口这边，通常会在这个阶段暴露得更明显。

三、第三步开始真正进入鸿蒙壳工程

这是鸿蒙 Flutter 项目和普通 Flutter 项目开始明显分叉的地方。

到了这里，命令已经不再只是“Flutter 自己跑”，而是要真正依赖：

• app/ohos/

• app/ohos/entry/

• app/ohos/entry/src/main/module.json5

也就是说，Flutter 主体只是应用的一部分，真正能不能在鸿蒙侧成立，还要看壳工程是否完整、模块是否正确。

在这个阶段，module.json5 很关键，因为它决定的是：

• 主入口是谁

• 模块有哪些 Ability

• 扩展能力有没有声明

• 权限是否完整

四、第四步不是单纯构建，而是会经过 Hvigor

很多人看到 flutter run，下意识会把整条链路都理解成 Flutter 自己完成。
但在鸿蒙工程里，真正的模块构建还会经过：

• app/ohos/hvigorfile.ts

• app/ohos/entry/hvigorfile.ts

在食界探味里：

• 根 hvigorfile.ts 接入了 flutter-hvigor-plugin

• entry/hvigorfile.ts 负责模块级 hapTasks

这意味着 Flutter 命令并不是跳过了鸿蒙构建系统，而是把它调了起来。
所以一旦问题出在构建脚本、模块任务、工程组织层，单看 Dart 日志通常是不够的。

五、第五步会带上构建目标和签名配置一起参与

在食界探味里，这一步最直接相关的就是：

• app/ohos/build-profile.json5

• app/ohos/entry/build-profile.json5

根 build-profile.json5 更关心：

• signingConfigs

• products

• modules

• targetSdkVersion

• compatibleSdkVersion

entry/build-profile.json5 更关心：

• 当前模块工作在 stageMode

• 有哪些 targets

这就意味着，真正运行到这里时，很多看似“运行失败”的问题，实际可能已经变成：

• 签名问题

• SDK 版本问题

• 模块挂载问题

• 构建目标问题

六、第六步是生成、安装并交给系统启动

如果前面的构建链路都顺利，系统接到的也不是一个抽象的 Flutter 页面，而是一个已经完成鸿蒙模块打包和签名的产物。

这一段真正关心的是：

• 应用能不能被设备接受

• 安装链路是否顺利

• 系统能不能拉起模块主入口

也就是说，生成成功不等于安装成功，安装成功也不等于入口成功。

七、第七步真正被拉起的是 EntryAbility

如果前面的构建和安装都顺利，最后真正被系统拉起的，不是一个抽象的 Flutter 页面，而是模块声明里的入口 Ability。

在食界探味里，这个角色就是：

• app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

这意味着从系统视角看，最后被启动的是：

• HarmonyOS 模块

• EntryAbility

• 再由它挂起 Flutter 引擎与页面容器

所以这条链路的终点不是“Dart main 函数”，而是“鸿蒙入口成功承接 Flutter 主体”。

八、为什么出错时不能只盯着 Flutter

这也是这篇最关键的一点。

很多人会先写成下面这种口语化形式：

flutter run -d ohos

但结合你这次的真实输出，更准确的写法应该是：

flutter devices
flutter run -d <device-id>

这时再继续讨论后续构建和安装链路才是准确的。
否则连设备都没匹配上，后面的壳工程、Hvigor、签名配置根本还没开始发挥作用。

很多人一旦看到 run 命令报错，就会天然认为：

• 报错 = Flutter 报错

但回到前面的链路就会发现，实际至少还有这些可能：

• 设备匹配参数写错

• Flutter 业务代码有问题

• 平台边界调用有问题

• module.json5 入口或权限声明有问题

• build-profile.json5 构建或签名配置有问题

• Hvigor 构建链路有问题

• 设备安装链路有问题

所以真正实用的做法不是“盯着命令”，而是先做问题分流。

九、最实用的分流思路

遇到 Flutter 在鸿蒙设备上运行失败时，我更建议先按这几类去分：

第零步：先判断是不是设备匹配就没过

• flutter devices 里有没有鸿蒙设备

• -d 后面传的是不是设备真实 id

• 设备明明存在，但你传的是平台名或口语化别名

如果卡在这一步，先不要急着查壳工程，因为命令甚至还没准确进入构建链路。

更像 Flutter 层的问题

• Dart 编译错误

• 页面或状态层错误

• Flutter 侧 channel 调用错误

更像鸿蒙壳工程层的问题

• module.json5 入口与权限问题

• build-profile.json5 签名、产品、SDK 问题

• ArkTS 入口或插件问题

更像构建链路层的问题

• hvigorfile.ts 相关构建问题

• SDK 路径问题

• 构建目标或模块映射问题

更像设备或安装层的问题

• 安装不上

• 启动不了

• 设备不识别

只要先把这一层分清，后面的排查效率会高很多。

十、开发期最好先建立哪种排查顺序

如果你只是想让命令尽快跑通，我建议按下面这条顺序排查：

1. 先跑 flutter devices，确认鸿蒙设备真实 id

2. 再用 flutter run -d <device-id>，不要直接把 ohos 当成固定别名

3. 再确认设备和 SDK 环境有没有被识别

4. 再确认 Flutter 侧是不是已经存在编译错误

5. 再看 app/ohos/ 下的 module.json5 和 build-profile.json5

6. 如果报错明显靠近构建链，就检查 hvigorfile.ts 和 local.properties

7. 最后再回到 EntryAbility.ets 这类入口代码看启动承接是否有问题

这样做的好处是，你能更快判断失败点是在设备匹配、壳工程配置、构建链路，还是最终入口阶段。

关键代码位置

• app/lib/

• app/ohos/

• app/ohos/local.properties

• app/ohos/build-profile.json5

• app/ohos/entry/build-profile.json5

• app/ohos/hvigorfile.ts

• app/ohos/entry/hvigorfile.ts

• app/ohos/entry/src/main/module.json5

• app/ohos/entry/src/main/ets/entryability/EntryAbility.ets

鸿蒙侧实现

从鸿蒙侧看，设备、模块、权限、签名、构建系统都会直接影响最终运行。
所以 Flutter 在鸿蒙设备上运行，虽然最终仍由 Flutter 命令触发，但真正落地时会深度依赖鸿蒙壳工程。

更具体地说，它至少依赖三层：

• 模块声明层：module.json5

• 构建与签名层：build-profile.json5

• 构建执行层：Hvigor 脚本和本地 SDK 配置

Flutter 侧实现

从 Flutter 侧看，这条运行链路的价值在于把：

• Flutter 应用主体

• 平台边界层

• Ohos 壳工程

串成一条可运行链路。
但也正因为它串起来的层太多，所以失败时更要主动分流。

常见坑

• 把 ohos 当成可直接执行的固定设备 id

• 看到 flutter run 就默认是 Flutter 层问题

• 不区分设备匹配失败、构建失败、安装失败

• 没意识到 EntryAbility 才是鸿蒙侧真正的启动落点

• 一旦报错就先改页面层代码，而不是先判断链路卡在哪

• 完全忽略 local.properties、Hvigor 脚本和签名配置这几层

可复用模板

Flutter 在鸿蒙设备上的运行链路
1. flutter devices 发现可用设备
2. flutter run -d <device-id> 匹配目标设备
3. 准备 Flutter 产物
4. 调起 Ohos 壳工程构建
5. 读取 Hvigor、模块与签名配置
6. 安装到设备
7. 拉起 EntryAbility
8. 再由壳工程承接 Flutter 页面

排查顺序
1. 先判断是不是设备 id 就没匹配上
2. 再判断是 Flutter 问题还是壳工程问题
3. 再判断是构建问题、安装问题还是入口问题
4. 构建层问题别忘了看 Hvigor 和 local.properties

本篇总结

这篇最该先改正的地方，其实就是一个非常基础但非常关键的认知：
在你当前这套环境里，真正执行时不应该把 ohos 当成固定设备参数，而应该先通过 flutter devices 取到真实设备 id。

只要把“设备匹配、Flutter、壳工程、Hvigor、签名、入口”这条链路先想清楚，后面无论是设备匹配失败、构建失败还是运行失败，都不会再只会从 Flutter 一个方向死磕。