From 344fe8d6130a48b6c98451263b71f55be96f2599 Mon Sep 17 00:00:00 2001
From: lanterngamescn <lanterngamescn@gmail.com>
Date: Sat, 27 Jun 2026 00:52:30 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=9A=E7=9C=9F=E6=9C=BA?=
 =?UTF-8?q?=20ArkWeb=20DevTools=20=E8=B0=83=E8=AF=95=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=EF=BC=88hdc=20fport=20+=20chrome=20network=20target=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

新增 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>
---
 docs/开发调试/真机ArkWeb-DevTools调试.md | 116 +++++++++++++++++++++++
 1 file changed, 116 insertions(+)
 create mode 100644 docs/开发调试/真机ArkWeb-DevTools调试.md

diff --git a/docs/开发调试/真机ArkWeb-DevTools调试.md b/docs/开发调试/真机ArkWeb-DevTools调试.md
new file mode 100644
index 0000000..dcd7387
--- /dev/null
+++ b/docs/开发调试/真机ArkWeb-DevTools调试.md
@@ -0,0 +1,116 @@
+# 真机 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 鼠标的事件序列。