开篇

前提条件，我之前说过这个插件：Joyous Harmony Runner，没有安装的请先安装一个，之前有做过简单的功能介绍。

目前在Android Studio，如果安装了侧链 Harmony版本的Flutter后，只能在命令行中编译，安装应用；没办法在真机上Debug。只在命令行中安装和启动还不够，真正开发时需要断点、暂停、继续、Step、调用栈和变量查看。

Joyous Harmony Runner 的 Debug Session 它的一个明确目标：让 Harmony Flutter 的 Dart 调试接入 Android Studio 原生 Debug Tool Window，说白了就是可以直接debug鸿蒙真机，彻底告别爹(flutter)不疼妈(harmony)不爱的阶段。

Debug 前先过 Harmony Doctor

真正开始 Debug 前，建议先点一次 Runner 顶部的 Doctor。Harmony Flutter 调试不是只要有一台手机就行，它至少要同时满足几件事：

• 当前项目能识别出 pubspec.yaml 和 ohos/entry。
• Flutter Harmony SDK 路径正确。
• Harmony SDK、hdc、ohpm 能被找到。
• 真机已经连接并授权。
• 应用具备可安装到真机的签名配置。

Doctor 的作用就是把这些前置条件一次性检查出来。这样 Debug 按钮失败时，不会只看到一段命令行错误，而是能知道到底是 SDK、设备、签名，还是项目结构的问题。

如果缺少签名，需要先回到 DevEco

Harmony 真机安装和 Debug 都绕不开签名。Runner 不会自动生成、修改或托管你的证书和 Profile，这部分仍然应该交给 DevEco Studio。

当 Doctor 检查到当前项目缺少签名配置，并且已经连接了真机时，Runner 会弹出签名引导。这个引导不是让你看一堆文字，而是告诉你接下来在 DevEco 里要做的关键路径：

1. 保持 Harmony 真机已连接。
2. 打开当前 ohos/ 壳工程到 DevEco Studio。
3. 进入 Signing Configs。
4. 勾选自动生成签名。
5. 完成后关闭 DevEco，回到 Android Studio 重新运行 Doctor 或 Debug。

打开 DevEco 后，重点看 Project Structure 里的 Signing Configs 页。对于普通调试场景，通常要确认 default 配置存在，并且 Automatically generate signature 已经开启。

这一步完成后，回到 Android Studio 再点 Doctor。如果签名、设备和 SDK 都通过，Debug 才有机会进入真正的 Dart VM Service 调试流程。

为什么可以调试 Dart

Flutter 的 Dart 调试依赖 Dart VM Service。Runner 启动 Debug 时，会通过 Harmony Flutter 工具链执行类似下面的流程：

flutter run --machine --start-paused

--machine 会输出结构化事件。Runner 从这些事件里捕获 VM Service 地址，然后把它交给 Android Studio / Dart 插件的原生 Debug 能力。

这意味着 Runner 不自绘调试器，也不重新实现 Dart 调试协议，而是把 Harmony Flutter 运行起来以后，接入 IDE 已有的 Dart Debug Session。

Debug 按钮做了什么

点击 Debug 后，Runner 会按顺序处理：

1. 识别当前项目。
2. 选择当前 HarmonyOS 设备。
3. 启动 Harmony Flutter debug 运行流程。
4. 捕获 Dart VM Service。
5. 启动 Android Studio 原生 Debug Session。
6. 把断点、暂停、继续、Step、变量和调用栈交给 IDE 原生 Debug UI。

断点和 Step

当 main.dart 中的 Dart 断点命中后，可以使用 Android Studio 原生 Debug 工具栏：

• Pause
• Resume
• Step Over
• Step Into
• Step Out
• Stop

这些按钮来自 IDE 原生 Debug Tool Window。Runner 的职责是启动和连接正确的调试会话，避免出现“断点能停，但 Step 工具栏不完整”的问题。

变量和调用栈

断点命中后，可以在 Debug 面板中查看：

• Variables
• Frames
• 当前 Dart 调用栈
• 当前作用域变量

这部分能力同样依赖 Dart 插件和 VM Service。Runner 不复制这些 UI，而是让 Harmony Flutter 运行结果进入 Android Studio 已有调试体验。

明确边界：不是 ETS / ArkTS 运行时调试

当前 Debug Session MVP 支持的是 Dart 调试，不是 ETS / ArkTS runtime breakpoint。

Runner 已经支持 .ets / .arkts 文件类型、语法高亮、注释、括号匹配和 Color Scheme 自定义，但 ETS / ArkTS 运行时断点命中需要 DevEco / ArkTS 调试协议能力验证，不在当前首发版本承诺范围内。

使用结论

Joyous Harmony Runner 的 Debug MVP 解决的是 Flutter 开发者最核心的调试链路：把 Harmony Flutter 应用安装并启动到真机，然后接入 Dart VM Service，让 Android Studio 原生 Debug 面板继续工作。

只要 Dart 断点、Step、变量和调用栈能在 Android Studio 里正常使用，Harmony Flutter 的日常开发体验就已经从“能跑”进入到“能调”。