lanterngamescnandClaude Opus 4.8
344fe8d613
新增 docs/开发调试/真机ArkWeb-DevTools调试.md：HarmonyOS 不走 chrome USB discovery， 需 hdc fport 转发 webview_devtools_remote_<pid> → localhost:9222，再加 network target； 含自动取 pid 一条命令、pid 随重启变化需重连、ARKWEB-CONSOLE 看日志、canvas 不可见元素、 以及"DevTools 鼠标点击≠真机触摸"的调试陷阱。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
117 lines
5.5 KiB
Markdown
117 lines
5.5 KiB
Markdown
# 真机 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:<端口>`。
|
||
|
||
---
|
||
|
||
## 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）：**
|
||
|
||
```bash
|
||
# 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>`）。
|
||
- 单设备简化版：
|
||
|
||
```bash
|
||
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，再转发）：**
|
||
|
||
```bash
|
||
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. 验证转发是否通
|
||
|
||
```bash
|
||
curl -s http://localhost:9222/json/version # 应返回 ArkWeb 的 Chrome / ArkWeb 版本
|
||
curl -s http://localhost:9222/json # 应列出可调试页面（title / url / type=page）
|
||
```
|
||
|
||
`/json` 里能看到大厅页面，例如：
|
||
|
||
```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`**：
|
||
|
||
```bash
|
||
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` 看下）。
|
||
- **页面是 `<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 鼠标的事件序列。
|