鸿蒙Cordova开发踩坑记录：真机调试的“盲盒“

摘要：在模拟器上一切正常，一上真机就白屏。这种时候，如果没有 DevTools，开发者就像在开盲盒。本文介绍了如何开启 HarmonyOS Web 组件的远程调试功能，并通过 Chrome 浏览器对真机上的 H5 页面进行 inspect（审查元素、断点调试、性能分析）。

📦 1. 黑盒里的 bug

真机上的 Webview 默认是不可调试的。你无法右键"检查"，也看不到 console.log 的输出（除非你把日志打到了原生 Logcat 中）。

对于样式兼容性问题（如刘海屏遮挡），或者 JS 执行错误，我们需要一个可视化的调试工具。

🔓 2. 开启调试之门

在 ArkTS 代码中，我们需要显式开启 WebDebugging。

2.1 全局开启

在 EntryAbility.ets 的 onWindowStageCreate 中：

import web_webview from '@ohos.web.webview';

onWindowStageCreate(windowStage: window.WindowStage) {
    // 开启 Web 调试模式
    // 注意：建议只在 Debug 包开启，Release 包关闭
    web_webview.WebviewController.setWebDebuggingAccess(true);
}

这行代码是总开关。开启后，连接 USB 的电脑就能扫描到这个 Webview 实例。

🔌 3. 连接 Chrome DevTools

3.1 端口转发

鸿蒙设备通过 hdc 工具连接。为了让 Chrome 看到设备，我们需要做端口映射。
鸿蒙 Webview 的调试协议通常运行在设备的特定 Unix Domain Socket 上。

在命令行执行：

# 查找 devtools 相关的 socket
hdc shell cat /proc/net/unix | grep devtools
# 输出示例： ... @webview_devtools_remote_12345

# 映射端口 (将本地 9222 映射到设备的 devtools socket)
hdc fport tcp:9222 localabstract:webview_devtools_remote_12345

注意：不同版本的鸿蒙系统，Socket 名称可能不同，有时不需要手动映射，Chrome 可直接识别（如果实现了 ADB 协议兼容）。

3.2 Chrome 访问

打开 Chrome 浏览器，输入：
chrome://inspect/#devices

如果一切顺利，你应该能在 “Remote Target” 列表中看到你的鸿蒙设备以及正在运行的 WebView 页面（Title 和 URL）。

点击 “Inspect”。

🛠️ 4. 调试实战

现在，熟悉的 DevTools 界面出现了！

1. Elements: 实时修改 CSS，调整刘海屏的 Padding，所见即所得。
2. Console: 查看 JS 报错，输入 JS 代码直接控制游戏逻辑（如 window.game.restart()）。
3. Network: 抓包查看接口请求，排查 CORS 或 404 问题。
4. Application: 查看 LocalStorage、Cookies 内容，验证数据存储逻辑。

💡 5. 替代方案：vConsole

如果你在户外，没带电脑，或者环境限制无法 USB 调试。
推荐在 H5 页面中集成 vConsole 或 eruda。

<script src="https://unpkg.com/vconsole/dist/vconsole.min.js"></script>
<script>
  // 只在测试环境初始化
  if (location.href.includes('debug=true')) {
    var vConsole = new VConsole();
  }
</script>

这样，手机屏幕上会出现一个绿色的 “vConsole” 按钮，点击即可查看日志和网络请求。虽然功能不如 Chrome 强大，但用来看报错绰绰有余。

📚 6. 总结

无调试，不开发。
一定要在项目初期就打通真机调试流程。

1. ArkTS 端开启 setWebDebuggingAccess(true)。
2. PC 端准备好 Chrome 和 hdc 环境。
3. 备选方案集成 vConsole。

这三板斧能帮你节省 80% 的盲目猜测时间。