---

适用场景：

• App 启动后白屏、不渲染 Web 内容。
• 页面偶发白屏、资源加载失败，却难以复现。
• 想在 HarmonyOS 设备上像在浏览器那样调试 Web（查看 console、Network 等）。

从 ArkTS + Cordova + ArkWeb 三层，构建一套可落地的调试与排错方法，代码占比约 3/10。

---

1. 白屏问题分类：先判断是“真白屏”还是“假白屏”

遇到白屏时，先不要慌，先判断：

• 真白屏：WebView 压根没加载页面，连 index.html 都没进来。
• 假白屏：Web 实际已加载，只是由于 CSS/JS 或业务逻辑问题看起来像白屏。

1.1 判别思路图

---

2. 开启 Web 调试与日志：MainPage 的调试开关

2.1 isWebDebug 开关

在 Index.ets 中，MainPage 有一个重要参数：isWebDebug：

// entry/src/main/ets/pages/Index.ets
@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      MainPage({
        isWebDebug: true,   // 开启 Web 调试
        cordovaPlugs: []
      });
    }
    .height('100%')
    .width('100%')
  }
}

在 MainPage.ets 中，对应的处理逻辑类似：

// cordova/src/main/ets/components/MainPage.ets（节选）
aboutToAppear() {
  if (!cordovaWebIdToWebviewGlobe.hasKey(this.webTag)) {
    webview.WebviewController.setWebDebuggingAccess(this.isWebDebug);
    // ... 其余 Cordova 初始化逻辑
  }
}

效果：

• 在支持的环境下，启用远程调试能力（具体调试工具因平台而异）。
• 即使无法使用开发工具，isWebDebug 也常搭配更多日志输出，帮助排错。

2.2 ArkTS 侧日志建议

在关键生命周期与事件回调处添加日志：

aboutToAppear() {
  console.log('[MainPage] aboutToAppear, isWebDebug=' + this.isWebDebug);
  // ... 初始化逻辑
}

@Builder
builder() {
  Column() {
    Stack({ alignContent: Alignment.Top }) {
      Web({ src: this.src, controller: this.webviewController })
        .onPageBegin(event => {
          console.log('[MainPage] onPageBegin: ' + event.url);
        })
        .onProgressChange(event => {
          console.log('[MainPage] onProgressChange: ' + event.newProgress);
        })
        .onPageEnd(event => {
          console.log('[MainPage] onPageEnd: ' + event.url);
          this.splashScreenHide();
        })
        // ... 其它回调
    }
  }
}

用法：

• 观察 onPageBegin/onProgressChange/onPageEnd 是否被调用。
• 若 onPageBegin 都没有被触发，说明 WebView 可能压根没有开始加载。

---

3. Web 控制台与 Network 调试（思路）

具体远程调试方式会因设备与 IDE 版本略有差异，但通用思路是：

• 启用 isWebDebug；
• 使用厂商提供的 Web 调试工具/浏览器 配套功能，连接设备查看：
  • console.log 输出
  • Network 请求与状态（200/404/500）
  • Sources 查看实际加载的 JS 文件

提示：

• 在没有正式 DevTools 的情况下，也可以在页面上临时加一个调试用 textarea 或弹窗，把关键日志直接渲染到页面上。

---

4. 真白屏：WebView 没有加载页面时的排查

4.1 调用链回顾

如果连 onPageBegin 都不触发，通常是以下原因：

• Index.ets 没有渲染 MainPage。
• MainPage 构建时 src 为空或异常。
• ArkWeb 初始化失败（查 native 日志）。

4.2 检查 Index.ets 是否渲染 MainPage

重点确认：

• 是否导入了 MainPage。
• 是否在 build() 中调用了 MainPage。
• 是否设置了宽高为 100%，否则可能被其他组件遮挡。

4.3 检查 src 的最终值

在 MainPage.aboutToAppear 中打印最终 URL：

aboutToAppear() {
  // ... 解析 Hostname、indexPage 等
  if (this.indexPage == '') {
    this.src = 'https://' + this.strTmpUrl + '/www/index.html';
  }
  console.log('[MainPage] final src = ' + this.src);
}

