# 真机 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
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）：**

```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>`**：如果同时连了真机 + 模拟器（`hdc list targets` 会列出真机 serial 和形如 `127.0.0.1:5555` 的模拟器），**不带 `-t` 可能把命令发到模拟器上，pidof/转发都打在错的设备 → chrome 里找不到真机页面**。真机 serial 是不含 `:` 的那一串。
- **单设备**才可省略 `-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` 看下）。
- **`[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 鼠标的事件序列。