HarmonyOS鸿蒙Next中webview白屏

HarmonyOS鸿蒙Next中webview白屏

HarmonyOS 使用webview加载H5页面,显示白屏,URL通过浏览器可以正常访问。API20+

@react-native-ohos/react-native-webview 13.15.1 RN版本0.77

9 回复

既然降到 13.10.5 可以恢复,优先按 13.15.1 的 RN WebView 适配回归来处理。建议保留一个最小复现:同一个 URL、同一台设备、同一 RN 版本,仅切换 webview 版本;同时把 onError/onHttpError/onLoadStart/onLoadEnd 日志、页面是否依赖 JS/DOMStorage、是否有混合内容或证书问题一起打出来。若原生 ArkTS Web 组件能正常加载,而 RN WebView 13.15.1 白屏,就更能定位到桥接层或该版本组件问题。线上先锁定 13.10.5,后续等组件版本修复再升级。

更多关于HarmonyOS鸿蒙Next中webview白屏的实战系列教程也可以访问 https://www.itying.com/category-93-b0.html


这个问题我倾向先按两条线看:

  1. Web 页面资源在 WebView 里被拦截了
  2. RN 0.77 + @react-native-ohos/react-native-webview 13.15.1 组合存在兼容问题

因为你描述的是:

  • 浏览器能正常打开
  • HarmonyOS WebView 白屏
  • 还是 RN OHOS 适配包

这类情况很常见地不是“URL 不通”,而是 WebView 环境和系统浏览器环境不一致

先给结论

优先怀疑顺序建议是:

  1. ohos.permission.INTERNET 是否声明
  2. H5 是否有 http/https 混合内容、CORS、证书、重定向问题
  3. H5 是否依赖特定 User-Agent 或 Web 能力
  4. @react-native-ohos/react-native-webview 13.15.1RN 0.77 的兼容性问题

华为官方关于 Web 白屏排查里明确提到:

另外,我检索到一个和你描述几乎一致的同类反馈,环境也是:

  • RN 0.77
  • @react-native-ohos/react-native-webview 13.15.1

摘要里提到 通过降低版本解决了白屏问题,说明这个版本组合本身就值得重点怀疑:同类问题讨论

先做 5 个快速检查

1. 检查网络权限

确认模块里已经声明:

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  }
]

注意:

  • 浏览器能访问,不代表你的 App WebView 有联网权限
  • 这是最容易漏掉的一项

2. 用最小页面做对照测试

先分别测试这 3 类页面:

  • 一个纯静态 HTTPS 页
  • 你的目标 H5 页
  • 一个你自己最简单的测试页,只放一行 HTML

如果:

  • 简单页能开,业务 H5 白屏
    说明是 页面兼容 / 资源加载 / 脚本执行 问题

如果:

  • 所有页都白屏
    更像是 权限 / 组件兼容 / 容器初始化 问题

3. 打开 WebView 事件日志

先把这些事件都挂上:

  • onLoadStart
  • onLoadProgress
  • onLoadEnd
  • onError
  • onHttpError

重点看:

  • 有没有进入 onLoadStart
  • 是否卡在某个进度
  • 是否抛出证书、重定向、资源加载失败错误

如果 onLoadStart 有,onLoadEnd 没有,通常是中途资源或脚本挂了。

4. 检查混合内容和跨域

如果你的页面是 https://... ,但内部资源还有:

  • http://...js
  • http://...css
  • http://...img

或者用了 file/resource 协议跨域访问资源,就很容易白屏。

华为官方文档也提到,Web 组件里跨域资源如果协议不合规,会被 CORS 拦掉,建议统一使用 http/https 协议资源:Web 白屏官方说明

5. 检查 UA 适配

有些 H5 会根据 UA 判断平台,然后走不同分支:

  • 浏览器里正常
  • WebView 里被识别成不支持的环境
  • 最终脚本分支直接空白

尤其如果页面里做了:

  • 平台探测
  • WebGL/音视频能力判断
  • 登录态注入
  • JSBridge 探测

