arkweb-app-debug

ArkWeb 应用调试

何时使用此技能

当用户需要调试 HarmonyOS ArkWeb（WebView）应用时，使用此技能：

• 调试：“调试我的 WebView”“将 DevTools 连接到应用”“检查 WebView”
• 测试：“测试网页”“自动化 WebView 测试”“检查 WebView 元素”
• 故障排查：“WebView 无法正常工作”“无法连接 DevTools”“未找到 Socket”
• 检查：“显示 WebView 控制台”“检查网络请求”“检查 Web 元素”

快速开始

启动 ArkWeb 调试会话：

# Using the debug script (auto-configures environment)
$SKILL_DIR/scripts/start-debug.sh

# Or with explicit package name
$SKILL_DIR/scripts/start-debug.sh --package com.example.app

内置资源

此技能在 scripts/ 中包含调试脚本：

脚本	用途
start-debug.sh	启动调试会话（macOS/Linux，自动配置环境）
start-debug.py	启动调试会话（跨平台 Python）
start-debug.bat	启动调试会话（Windows，自动配置环境）

所有脚本都会自动：

• 检测 DevEco Studio 安装情况（通过 ohos-app-build-debug 技能）
• 配置 hdc 和其他工具的环境
• 查找 HarmonyOS 项目配置
• 连接设备并创建端口转发
• 在 http://127.0.0.1:9222 打开 Chrome DevTools

详细文档请参阅 references/。

常见工作流

启动调试会话

# Run the debug script from your HarmonyOS project directory
cd /path/to/harmonyos/project
$SKILL_DIR/scripts/start-debug.sh

# The script automatically:
# - Detects project configuration (package name, HAP path)
# - Connects to device
# - Creates port forwarding to webview_devtools socket
# - Opens Chrome DevTools

与 ohos-app-build-debug 集成

完整开发工作流：

# 1. Build and install app (using ohos-app-build-debug skill)
$OHOS_SKILL_DIR/scripts/build.py
$OHOS_SKILL_DIR/scripts/install.py -f entry/build/default/outputs/default/entry-default-signed.hap
$OHOS_SKILL_DIR/scripts/launch.py

# 2. Start debugging (this skill)
$SKILL_DIR/scripts/start-debug.sh

AI 自动化测试（使用 MCP）

配置 Chrome DevTools MCP 后，Claude 可以自动测试 WebView 功能：

User: Please test the login functionality in my webview
Claude: (Automatically uses Chrome DevTools MCP)
  - Opens DevTools connection
  - Navigates to login page
  - Fills out form
  - Submits and verifies results

请参阅 references/mcp-guide.md，了解 MCP 设置和可用工具。

工作原理

自动检测

调试脚本会自动：

1. 检测 DevEco Studio：使用 ohos-app-build-debug 技能查找 DevEco Studio 并配置 hdc
2. 查找项目：向上搜索 HarmonyOS 项目根目录（最多 5 层）
3. 读取配置：从 AppScope/app.json5 提取包名
4. 连接设备：使用 hdc 连接 HarmonyOS 设备
5. 查找 Socket：动态定位 webview_devtools Socket（处理 PID 变化）
6. 创建端口转发：设置从设备到 localhost:9222 的端口转发
7. 打开 DevTools：启动带有 DevTools 的 Chrome/Chromium

关键时序

根据实际调试经验：

• 应用启动后：等待 10 秒，让 Web 组件创建调试 Socket
• 端口转发后：等待 2 秒，让 Socket 初始化
• 查找 Socket：每隔 2 秒重试，最长等待 15 秒

脚本会自动处理这些时序。

响应指南

帮助用户调试 ArkWeb 时：

1. 先检查环境

   • 确认 hdc 可用（脚本应能自动检测）
   • 检查设备连接：hdc list targets
   • 确保应用在 aboutToAppear() 中调用了 setWebDebuggingAccess(true)

2. 使用脚本

   • 调用 scripts/ 目录中的脚本
   • 将 $SKILL_DIR 替换为实际的技能安装路径
   • 将 $OHOS_SKILL_DIR 替换为 ohos-app-build-debug 技能路径

3. 处理常见问题

   • 未找到 Socket：等待 10-15 秒，确保应用已初始化且 Web 组件已渲染
   • 端口被占用：可能有之前的会话仍在运行，使用 hdc fport list 检查
   • 未找到设备：检查 USB 连接和授权状态
   • 未找到 hdc：脚本应能通过 ohos-app-build-debug 自动检测

4. 配合 ohos-app-build-debug 使用

   • 对于构建/安装问题，使用 ohos-app-build-debug 技能
   • 此技能仅专注于调试

5. 显示实际命令

   • 为确保透明，显示正在执行的 hdc 命令
   • 显示端口转发设置
   • 提供 DevTools URL

应用要求

ArkWeb 应用必须在 aboutToAppear() 中启用调试：

import { webview } from '@kit.ArkWeb';

@Entry
@Component
struct Index {
  controller: webview.WebviewController = new webview.WebviewController();

  aboutToAppear() {
    // CRITICAL: Enable debugging BEFORE Web component renders
    webview.WebviewController.setWebDebuggingAccess(true);
  }

  build() {
    Web({ src: this.currentUrl, controller: this.controller })
  }
}

错误处理

如果未检测到 DevEco Studio/hdc：

• 确认已安装 DevEco Studio
• 确保 ohos-app-build-debug 技能可用
• 脚本会尝试自动配置环境

如果设备未连接：

• 检查 USB 线缆连接
• 确认设备已启用 USB 调试
• 出现提示时，在设备上授权 USB 调试

如果未找到套接字：

• 确保代码中已设置 setWebDebuggingAccess(true)
• 等待 10-15 秒，让应用完成初始化
• 确认 Web 组件已渲染（导航到某个 URL）
• 检查应用是否崩溃：hdc shell ps -A | grep <package>

如需详细的故障排查信息，请参阅 references/troubleshooting.md。

前提条件

• DevEco Studio 3.1+（建议使用 4.0+）或 PATH 中的 hdc
• 已启用 USB 调试的 HarmonyOS 设备
• 已启用 setWebDebuggingAccess(true) 的 ArkWeb 应用
• Python 3.8+（用于 start-debug.py 脚本）
• Chrome/Chromium 浏览器（用于 DevTools）

可选：用于 AI 自动化测试的 Chrome DevTools MCP

下载 DevEco Studio：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-download