06. Flutter鸿蒙真机与模拟器调试：设备连接、签名、运行和日志查看

真机调试是 Flutter 鸿蒙开发的核心环节。只会写页面还不够，还要能识别设备、运行应用、安装 hap、查看日志，并能从日志里判断问题发生在 Flutter 层、鸿蒙构建层还是原生插件层。

设备连接

先开启设备开发者模式和调试授权，然后执行：

hdc list targets

能看到设备编号后，再执行：

flutter devices

两个命令都能识别设备，才说明调试链路比较完整。hdc 能识别但 flutter devices 不能识别时，优先检查 OpenHarmony Flutter SDK、环境变量和设备授权状态。

运行调试包

进入项目根目录：

flutter run --debug -d <deviceId>

运行过程中会经历依赖检查、Flutter 编译、鸿蒙工程构建、安装和启动。第一次运行慢是正常的，后续热重载会快很多。

常用调试按键：

r  热重载
R  热重启
q  退出运行

安装 release 包

构建：

flutter build hap --release

安装：

hdc -t <deviceId> install ohos/entry/build/default/outputs/default/entry-default-signed.hap

如果提示签名或安装失败，回到 DevEco Studio 检查签名配置、设备开发者模式和应用包名冲突。

查看日志

基础日志：

hdc shell hilog

日志很多时可以过滤：

hdc shell hilog | findstr Flutter
hdc shell hilog | findstr EntryAbility

也可以按官方 FAQ 的思路关闭全局日志，再打开自己的 domain：

hdc shell hilog -b X
hdc shell hilog -b D -D A00000

调试排错

常见情况：

现象	处理
hdc list targets 为空	检查数据线、授权、驱动、开发者模式
flutter devices 为空	检查 Flutter SDK 和 OpenHarmony doctor
debug 闪退 release 正常	清理缓存，检查 SDK 版本和日志
安装失败	检查签名、包名、旧版本残留
日志太多	用 hilog 过滤 Tag 或 domain

签名问题处理

调试阶段最常见的非代码问题就是签名。应用无法安装、安装后无法启动、debug 包行为异常，都可能和签名或设备开发者模式有关。处理顺序可以这样来：

1. 确认设备已经开启开发者模式
2. 确认 DevEco Studio 中签名配置可用
3. 清理旧应用后重新安装
4. 对比 debug 和 release 包行为

卸载旧应用时包名要以项目配置为准：

hdc uninstall com.example.hello_ohos
flutter run --debug -d <deviceId>

日志关键字

定位问题时可以重点搜索这些关键字：

Flutter
EntryAbility
MethodChannel
PlatformView
ProcessException
Exception
ERROR

例如：

hdc shell hilog | findstr EntryAbility
hdc shell hilog | findstr MethodChannel

如果是原生插件没有响应，先查插件是否注册，再查通道名称是否一致，最后查参数解析是否抛异常。

日志保存方式

调试复杂问题时可以把日志保存到文件：

hdc shell hilog > D:\flutter_ohos_workspace\logs\hilog.txt

也可以只保存 Flutter 相关内容：

hdc shell hilog | findstr Flutter > D:\flutter_ohos_workspace\logs\flutter_hilog.txt

日志文件比截图更适合搜索关键字。排查原生插件时，尤其要关注插件注册、方法名、参数解析、异常栈。

调试前后清理应用

包名冲突或旧版本残留时，可以先卸载旧应用，再重新安装。实际包名以项目配置为准：

hdc uninstall com.example.hello_ohos
flutter run --debug -d <deviceId>

如果 release 包能安装但 debug 包启动失败，重点检查 SDK 缓存、debug 签名和 Flutter OpenHarmony 版本。
bash
hdc uninstall com.example.hello_ohos
flutter run --debug -d

如果 release 包能安装但 debug 包启动失败，重点检查 SDK 缓存、debug 签名和 Flutter OpenHarmony 版本。