HarmonyOS ArkWeb 系列之用 Chrome DevTools 调试手机上的网页

文章目录

• • • 开启调试模式的方法
    • USB 调试完整代码
    • 权限配置
    • 用 Chrome DevTools 连接调试
    • USB 调试的完整流程图
    • DevTools 能做什么
    • 重要警告：上线前必须关闭调试
    • 踩坑记录
    • 写在最后

做 Web 内嵌页开发有个痛点：页面跑在手机上，但 DevTools 在电脑上。想调试 JS、查元素、看网络请求，只能在代码里到处加 console.log，调完还要一条条删掉。 HarmonyOS 的 Web 组件支持接入 Chrome DevTools 进行远程调试，一行代码开启，体验和在 Chrome 桌面端调试本地页面没什么区别。

开启调试模式的方法

核心就是一个静态方法调用：

webview.WebviewController.setWebDebuggingAccess(true);

这个方法是静态方法，不是某个控制器实例的方法，所以不需要先创建 Controller 就能调用。调用时机通常是在页面的 aboutToAppear() 生命周期里，确保 Web 组件加载之前就开启调试。

USB 调试完整代码

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

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

aboutToAppear(): void {
// 在组件即将出现前开启 Web 调试模式
// 注意：这是静态方法，用类名调用，不是 this.controller.xxx
webview.WebviewController.setWebDebuggingAccess(true);
}

build() {
Column() {
Web({ src: 'https://www.example.com', controller: this.controller })
.width('100%')
.height('100%')
}
}
}

权限配置

调试模式需要 ohos.permission.INTERNET 权限（因为调试协议走网络通信），在 module.json5 里声明：

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

用 Chrome DevTools 连接调试

步骤一：USB 连接设备

步骤二：安装并运行应用

把包含 setWebDebuggingAccess(true) 的应用安装到设备并运行，打开包含 Web 组件的页面。

步骤三：用 Chrome 打开调试入口

在电脑的 Chrome 浏览器地址栏输入：

chrome://inspect/#devices

步骤四：发现设备并调试

Chrome 应该能自动发现通过 USB 连接的 HarmonyOS 设备，以及上面运行的 Web 组件页面。点击页面下方的「inspect」按钮，就会弹出完整的 Chrome DevTools 窗口。

USB 调试的完整流程图

DevTools 能做什么

连接成功后，可以使用 Chrome DevTools 的全部功能：

这比满屏 console.log 调试高效得多。

重要警告：上线前必须关闭调试

这个问题很严重，很多开发者忘记处理：

setWebDebuggingAccess(true) 绝对不能带进发布版本。

原因很简单：开启调试模式后，任何连接了 USB 并打开了 chrome://inspect 的人，都可以看到你 Web 组件里的所有内容，执行任意 JS，甚至读取 localStorage 里的数据。对用户来说，这是严重的安全漏洞。

正确做法是用编译条件控制：

aboutToAppear(): void {
// 只在 debug 模式下开启，release 编译时不会包含这行代码
if (process.env.NODE_ENV === 'development') {
webview.WebviewController.setWebDebuggingAccess(true);
}
}

或者使用 HarmonyOS 的 BuildProfile 机制：

import { BuildProfile } from 'BuildProfile';

aboutToAppear(): void {
if (BuildProfile.DEBUG_MODE) {
webview.WebviewController.setWebDebuggingAccess(true);
}
}

这样打 release 包时，DEBUG_MODE 为 false，调试代码就不会执行。

踩坑记录

坑一：setWebDebuggingAccess 必须在 Web 组件渲染前调用

如果在 Web 已经加载完页面后才调用这个方法，调试可能无法正常工作。一定要放在 aboutToAppear() 里。

坑二：部分手机需要手动信任 ADB 连接

初次连接时，手机会弹出"是否信任此电脑"的对话框，一定要点"允许"，否则 Chrome 无法发现设备。

坑三：加载本地文件（$rawfile()）也可以调试

setWebDebuggingAccess(true) 对本地 HTML 文件同样有效，不只是网络地址。调试本地 H5 页面时一样好用。

写在最后

USB 调试这个功能强烈推荐在开发阶段就配置好，一行代码的事，能省掉大量靠肉眼猜 bug 的时间。

但记住——上线版本务必关掉。