• 如果 this.src 是空字符串 → WebView 不会发起加载。
• 如果 URL 格式明显不对（比如 https:///www/index.html）也会导致白屏。

---

5. 假白屏：Web 已加载但页面看起来是白的

当确认 onPageBegin/onPageEnd 正常调用，而且 Web console 也有输出时，说明页面已经成功加载。这时的“白屏”多半是前端问题。

5.1 CSS 问题：背景与文字同色/被覆盖

• 全局背景色与文本颜色相近。
• 主容器高度为 0 或被定位到屏幕外。

排查方法：

• 在 app.js 中临时加上：

setTimeout(() => {
  const body = document.body;
  body.style.background = '#000';
  body.style.color = '#fff';
  console.log('[Debug] Force body styles');
}, 1000);

• 看看是否能“救活”页面显示。

5.2 JS 报错：脚本中断导致后续渲染逻辑未执行

• 在 Web console 中查看是否有类似 TypeError、ReferenceError。
• 在 app.js 的入口处加一条日志：

console.log('[2048] app.js loaded');

• 若没有打印，说明 app.js 没有成功加载（可能是 404）。

---

6. 资源 404 / 加载失败排查

6.1 使用 Web 调试的 Network 面板

重点关注：

• index.html 是否 200。
• css/style.css、js/app.js 是否 200。
• 是否有资源走错域名或协议（比如预期 https://Host/www/js/app.js，实际请求到了其他域）。

6.2 不依赖 DevTools 的简单探测方法

在 index.html 中添加一个简单的探测脚本：

<script>
  window.addEventListener('load', function () {
    var el = document.createElement('div');
    el.textContent = '资源加载探测：';
    el.style.position = 'fixed';
    el.style.left = '10px';
    el.style.top = '10px';
    el.style.zIndex = '9999';
    el.style.background = 'rgba(0,0,0,0.6)';
    el.style.color = '#fff';
    el.style.padding = '8px 12px';

    var cssOk = !!document.styleSheets.length;
    var jsOk = !!window.Game2048 || !!window.appLoadedFlag; // 依据你实际项目全局变量调整

    el.textContent += ' CSS=' + (cssOk ? 'OK' : 'FAIL');
    el.textContent += ' JS=' + (jsOk ? 'OK' : 'FAIL');
    document.body.appendChild(el);
  });
</script>

说明：

• 这是一个简单但很实用的“自检 HUD”，可以在没有 DevTools 的设备上快速判断 CSS/JS 是否正常加载。

---

7. 端到端排查案例：从白屏到定位错误配置

假设你遇到如下情况：

• 启动 App → 白屏。
• ArkTS 日志仅有 MainPage aboutToAppear，却没有 onPageBegin。

7.1 排查步骤

1. 确认 Index 渲染 MainPage。
2. 打印 this.src，发现为：

https://localhost/www2/index.html

3. 检查 rawfile 目录，实际为：

rawfile/www/index.html

4. 原因：配置中 indexPage/路径被错误设置成了 /www2/index.html。

7.2 修复方式

• 在 Cordova 配置中改回正确路径，或删除自定义 indexPage 让其使用默认的 /www/index.html。

---

8. 综合调试流程图

把上面的步骤汇总成一张流程图，便于在实际项目中套用：

---

9. 小结：三层协同的调试思维

面对 Web 白屏与加载问题，推荐始终从 三层协同 的角度来思考：

• ArkTS 层：
  • Web 引擎是否初始化？
  • MainPage 是否渲染？
  • src 是否正确？
• Cordova/ArkWeb 层：
  • 请求是否发起？
  • 是否启用了必要的调试开关与日志？
• Web 层：
  • 资源是否 200？
  • JS 是否报错？
  • CSS/布局是否导致内容不可见？

有了这套“白屏排查手册”，你可以在 HarmonyOS + Cordova 的混合项目中更有底气地面对复杂的显示问题，而不会被单一层面的信息误导。