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

目录

一、核心原理

[二、前置：代码开启 Web 调试（必须第一步）](#二、前置：代码开启 Web 调试（必须第一步）)

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

[方式 2：组件内单独开启（单页面生效）](#方式 2：组件内单独开启（单页面生效）)

权限补充

[三、调试方式（USB 有线 ）](#三、调试方式（USB 有线 ）)

[步骤 1：设备开启开发者模式](#步骤 1：设备开启开发者模式)

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

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

[步骤 4：Chrome 连接调试面板](#步骤 4：Chrome 连接调试面板)

[四、Chrome DevTools 可实现的全部调试功能（解决 H5 所有问题）](#四、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 所有问题）

面板	作用（鸿蒙 Web 高频场景）
Elements	查看 / 修改 DOM、CSS，排查适配、白屏、样式错乱、刘海遮挡
Console	查看 h5 console.log/ 报错，执行 JS 和 ArkWeb 桥接测试
Network	抓全部接口请求、HTTPS 明文查看、看 404 / 跨域、上传下载
Sources	H5 JS 源码断点、单步调试、定位 JS 崩溃白屏根源
Application	查看 localStorage/cookie、缓存、本地存储
Performance	页面加载性能、渲染卡顿、内存泄漏分析
Memory	H5 内存溢出、页面切换残留占用排查