arkweb-app-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ArkWeb App Debug

ArkWeb应用调试

When to Use This Skill

适用场景

Use this skill when the user needs to debug HarmonyOS ArkWeb (webview) applications:

Debugging: "Debug my webview", "Connect DevTools to app", "Inspect webview"
Testing: "Test the web page", "Automate webview testing", "Check webview elements"
Troubleshooting: "Webview not working", "Can't connect DevTools", "Socket not found"
Inspection: "Show me webview console", "Inspect network requests", "Check web elements"

当用户需要调试HarmonyOS ArkWeb（webview）应用时使用此skill：

调试："调试我的webview"、"将DevTools连接到应用"、"检查webview"
测试："测试网页"、"自动化webview测试"、"检查webview元素"
问题排查："Webview无法工作"、"无法连接DevTools"、"未找到套接字"
检查："展示webview控制台"、"检查网络请求"、"检查网页元素"

Quick Start

快速开始

Start an ArkWeb debugging session:

bash

undefined

启动ArkWeb调试会话：

bash

undefined

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

undefined

$SKILL_DIR/scripts/start-debug.sh --package com.example.app

undefined

Bundled Resources

内置资源

This skill includes debugging scripts in

scripts/

Script	Purpose
`start-debug.sh`	Start debugging session (macOS/Linux, auto-configures environment)
`start-debug.py`	Start debugging session (cross-platform Python)
`start-debug.bat`	Start debugging session (Windows, auto-configures environment)

All scripts automatically:

Detect DevEco Studio installation (via ohos-app-build-debug skill)
Configure environment for hdc and other tools
Find HarmonyOS project configuration
Connect to device and create port forwarding
Open Chrome DevTools on http://127.0.0.1:9222

For detailed documentation, see references/.

此skill在

scripts/

目录中包含调试脚本：

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

所有脚本会自动执行以下操作：

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

详细文档请查看references/。

Common Workflows

常见工作流

Start Debugging Session

启动调试会话

bash

undefined

bash

undefined

Run the debug script from your HarmonyOS project directory

从HarmonyOS项目目录运行调试脚本

cd /path/to/harmonyos/project $SKILL_DIR/scripts/start-debug.sh

The script automatically:

脚本会自动：

- Detects project configuration (package name, HAP path)

- 检测项目配置（包名、HAP路径）

- Connects to device

- 连接设备

- Creates port forwarding to webview_devtools socket

- 创建到webview_devtools套接字的端口转发

- Opens Chrome DevTools

- 打开Chrome DevTools

undefined

undefined

Integration with ohos-app-build-debug

与ohos-app-build-debug集成

For complete development workflow:

bash

undefined

实现完整开发工作流：

bash

undefined

1. Build and install app (using ohos-app-build-debug skill)

1. 构建并安装应用（使用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)

2. 启动调试（使用本skill）

$SKILL_DIR/scripts/start-debug.sh

undefined

$SKILL_DIR/scripts/start-debug.sh

undefined

AI Automated Testing (with MCP)

AI自动化测试（通过MCP）

When Chrome DevTools MCP is configured, Claude can automatically test webview functionality:

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

See references/mcp-guide.md for MCP setup and available tools.

配置Chrome DevTools MCP后，可自动测试webview功能：

用户：请测试我的webview中的登录功能
Claude：（自动使用Chrome DevTools MCP）
  - 打开DevTools连接
  - 导航到登录页面
  - 填写表单
  - 提交并验证结果

MCP设置及可用工具请查看references/mcp-guide.md。

How It Works

工作原理

Automatic Detection

自动检测

The debug scripts automatically:

Detect DevEco Studio: Uses ohos-app-build-debug skill to find DevEco Studio and configure hdc
Find Project: Searches upward for HarmonyOS project root (max 5 levels)
Read Configuration: Extracts package name from
```
AppScope/app.json5
```
Connect Device: Uses hdc to connect to HarmonyOS device
Find Socket: Dynamically locates webview_devtools socket (handles PID changes)
Create Port Forward: Sets up port forwarding from device to localhost:9222
Open DevTools: Launches Chrome/Chromium with DevTools

调试脚本会自动执行以下步骤：

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

Critical Timing

关键时机

Based on real debugging experience:

After app start: Wait 10 seconds for Web component to create debugging socket
After port forward: Wait 2 seconds for socket initialization
Socket finding: Retry every 2 seconds for up to 15 seconds

