youle_app_ohos/docs/开发调试/真机ArkWeb-DevTools调试.md

真机 ArkWeb（H5/WebView）DevTools 调试

调试 H5（大厅 / 子游戏 / 通用网页里的网页内容）时，用电脑 Chrome 的 DevTools 远程连接真机上的 ArkWeb 内核，可以审查元素、看 Console / Network、断点、Animations 等。

⚠ 关键差异：HarmonyOS 的 ArkWeb 不走 Chrome 的「Discover USB devices」（那是 Android adb 专用）。必须用 hdc fport 把 ArkWeb 的 DevTools domain socket 转发成本地 TCP 端口，再在 Chrome 的「Discover network targets」里添加 localhost:<端口>。

---

🚀 最快：一键脚本

bash scripts/arkweb-devtools.sh

它会自动：找 hdc → 选真机（排除模拟器）→ 取应用 pid（没运行则拉起）→ 清掉端口上所有旧转发并重建 tcp:9222 → curl 自验。 成功后去 Chrome 打开 chrome://inspect，在 Discover network targets 里加 localhost:9222（只需加一次），点页面的 inspect。 应用一旦重启 pid 变、连接断了，重跑这条脚本即可（端口不变、chrome 配置不用改、幂等可反复跑）。

想手动理解原理 / 脚本不适用你的环境时，看下面的分步说明。

---

0. 前置条件

1. 必须是 debug 包。本工程在 BridgeGameContainer.aboutToAppear() 里仅 debug 调用了 webview.WebviewController.setWebDebuggingAccess(true)（AppEnv.isDebug() 守卫）；release 包不开远程调试，连不上。
2. 电脑装了 Chrome（或 Edge 等 Chromium 内核浏览器）。
3. hdc 可用（随 HarmonyOS SDK，路径形如 <SDK>/toolchains/hdc，例如 ~/AppData/Local/OpenHarmony/Sdk/<版本>/toolchains/hdc），且真机已通过 hdc list targets 能看到。
4. 应用包名：com.lobby.daoqi。

备注：本工程使用的 ArkWeb 内核约为 Chrome 132 / ArkWeb 6.1.x（可用第 2 步的 /json/version 查看实际版本）。

---

1. 建立端口转发（fport）

ArkWeb 开启远程调试后，会在应用进程下开一个 abstract domain socket：@webview_devtools_remote_<pid>（<pid> 是应用进程 id，每次重启会变）。

一条命令搞定（自动取当前 pid 并转发到本地 9222）：

# Windows git-bash / Linux / macOS 通用
hdc -t <设备serial> fport tcp:9222 localabstract:webview_devtools_remote_$(hdc -t <设备serial> shell pidof com.lobby.daoqi | tr -d '\r')

• <设备serial>：hdc list targets 里那一串。
• ⚠ 多设备必须带 -t <serial>：如果同时连了真机 + 模拟器（hdc list targets 会列出真机 serial 和形如 127.0.0.1:5555 的模拟器），不带 -t 可能把命令发到模拟器上，pidof/转发都打在错的设备 → chrome 里找不到真机页面。真机 serial 是不含 : 的那一串。
• 单设备才可省略 -t <serial>：

hdc fport tcp:9222 localabstract:webview_devtools_remote_$(hdc shell pidof com.lobby.daoqi | tr -d '\r')

Windows git-bash 里如果路径/参数被转换出错，给该命令前加 MSYS_NO_PATHCONV=1。

手动两步版（先查 pid，再转发）：

hdc shell pidof com.lobby.daoqi          # 得到 <pid>
hdc fport tcp:9222 localabstract:webview_devtools_remote_<pid>
hdc fport ls                             # 确认已建立（应看到 tcp:9222 -> webview_devtools_remote_<pid>）

---

2. 验证转发是否通

curl -s http://localhost:9222/json/version    # 应返回 ArkWeb 的 Chrome / ArkWeb 版本
curl -s http://localhost:9222/json            # 应列出可调试页面（title / url / type=page）

/json 里能看到大厅页面，例如：

{ "title": "gameabc", "type": "page",
  "url": "file:///data/.../tsgames/.../gamehall/index.html?Launchtype=0" }

---

3. Chrome 里打开 DevTools

1. Chrome 地址栏输入 chrome://inspect。
2. 勾选 Discover network targets → 点右边 Configure...。
3. 添加一行：localhost:9222 → Done。
4. 稍等一两秒，下方 Remote Target 区出现页面（如 gameabc，url 为 .../gamehall/index.html）。
5. 点该页面的 inspect → 打开 DevTools，即可审查元素 / Console / Network / Sources 断点 / Animations。

「Discover USB devices」对 HarmonyOS 无效，可不管。

---

4. 应用重启后连接断了怎么办

转发绑定的是当前进程 pid。一旦杀掉/重启应用，pid 变化，转发失效，chrome://inspect 里页面消失。

重连：重新执行第 1 步那条「自动取 pid」的命令即可（端口仍用 9222，Chrome 里的 localhost:9222 配置不用改）。

---

5. 只想看 H5 的 console（不开 DevTools）

ArkWeb 会把网页 console.* 镜像到 hilog，tag 为 ARKWEB-CONSOLE：

hdc shell hilog | grep ARKWEB-CONSOLE
# 或
devecocli log --keyword ARKWEB-CONSOLE

历史上本工程也临时加过自定义 onConsole（tag WebConsole，debug 限定）转发，排查结束后已移除；需要时用上面的原生 ARKWEB-CONSOLE 即可。

---

6. 常见问题

• chrome://inspect 里 Remote Target 一直空：多半是没建 fport，或建错 pid（应用重启过）。重跑第 1 步并用第 2 步 curl /json 自查。
• curl /json/version 连不上：① 不是 debug 包（没开 setWebDebuggingAccess）；② pidof 没取到（应用没在前台运行）；③ fport 没建成功（hdc fport ls 看下）。
• [Fail]TCP Port listen failed at 9222：9222 上已存在转发（每次 fport 都会累积一条，应用多次重启后会有多条指向已死 pid 的）。只要 curl /json 通就不影响用。想清干净：hdc -t <serial> fport ls | grep 9222 看有几条，逐条删——⚠ fport rm 要把 local 和 remote 两段分开传（fport rm tcp:9222 localabstract:webview_devtools_remote_<pid>，不能 fport rm tcp:9222，也不能写成一个带空格的字符串）。一键脚本已自动清理。
• 页面是 <canvas> 看不到 DOM 结构：H5 游戏（gameabc/ifast 引擎）大量内容画在 canvas 上，DevTools 的 Elements 只能看到外层 <canvas>，看不到「按钮」等精灵——这是正常的，它们是引擎在 canvas 内绘制的，不是 DOM 元素。

---

7. 一个重要的调试陷阱（务必知道）

在 DevTools 里点击 ≠ 真机上触摸：DevTools 的「inspect」窗口/截屏里点击，Chromium 发的是 鼠标事件（CDP Input.dispatchMouseEvent）；真机手指触摸发的是触摸事件。

二者行为可能不同——例如本工程曾遇到「真机触摸按钮不缩放、但在 DevTools 里点击却正常缩放」，真因是 ArkWeb 把触摸合成的 mousedown/mouseup 挤在抬手后极短时间内（详见记忆 arkweb-canvas-compositing-keepalive，已用 touch→mouse shim 修复）。

结论：排查输入/交互类问题时，DevTools 里点击「正常」不能直接断定问题不存在，要以真机实际触摸为准；必要时在 DevTools Sources 里对相关 H5 事件下断点，对比触摸 vs 鼠标的事件序列。