HarmonyOS ArkWeb 系列之组件调试与 WebDebuggingAccess：开发阶段必知的调试技巧

文章目录

• • 大白话：为什么 Web 调试比 Native 麻烦？
  • 调试环境搭建流程
  • 第一步：代码中开启调试
  • 第二步：建立 HDC 端口转发
  • 第三步：用 Chrome DevTools 连接
  • 通过 onControllerAttached 在最佳时机注入 JS
  • 生命周期各回调的执行顺序
  • 常见调试场景与对策
  • • 场景1：JS 报错但不知道是哪一行
    • 场景2：网络请求失败
    • 场景3：页面样式错乱
    • 场景4：渲染进程崩溃（onRenderExited）
  • 生产环境关闭调试
  • 小结

内嵌的 Web 页面出了问题，你不知道 JS 有没有执行，样式为什么乱掉，网络请求有没有发出去——这些问题如果没有调试工具，只能靠猜。本文介绍 ArkWeb 调试的完整方案。

大白话：为什么 Web 调试比 Native 麻烦？

调试 Native 代码，你有 DevEco Studio 的断点、变量监视器。但 Web 组件里跑的是 HTML/CSS/JS，这套工具管不到它。

好在 ArkWeb 支持 Chrome DevTools Protocol，开启后可以用 Chrome 浏览器的开发者工具远程调试 Web 组件里的页面，就像调试普通网站一样。

开启的开关就是：webview.WebviewController.setWebDebuggingAccess(true)

调试环境搭建流程

第一步：代码中开启调试

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

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

aboutToAppear(): void {
// 注意：这是静态方法，在 Web 组件创建之前调用
// 只在开发调试阶段开启，发布版本务必关闭或通过编译开关控制
try {
webview.WebviewController.setWebDebuggingAccess(true);
console.info('Web 调试模式已开启');
} catch (error) {
console.error(
`开启调试失败 – Code: ${(error as BusinessError).code}, ` +
`Message: ${(error as BusinessError).message}`
);
}
}

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

重要：setWebDebuggingAccess 是静态方法，影响进程内所有 Web 实例，且必须在 Web 组件构建之前调用（建议放在 aboutToAppear 或 onCreate 里）。

第二步：建立 HDC 端口转发

设备连接电脑后，在终端执行：

# 【HarmonyOS6】查看已连接设备
hdc list targets

# 【HarmonyOS6】建立端口转发（将设备 9222 映射到本机 9222）
hdc fport tcp:9222 tcp:9222

# 【HarmonyOS6】如果有多台设备，指定设备 ID
hdc -t <device-id> fport tcp:9222 tcp:9222

第三步：用 Chrome DevTools 连接

此时你可以：

• Elements 面板：查看/修改 DOM 结构和 CSS 样式
• Console 面板：看 JS 日志、执行 JS 代码
• Network 面板：看所有网络请求、响应内容、耗时
• Sources 面板：给 JS 代码打断点、单步执行
• Performance 面板：分析渲染性能

通过 onControllerAttached 在最佳时机注入 JS

调试时经常需要向页面注入一些辅助脚本。onControllerAttached 是最佳时机——此时 Controller 已绑定但页面还没开始加载：

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

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

build() {
Column() {
Web({ src: 'https://example.com', controller: this.controller })
.onControllerAttached(() => {
// Controller 绑定完成，此时可以安全地执行预初始化操作

// 1. 注册 JS 对象，供网页调用 Native 功能
// this.controller.registerJavaScriptProxy(…)

// 2. 设置自定义 UserAgent
try {
const defaultUA = this.controller.getUserAgent();
this.controller.setCustomUserAgent(defaultUA + ' MyApp/1.0.0');
} catch (e) {
console.error('设置 UA 失败');
}

console.info('onControllerAttached：Controller 已就绪');
})
.onPageBegin((event) => {
// 页面开始加载（URL 确定）
if (event) console.info('开始加载:', event.url);
})
.onProgressChange((event) => {
// 加载进度 0~100
if (event) console.info('加载进度:', event.newProgress + '%');
})
.onFirstContentfulPaint((event) => {
// FCP：页面出现第一个有意义内容的时刻
if (event) {
console.info(
`FCP 时间: ${event.firstContentfulPaintMs}ms`,
`导航开始时刻: ${event.navigationStartTick}`
);
}
})
.onPageEnd((event) => {
// 页面加载完成，此时执行 JS 最安全
if (event) {
console.info('页面加载完成:', event.url);
// 执行 JS 脚本
this.controller.runJavaScript('console.log("页面已加载完成，来自 Native")')
.then(result => console.info('JS 执行结果:', result))
.catch((e: BusinessError) => console.error('JS 执行失败:', e.message));
}
})
.onPageVisible((event) => {
// 页面内容可见（比 onPageEnd 早，此时页面已可见但可能还没完全加载）
console.info('页面可见:', event.url);
})
.onRenderExited((event) => {
// 渲染进程崩溃！
if (event) {
console.error('渲染进程退出，原因:', event.renderExitReason);
// 可在这里尝试重新加载
// this.controller.loadUrl('https://example.com');
}
})
}
.width('100%')
.height('100%')
}
}

生命周期各回调的执行顺序

理清顺序，知道在哪个时机做什么事：

常见调试场景与对策

场景1：JS 报错但不知道是哪一行

开启调试后，Chrome DevTools Console 面板会显示完整的 JS 错误堆栈，包括文件名和行号。

场景2：网络请求失败

Network 面板可以看到每个请求的：

• 请求头/响应头
• 请求体/响应体
• HTTP 状态码
• 耗时（DNS/Connect/TTFB/Download）

场景3：页面样式错乱

Elements 面板可以实时查看 DOM 树，点击元素可以在右侧看到所有生效的 CSS 规则，以及被覆盖（划线）的规则。

场景4：渲染进程崩溃（onRenderExited）

RenderExitReason 枚举值说明：

遇到 ABNORMAL 或 OOM，优先检查页面内存占用，避免加载超大图片或执行内存泄漏的 JS。

生产环境关闭调试

调试开关一定不要带到正式发布版本：

// 推荐做法：通过编译宏或环境变量控制
aboutToAppear(): void {
// 只在 debug 构建中开启
if (BuildProfile.DEBUG_MODE) {
webview.WebviewController.setWebDebuggingAccess(true);
}
}

或者更简单，用 if (__DEV__) 宏（如果你的构建工具支持）。

小结

调试 Web 组件不用再凭感觉，工具用好了问题一目了然。