The scripts handle these timings automatically.

基于实际调试经验：

应用启动后：等待10秒，让Web组件创建调试套接字
端口转发后：等待2秒，让套接字完成初始化
套接字查找：每2秒重试一次，最多15秒

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

Response Guidelines

响应指南

When helping users with ArkWeb debugging:

Check Environment First
- Verify hdc is available (should be auto-detected by scripts)
- Check device connection:
```
hdc list targets
```
- Ensure app has
```
setWebDebuggingAccess(true)
```
  in
```
aboutToAppear()
```
Use Scripts
- Call scripts in
```
scripts/
```
  directory
- Replace
```
$SKILL_DIR
```
  with actual skill installation path
- Replace
```
$OHOS_SKILL_DIR
```
  with ohos-app-build-debug skill path
Handle Common Issues
- Socket not found: Wait 10-15s for app initialization, ensure Web component rendered
- Port in use: Previous session may be running, check with
```
hdc fport list
```
- Device not found: Check USB connection and authorization
- hdc not found: Scripts should auto-detect via ohos-app-build-debug
Coordinate with ohos-app-build-debug
- For build/install issues, use ohos-app-build-debug skill
- This skill focuses on debugging only
Show Actual Commands
- Display the hdc commands being executed for transparency
- Show port forwarding setup
- Indicate DevTools URL

在帮助用户进行ArkWeb调试时：

先检查环境
- 验证hdc是否可用（脚本应自动检测）
- 检查设备连接：
```
hdc list targets
```
- 确保应用在
```
aboutToAppear()
```
  中设置了
```
setWebDebuggingAccess(true)
```
使用脚本
- 调用
```
scripts/
```
  目录中的脚本
- 将
```
$SKILL_DIR
```
  替换为实际的skill安装路径
- 将
```
$OHOS_SKILL_DIR
```
  替换为ohos-app-build-debug skill的路径
处理常见问题
- 未找到套接字：等待10-15秒让应用初始化，确保Web组件已渲染
- 端口被占用：可能存在之前的会话，使用
```
hdc fport list
```
  检查
- 未找到设备：检查USB连接和授权
- 未找到hdc：脚本应通过ohos-app-build-debug自动检测
与ohos-app-build-debug配合
- 构建/安装问题请使用ohos-app-build-debug skill
- 本skill专注于调试操作
展示实际命令
- 显示正在执行的hdc命令以保证透明性
- 展示端口转发设置
- 指明DevTools的URL

Application Requirements

应用要求

ArkWeb applications must enable debugging in

aboutToAppear()

typescript

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 })
  }
}

ArkWeb应用必须在

aboutToAppear()

中启用调试：

typescript

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

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

  aboutToAppear() {
    // 关键：在Web组件渲染前启用调试
    webview.WebviewController.setWebDebuggingAccess(true);
  }

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

Error Handling

错误处理

If DevEco Studio/hdc is not detected:

Verify DevEco Studio is installed
Ensure ohos-app-build-debug skill is available
Scripts will attempt to auto-configure environment

If device is not connected:

Check USB cable connection
Verify USB debugging is enabled on device
Authorize USB debugging on device when prompted

If socket is not found:

Ensure app has
```
setWebDebuggingAccess(true)
```
in code
Wait 10-15 seconds for app to fully initialize
Verify Web component has rendered (navigate to a URL)
Check if app crashed:
```
hdc shell ps -A | grep <package>
```

For detailed troubleshooting, see references/troubleshooting.md.

如果未检测到DevEco Studio/hdc：

验证DevEco Studio已安装
确保ohos-app-build-debug skill可用
脚本会尝试自动配置环境

如果设备未连接：

检查USB线缆连接
验证设备已启用USB调试
提示时在设备上授权USB调试

如果未找到套接字：

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

详细排查指南请查看references/troubleshooting.md。

Prerequisites

前置条件

DevEco Studio 3.1+ (4.0+ recommended) OR hdc in PATH
HarmonyOS device with USB debugging enabled
ArkWeb app with
```
setWebDebuggingAccess(true)
```
enabled
Python 3.8+ (for start-debug.py script)
Chrome/Chromium browser (for DevTools)

Optional: Chrome DevTools MCP for AI automated testing

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

DevEco Studio 3.1+（推荐4.0+）或hdc已添加到PATH
已启用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