適用場景：

• 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 的混合項目中更有底氣地面對複雜的顯示問題，而不會被單一層面的信息誤導。