From f84988869c645acf8fb86539ee2b56d453927d5c Mon Sep 17 00:00:00 2001 From: lanterngamescn Date: Sat, 27 Jun 2026 01:03:35 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E7=9C=9F=E6=9C=BA=20ArkWeb?= =?UTF-8?q?=20DevTools=20=E4=B8=80=E9=94=AE=E8=84=9A=E6=9C=AC=20+=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=A1=A5=E5=A4=9A=E8=AE=BE=E5=A4=87/fport=20?= =?UTF-8?q?=E5=9D=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - scripts/arkweb-devtools.sh：自动找 hdc、选真机(排除模拟器)、取 pid(没运行则拉起)、 清掉端口上所有旧转发并重建 tcp:9222、curl 自验。幂等可反复跑；应用重启后重跑即可重连。 （修正：hdc `fport rm` 需 local/remote 两参数分开传，否则删不掉；会累积多条旧转发需逐条清。） - 文档加「一键脚本」快速开始、「多设备必须带 -t」提示、fport rm 两参数/累积排查。 Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/开发调试/真机ArkWeb-DevTools调试.md | 20 +++++++- scripts/arkweb-devtools.sh | 64 ++++++++++++++++++++++++ 2 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 scripts/arkweb-devtools.sh diff --git a/docs/开发调试/真机ArkWeb-DevTools调试.md b/docs/开发调试/真机ArkWeb-DevTools调试.md index dcd7387..3bc3a93 100644 --- a/docs/开发调试/真机ArkWeb-DevTools调试.md +++ b/docs/开发调试/真机ArkWeb-DevTools调试.md @@ -6,6 +6,20 @@ --- +## 🚀 最快：一键脚本 + +```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 调用了 @@ -30,8 +44,9 @@ ArkWeb 开启远程调试后，会在应用进程下开一个 **abstract domain 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` 里那一串。 +- **⚠ 多设备必须带 `-t `**：如果同时连了真机 + 模拟器（`hdc list targets` 会列出真机 serial 和形如 `127.0.0.1:5555` 的模拟器），**不带 `-t` 可能把命令发到模拟器上，pidof/转发都打在错的设备 → chrome 里找不到真机页面**。真机 serial 是不含 `:` 的那一串。 +- **单设备**才可省略 `-t `： ```bash hdc fport tcp:9222 localabstract:webview_devtools_remote_$(hdc shell pidof com.lobby.daoqi | tr -d '\r') @@ -103,6 +118,7 @@ devecocli log --keyword ARKWEB-CONSOLE - **`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 fport ls | grep 9222` 看有几条，逐条删——⚠ **`fport rm` 要把 local 和 remote 两段分开传**（`fport rm tcp:9222 localabstract:webview_devtools_remote_`，不能 `fport rm tcp:9222`，也不能写成一个带空格的字符串）。一键脚本已自动清理。 - **页面是 `` 看不到 DOM 结构**：H5 游戏（gameabc/ifast 引擎）大量内容画在 canvas 上，DevTools 的 Elements 只能看到外层 ``，看不到「按钮」等精灵——这是正常的，它们是引擎在 canvas 内绘制的，不是 DOM 元素。 --- diff --git a/scripts/arkweb-devtools.sh b/scripts/arkweb-devtools.sh new file mode 100644 index 0000000..4b3b40d --- /dev/null +++ b/scripts/arkweb-devtools.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +# 一键建立真机 ArkWeb DevTools 端口转发，供 chrome://inspect 调试 H5。 +# 自动：找 hdc → 选真机(排除模拟器) → 取应用 pid(没运行则拉起) → 重建 tcp:9222 转发 → 验证。 +# +# 用法： +# bash scripts/arkweb-devtools.sh # 默认 com.lobby.daoqi, 端口 9222 +# bash scripts/arkweb-devtools.sh [serial] +# 之后在 Chrome 打开 chrome://inspect → Discover network targets → 加 localhost:9222 → inspect。 +# 应用一旦重启 pid 会变、转发失效，重跑本脚本即可（端口不变，chrome 配置不用改）。 + +set -u +BUNDLE="${1:-com.lobby.daoqi}" +PORT="${2:-9222}" +SERIAL="${3:-}" +export MSYS_NO_PATHCONV=1 # git-bash 下避免 localabstract 路径被转换 + +find_hdc() { + command -v hdc >/dev/null 2>&1 && { echo hdc; return 0; } + local p + for p in "$HOME"/AppData/Local/OpenHarmony/Sdk/*/toolchains/hdc \ + "$HOME"/AppData/Local/Huawei/Sdk/*/*/toolchains/hdc; do + [ -x "$p" ] && { echo "$p"; return 0; } + done + p="/c/Program Files/Huawei/DevEco Studio/sdk/default/openharmony/toolchains/hdc.exe" + [ -x "$p" ] && { echo "$p"; return 0; } + return 1 +} + +HDC="$(find_hdc)" || { echo "✗ 找不到 hdc，请把 /toolchains 加入 PATH"; exit 1; } + +# 选真机：排除 127.0.0.1 模拟器；未指定 serial 时取第一台真机 +if [ -z "$SERIAL" ]; then + SERIAL="$("$HDC" list targets 2>/dev/null | tr -d '\r' | grep -v '127.0.0.1' | grep -viE 'empty|^\s*$' | head -1)" +fi +[ -z "$SERIAL" ] && { echo "✗ 没有连接的真机（hdc list targets 为空或只有模拟器）"; exit 1; } +echo "真机: $SERIAL" + +# 取 pid，没运行就拉起（注意：必须是 debug 包，才开了 setWebDebuggingAccess） +PID="$("$HDC" -t "$SERIAL" shell pidof "$BUNDLE" 2>/dev/null | tr -d '\r')" +if [ -z "$PID" ]; then + echo "应用未运行，拉起 $BUNDLE …" + "$HDC" -t "$SERIAL" shell aa start -a EntryAbility -b "$BUNDLE" >/dev/null 2>&1 + sleep 3 + PID="$("$HDC" -t "$SERIAL" shell pidof "$BUNDLE" 2>/dev/null | tr -d '\r')" +fi +[ -z "$PID" ] && { echo "✗ 取不到应用 pid（确认是 debug 包且在前台运行）"; exit 1; } +echo "pid: $PID" + +# 先删干净端口上【所有】旧转发（会积累多条指向已死 pid 的）。 +# 注意 hdc 的 `fport rm` 要 local/remote 两个参数分开传（不能是单个带空格的字符串），故 $rule 不加引号让其分词。 +"$HDC" -t "$SERIAL" fport ls 2>/dev/null | tr -d '\r' | awk -v p="tcp:$PORT" '$2==p{print $2" "$3}' | while IFS= read -r rule; do + # shellcheck disable=SC2086 + [ -n "$rule" ] && "$HDC" -t "$SERIAL" fport rm $rule >/dev/null 2>&1 +done +# 建新转发（指向当前 pid） +"$HDC" -t "$SERIAL" fport "tcp:$PORT" "localabstract:webview_devtools_remote_$PID" 2>&1 | tr -d '\r' + +# 验证 +if curl -s -m 6 "http://localhost:$PORT/json" 2>/dev/null | grep -q '"type"'; then + echo "✓ 就绪：http://localhost:$PORT 已能列出页面" + echo "→ Chrome 打开 chrome://inspect，Discover network targets 加 localhost:$PORT，点页面的 inspect" +else + echo "⚠ 转发已建，但 /json 暂无页面（应用可能还没加载完）。稍等几秒再： curl http://localhost:$PORT/json" +fi