ArkWeb 手记 04｜DevTools 调试与缓存清理

前面 01 搞定页面生命周期、02 实现双向 JS 通信、03 解决 rawfile 本地资源 404。

写到这里，你一定会遇到两个很折磨人的问题：H5 里 JS 报错看不到详情，修改了 H5 页面重新跑模拟器，页面还是旧版本，怎么刷新都不变。

我最开始调试 ArkWeb 的时候，修改完 H5 的 JS，模拟器点刷新完全没反应，以为是代码没保存，反复改了半小时，最后才发现是 ArkWeb 缓存。同时没有 DevTools，H5 里面 js 报错只能靠打印日志猜问题，效率极低。

核心误区：ArkWeb 自带独立缓存机制，和浏览器缓存逻辑不一样；而且调试开关需要手动开启，默认是关闭状态。

核心概念一句话讲清

webDebuggingAccess = true 开启 ArkWeb 调试能力，我们可以用 Chrome DevTools 连接模拟器里的 H5 页面，查看 DOM、Console 日志、网络请求；

ArkWeb 的缓存分为内存缓存 + 磁盘缓存，单纯页面刷新清不掉磁盘缓存，开发阶段需要主动调用接口清理。

前置条件：HarmonyOS7，DevEco Studio，沿用 03 的工程。

第一步：开启 ArkWeb 调试开关

复制代码

import { ArkWeb, ArkWebController } from '@kit.ArkWeb';

@Entry
@Component
struct WebDebugDemo {
  controller: ArkWebController = new ArkWebController();

  aboutToAppear() {
    // 开启网页调试，仅开发环境！上线务必注释/删掉
    this.controller.webDebuggingAccess = true;
    this.controller.javascriptEnabled = true;
  }

  build() {
    Column() {
      // 原生按钮：一键清除缓存
      Button("清空ArkWeb缓存")
        .margin(10)
        .onClick(async ()=>{
          // 清除磁盘缓存，不清除cookie
          await this.controller.clearCache(false);
        })
      ArkWeb({
        src: $rawfile("index.html"),
        controller: this.controller
      })
      .width('100%')
      .layoutWeight(1)
    }
  }
}

关键语句拆解：

webDebuggingAccess = true：开启调试。生产包一定要关闭，有安全风险。
clearCache(false)：参数 false = 只清缓存，保留 Cookie；传 true 会同时清空 Cookie 和缓存。
清除缓存是异步方法，必须加await。

第二步：电脑 Chrome 连接模拟器 DevTools

模拟器正常运行项目，ArkWeb 页面加载完成
打开电脑 Chrome 浏览器，地址栏输入 chrome://inspect
在页面列表找到对应 ArkWeb 实例，点击 inspect，调出调试面板
面板可以看 Elements、Console、Network，和普通网页调试操作几乎一样

注意：只能用 PC 端 Chrome，Edge 也可以，别的浏览器不支持这个调试协议。

第三步：开发常用缓存处理方案

方案 1：点击原生按钮手动清缓存（上面代码）

适合边写 H5 边调试，改完代码，点按钮清缓存，刷新页面。

方案 2：每次打开页面自动清除缓存（开发用）

复制代码

aboutToAppear() {
  this.controller.webDebuggingAccess = true;
  this.controller.javascriptEnabled = true;
  // 页面打开自动清空缓存
  this.controller.clearCache(false);
}

缺点：每次进入页面都会重新拉取资源，页面加载变慢，上线绝对不要这么写。

方案 3：rawfile 本地资源的特殊缓存坑

rawfile 打包进 hap 包，单纯清 ArkWeb 缓存有时候依旧加载旧文件。

✅解决办法：修改 html/js/css 之后，重新 Build 项目，不是只点模拟器刷新。

高频踩坑清单（重点）

❌ 打开 chrome://inspect 找不到设备页面
✅ 检查：模拟器正常在线；代码开启 webDebuggingAccess；重新编译运行工程；重启 DevEco 模拟器。
❌ DevTools 控制台中文日志乱码
✅ 不用额外配置，HarmonyOS7 新版模拟器基本修复；实在乱码就把日志改成英文打印。
❌ clearCache 调用后缓存依旧存在
✅ clearCache 是异步，忘记加 await；rawfile 资源修改必须重新 build，光清 ArkWeb 缓存没用。
❌ 上线版本保留 webDebuggingAccess=true
✅ 上线打包前注释，这个接口会允许外部调试页面，存在安全隐患。

小扩展：禁用缓存（远程 H5 页面场景）

如果加载的是线上 https 远程页面，可以在加载前设置缓存模式

复制代码

// 开发环境：每次都从网络拉取，不读取缓存
this.controller.cacheMode = WebCacheMode.NO_CACHE;

WebCacheMode 一共 4 种：NO_CACHE / NORMAL / ONLY_CACHE / DEFAULT，开发和生产按需切换。