远程真机跑通不等于产品验收：HarmonyOS 云调试的证据边界

本地模拟器能进入首页，发布包却在目标机型启动后停在空白页；或者页面运行正常，但蓝牙灯牌始终连不上。遇到这种情况，云调试很有用：它让开发者在没有对应实体设备时，先把安装、启动、页面操作和日志采集跑通。然而，远程真机上的一次成功并不能替代真实外设、弱网、相机和长时间运行的验收。

本文以跨平台应援灯牌控制应用的发布前验证为线索，建立一条可复现的“选择设备—核对包—执行操作—保存证据—判断是否过关”的链路。参考工程当前是 Flutter + OpenHarmony API 20 的基础工程；没有云调试会话、API 26 构建或灯牌连接的实测记录。文中的灯牌编辑和连接路径是读者在真实产品中应执行的用例，不是该基础工程已经具备的功能。

1. 先定义要回答的问题

“能不能在远程设备打开”其实包含几个不同问题。安装失败可能是签名、设备类型或 SDK 范围；启动闪退可能是宿主初始化或插件注册；进入页面后控件错位是布局问题；发送灯牌无响应则又进入网络或蓝牙及外设侧。把这些混在一条“云调试通过”里，团队无法知道下一步该修什么。

问题	云调试适合先做吗	仍需补的证据
指定系统版本能否安装、启动	是	实际发布包、渠道审核
页面能否输入、切换、旋转	是	更多机型和可访问性检查
异常发生时能否取到日志	是	本地可复现或符号化信息
能否连接桌上的实体灯牌	通常不能直接证明	同网络/蓝牙环境下的实物联调
大量用户长时间运行是否稳定	不能只靠一次会话	性能、稳定性和灰度数据

华为 AGC 云调试介绍 说明远程设备可用于应用安装、操作、日志等开发调试。以上“不能证明”的判断是基于远程设备与本地外设不处于同一可控物理环境的工程推论，不能理解为云调试服务不支持任何外设能力。

2. 给每次会话一张设备卡

远程设备可能被更换，镜像也可能升级。笔记里只写“鸿蒙手机通过”无法复现。至少记录设备型号、系统/API 版本、形态、测试日期、包的 SHA-256、操作步骤和日志文件名。不要在公开文章里写设备标识、账号或日志里的个人信息。

会话编号：CD-20261020-01
设备：控制台显示的型号 / 系统版本 / API 版本
目标：安装、启动、编辑页旋转后状态不丢
安装包：app-debug.hap / SHA-256: <本机计算结果>
结果：通过 / 失败 / 未执行
证据：日志文件、关键画面、失败时刻

这里的编号与占位值只是记录格式，不是真实运行数据。设备与 API 版本一定要从当次控制台读取，不要从项目的 targetSdkVersion 倒推设备系统版本。

3. 先确认装上去的是哪个包

云端问题常因“本地刚改了代码，却传了上一次构建的 HAP”而误判。上传前先计算哈希；若复测，哈希相同才能说用的是同一份二进制。哈希不能证明签名有效或功能正确，但能固定排查对象。

$hap = 'D:\release\app-debug.hap'
if (-not (Test-Path -LiteralPath $hap)) {
  throw "HAP 不存在：$hap"
}
$file = Get-Item -LiteralPath $hap
$hash = Get-FileHash -LiteralPath $hap -Algorithm SHA256
[pscustomobject]@{
  Name = $file.Name
  Bytes = $file.Length
  SHA256 = $hash.Hash
  Modified = $file.LastWriteTime
} | Format-List

输入是本次待上传包的绝对路径。若路径不存在就立即停止，避免“云端跑了旧包”；输出中的文件大小和哈希写进设备卡。是否可安装还要结合签名、模块配置和云端错误提示判断，不能只看文件存在。

4. 选设备时按风险，不按新旧排序

API 迁移的核心是比较“旧目标环境”和“新目标环境”的行为，而不是只借一台最新机型。华为 API 升级适配说明 将版本适配与功能回归并列。下面矩阵是为灯牌场景设计的测试计划；设备是否在 AGC 实时可用，以控制台为准。

设备槽位	首测动作	失败后先看
当前线上主要设备版本	安装、冷启动、编辑与保存	是否发生既有功能回归
目标新 API 版本设备	同一路径再跑一遍	权限、窗口、插件行为变化
小屏或短高设备	键盘弹出、提交按钮触达	安全区域与滚动容器
宽屏/折叠形态	缩放、旋转、布局连续	状态是否被布局重建清空

如果当日无法预约到某类设备，把该槽位标为“未执行”，不要以相邻版本的结果代替。只有设备、包、步骤三者一致，跨版本结果才有比较价值。

5. 把操作步骤写成可重复的脚本

云调试不是随手点几下。对于灯牌编辑页，一条最小路径应当覆盖输入、预览、切换形态、返回和重入；如果应用确有设备连接能力，再在实体设备阶段加入连接/发送。以下是人工执行脚本，不依赖虚构的自动化接口。

