【工具汇总】鸿蒙 ArkWeb完整调试工具步骤

目录

一、核心原理

二、前置：代码开启 Web 调试（必须第一步）

方式 1：全局开启（推荐，整个应用所有 Web 页面生效）

方式 2：组件内单独开启（单页面生效）

权限补充

三、调试方式（USB 有线 ）

步骤 1：设备开启开发者模式

步骤 2：DevEco Studio 一键自动转发（懒人首选，不用敲命令）

步骤 3：手动 hdc 命令转发（IDE 自动转发失效时用，Mac 终端直接执行）

步骤 4：Chrome 连接调试面板

四、Chrome DevTools 可实现的全部调试功能（解决 H5 所有问题）

鸿蒙内嵌 H5 页面唯一官方标准调试工具：Chrome DevTools（谷歌浏览器调试面板），搭配 DevEco Studio 自动转发、hdc 命令、日志工具，下面分全套操作、两种调试模式、辅助工具、踩坑点完整说明。

一、核心原理

鸿蒙 Web 组件（ArkWeb）底层基于 Chromium 内核，支持远程调试协议；需要代码开启调试开关 + 端口转发 + Chrome 连接三步，即可像调试网页一样审查元素、抓接口、打断点、看 console 日志

二、前置：代码开启 Web 调试（必须第一步）

方式 1：全局开启（推荐，整个应用所有 Web 页面生效）

在页面aboutToAppear或EntryAbility的onWindowStageCreate中全局开启，仅 Debug 包启用，上线 Release 务必关闭。

import { webview } from '@kit.ArkWeb'; @Entry @Component struct WebPage { controller: webview.WebviewController = new webview.WebviewController(); aboutToAppear() { // 开启USB调试模式（全版本通用） webview.WebviewController.setWebDebuggingAccess(true); } build() { Web({ src: "https://xxx.com/h5", controller: this.controller }) } }

方式 2：组件内单独开启（单页面生效）

Web({ src: $rawfile("local.html"), controller: this.controller }) .webDebuggingAccess(true)

权限补充

模块module.json5必须声明网络权限，否则调试连接失败：

"requestPermissions": [ {"name": "ohos.permission.INTERNET"} ]

三、调试方式（USB 有线 ）

步骤 1：设备开启开发者模式

1. 设置 → 关于本机 → 连续点击版本号7 次开启开发者模式
2. 设置 → 系统和更新 → 开发者选项 → 打开USB 调试
3. USB 连接 Mac/Windows 电脑，设备弹窗授权调试

步骤 2：DevEco Studio 一键自动转发（懒人首选，不用敲命令）

从 DevEco Studio 5.0.5 开始内置Auto WebView Debug自动端口转发：

1. 顶部菜单Run → Edit Configurations
2. 切换到对应 hap 模块，在 General 栏勾选Auto WebView Debug
3. 重新运行 App，打开 Web 页面，IDE 自动完成 hdc 端口映射，Run 控制台打印转发端口9222

步骤 3：手动 hdc 命令转发（IDE 自动转发失效时用，Mac 终端直接执行）

如果步骤2 中 Run 控制台打印转发端口 9222，则不用考虑步骤3

# 1. 查看连接设备 hdc list targets # 2. 端口映射 本地9222 <-> 设备Web调试端口 hdc fport tcp:9222 tcp:9222 # 3. 验证端口是否转发成功 hdc fport ls

多页面 / 多 Web 进程端口冲突时，可查询设备调试 socket 手动映射

# 查设备内web调试进程标识 hdc shell cat /proc/net/unix | grep devtools # 映射示例（替换末尾数字为查到的进程号） hdc fport tcp:9222 localabstract:webview_devtools_remote_38532

步骤 4：Chrome 连接调试面板

1. 电脑 Chrome 地址栏输入：chrome://inspect/#devices
2. 勾选Discover USB devices、Discover network targets
3. 下方Remote Target会出现你的 H5 页面，点击inspect打开完整调试面板

四、Chrome DevTools 可实现的全部调试功能（解决 H5 所有问题）