就更容易出现“浏览器正常、内嵌白屏”。

RN 侧建议先这样测

你可以先用一个尽量保守的写法测一下:

<WebView
  source={{ uri: 'https://你 的地址' }}
  javaScriptEnabled={true}
  domStorageEnabled={true}
  originWhitelist={['*']}
  mixedContentMode="always"
  onLoadStart={() => console.log('load start')}
  onLoadProgress={(e) => console.log('progress', e.nativeEvent)}
  onLoadEnd={() => console.log('load end')}
  onError={(e) => console.log('error', e.nativeEvent)}
  onHttpError={(e) => console.log('http error', e.nativeEvent)}
/>

重点看两件事:

  • 开启 domStorageEnabled
  • 临时把 mixedContentMode 放开,先验证是不是混合内容导致

如果这样能显示,说明问题就基本锁定在页面资源策略上了。

这个版本组合我建议重点验证

你当前组合:

  • RN 0.77
  • @react-native-ohos/react-native-webview 13.15.1

我会把它列为高优先级怀疑项。

因为已经有同类反馈提到,同版本场景下鸿蒙白屏,而降版本后恢复。所以建议你直接做一组 A/B 对照:

  • 保持 RN 0.77 不动,降 @react-native-ohos/react-native-webview
  • 或保持 webview 不动,换一个更稳定的 RN 版本验证

如果你们是“三端一套代码”,安卓和 iOS 正常、只有 OHOS 白屏,这种情况非常像 OHOS 适配包版本问题,不是业务 H5 本身坏了。

最建议的排查顺序

  1. 确认 ohos.permission.INTERNET
  2. 给 WebView 加全量事件日志
  3. 用最小 HTTPS 页面做对照
  4. 打开 domStorageEnabled
  5. 临时试 mixedContentMode="always"
  6. 检查 H5 是否有 UA / JSBridge / CORS / http 资源依赖
  7. 最后直接验证 13.15.1 降版本

我的判断

如果让我按概率排:

  • 第一梯队:版本兼容问题
  • 第二梯队INTERNET / mixed content / CORS / DOM storage
  • 第三梯队:页面依赖特定 UA 或 Web 能力

@react-native-ohos/react-native-webview 13.10.5
目前通过降低版本解决了白屏问题

开发者你好,问题已收到,正在处理中。

项目用的RN0.77版本。一套代码编译3端。鸿蒙使用的是@react-native-ohos/react-native-webview 13.15.1版本。在鸿蒙手机上,webview 展示不了页面。安卓和IOS使用的react-native-webview 正常展示

这里有官方文档:

定位与解决Web白屏问题

官方文档链接

不是用arkTS写的,代码是RN的,0.77.这个版本可以编译成鸿蒙代码。这个官方文档已经看过了。目前在排查和鸿蒙原生的桥接是否有问题

在HarmonyOS Next中,WebView白屏常见原因:网络权限未在module.json5中声明ohos.permission.INTERNET;WebViewController未正确绑定;加载的URL无效或被拦截;HTTPS证书校验失败;或ArkUI组件渲染异常。请确认以上配置与代码。,

白屏通常由网络权限或混合内容加载策略引起。在使用 @react-native-ohos/react-native-webview 加载 HTTPS 链接时,若页面包含 HTTP 资源或证书校验未通过,Web 组件默认会拦截并导致白屏。

解决方案:

在原生侧 EntryAbility 中,通过 resourceManager 注册 rawfile 下的证书文件,并配置 Web 组件模式。关键配置示例:

// 在 aboutToAppear 或 RN 调用原生前设置
webview.WebviewController.setWebDebuggingAccess(true);
// 针对 HTTPS 加载 HTTP 资源白屏,设置混合内容模式
this.webConfig = {
  mixedMode: webview.MixedMode.All, // 允许加载不安全的 HTTP 内容
  // 若需要忽略证书错误(仅调试用)
  // enableNativeMediaPlayer: false,
};

确保 module.json5 中已申请 ohos.permission.INTERNET 权限。

回到顶部