01 安装固定哈希的包，冷启动一次，记录首屏时间与错误提示
02 进入编辑页，输入“演唱会 A 区”，选红色，速度设为中档
03 打开预览，确认文案、颜色、速度与输入一致
04 旋转或调整窗口，再回到原形态，确认三个值未丢
05 返回首页后重进，按产品设计检查是恢复还是清空
06 杀进程重开，按持久化约定检查草稿
07 导出日志，标注每个失败动作的时间点

这张脚本有两个关键边界：第 05、06 步的“正确值”由产品需求决定，不能擅自规定必须恢复；第 07 步应优先截取故障附近的日志，再进行脱敏，避免把整个会话的敏感数据上传到问题单。

6. 区分宿主启动失败和 Flutter 页面失败

参考工程的鸿蒙入口 EntryAbility 继承 FlutterAbility，插件由 GeneratedPluginRegistrant 注册；首页是 Flutter Widget。如果启动后白屏，要先判断卡在原生 Ability/Flutter 引擎初始化，还是 Widget 构建之后的业务问题。两种故障对应不同日志范围。

安装失败
  → 查看签名、包格式、deviceTypes 与 SDK 范围
Ability 启动后无 Flutter 首帧
  → 查看引擎加载、插件注册、原生异常
Flutter 首帧已出现但页面报错
  → 查看 Dart 异常、异步数据、布局约束
点击功能后才失败
  → 查看该功能的平台通道、权限与业务状态

这不是一份已经采集到的日志结论，而是排查顺序。尤其是平台通道调用成功与否，不能只凭界面是否显示按钮判断；需要有对应调用和错误信息。

7. 日志要有动作坐标，但不能泄露用户信息

当一个操作跨 Flutter 与鸿蒙宿主时，可以给关键节点一个短的事件名与会话内序号。日志应记录阶段、耗时与错误码，不记录灯牌文案原文、位置、手机号、设备标识或完整 Token。以下是适合放在业务层的示意代码，尚未接入参考工程。

void recordEditorStep(String step, int sequence, {String? errorCode}) {
  final safeStep = const {'open', 'preview', 'save'}.contains(step)
      ? step
      : 'unknown';
  debugPrint('led_editor step=$safeStep seq=$sequence '
      'error=${errorCode ?? "none"}');
}

recordEditorStep('preview', 3);

输入的 step 被限制在允许集合里，防止调用方把用户输入当事件名写入日志。上线时还需遵守项目的日志级别与采集策略；示例 debugPrint 不代表生产环境应持续打印。

8. 会话结束前完成证据导出

根据 AGC 云调试预约设备说明，入口在项目质量相关服务下；预约、设备可用性和时长以当前控制台为准。离开会话前先保存关键画面、失败提示和日志，否则“刚才确实白屏过”很难支撑问题定位。

$evidence = 'D:\cloud-debug\CD-20261020-01'
New-Item -ItemType Directory -Path $evidence -Force | Out-Null
$items = Get-ChildItem -LiteralPath $evidence -File
$items | Select-Object Name, Length, LastWriteTime | Format-Table

这段命令只建立本地证据目录并列出已导出的文件，不会从 AGC 自动下载日志。真正的导出动作以控制台界面提供的功能为准。发布问题单前应检查截图和日志是否包含账号、定位、设备 ID 或真实用户数据。

9. 用四级结果代替一个“通过”

一次会话可以部分成功。例如安装和启动通过，预览也通过，但横竖屏恢复失败；若只写“云调试通过”，后续排期会漏掉最重要的缺陷。建议按下表逐项记录，并附证据文件。

层级	判定条件	本文示例的结果
包与环境	哈希、设备版本、安装结果齐全	未执行
核心页面	输入、预览、返回符合预期	未执行
形态连续	旋转/窗口变化不丢关键状态	未执行
实物链路	外设连接与发送有独立实测	未执行

参考基础工程目前没有灯牌编辑和连接功能，因此不能把上面任何一项改成“通过”。当真实产品完成后，至少为每条结论关联设备卡、包哈希和对应日志或画面。

10. 排查与交付清单

现象	首要核查	不应直接下的结论
上传包后不能安装	包格式、签名、deviceTypes、SDK	Flutter 代码一定有错
打开即白屏	Ability、引擎、插件与 Dart 首帧	云设备一定坏了
旋转后文案消失	状态所有权、页面重建、持久化约定	只需增大控件宽度
远程设备找不到灯牌	物理距离、网络/蓝牙边界	APP 的连接实现已失败
日志没有错误	是否抓对时段、级别与进程	功能必定正确

交付前逐一确认：设备版本与包哈希可追溯；操作脚本可复跑；失败项有截图/日志时间点；日志已脱敏；云端未覆盖的实体外设和长期稳定性另有计划。云调试的价值是缩短定位路径，而不是用一台远程设备替代整套产品验收。

参考资料：AGC 云调试介绍、预约设备说明、HarmonyOS API 升级适配。页面入口、设备库存和规则可能更新，执行前以官方当前页面为准。