Web页面白屏问题的排查步骤和解决方法

Web页面出现白屏的原因众多，本文列举了若干常见白屏问题的排查步骤，供开发者快速定位。

1.首先排查权限和网络状态。

2.通过使用DevTools工具调试前端页面定位具体报错类型（跨域、资源404、JS异常）。

3.在复杂布局场景中，排查渲染模式及组件约束条件的问题。

4.处理H5代码兼容性问题。

5.从日志中排查生命周期和网络加载相关关键字。

检查权限和网络状态

如果应用未开启联网或文件访问权限或者设备网络状态不佳，将导致Web组件加载失败或页面元素缺失，进而引起白屏。

验证设备的网络状态，包括是否已连接网络，设备自带的浏览器能否正常访问网页等（在线页面场景）。

确保应用已添加网络权限：ohos.permission.INTERNET（在线页面必需）。

// 在module.json5中添加相关权限
"requestPermissions":[
 {
  "name":"ohos.permission.INTERNET"
 }
]

开启相关权限：

// xxx.ets
import{ webview }from'@kit.ArkWeb';
@Entry
@Component
structWebComponent{
controller: webview.WebviewController=newwebview.WebviewController();
build() {
 Column() {
  Web({src:'www.example.com',controller:this.controller})
    .domStorageAccess(true)
    .fileAccess(true)
    .imageAccess(true)
    .onlineImageAccess(true)
    .javaScriptAccess(true)
  }
 }
}

修改UserAgent后再观察页面是否恢复正常。

// xxx.ets
import{ webview }from'@kit.ArkWeb';
import{BusinessError}from'@kit.BasicServicesKit';
@Entry
@Component
structWebComponent{
controller: webview.WebviewController=newwebview.WebviewController();
@StatecustomUserAgent:string=' DemoApp';
build() {
 Column() {
  Web({src:'www.example.com',controller:this.controller})
   .onControllerAttached(() =>{
   console.log("onControllerAttached");
   try{
    letuserAgent =this.controller.getUserAgent() +this.customUserAgent;
    this.controller.setCustomUserAgent(userAgent);
    }catch(error) {
    console.error(`ErrorCode:${(errorasBusinessError).code}, Message:${(errorasBusinessError).message}`);
    }
   })
  }
 }
}

使用DevTools工具进行页面内容验证

在确保网络与权限配置无误后，若仍出现白屏，则应利用DevTools工具调试前端页面以及监听Web相关错误上报接口，来定位具体报错类型。

1.查阅控制台的错误信息，定位具体的资源加载失败问题。资源加载失败会导致页面元素缺失，布局紊乱，图片和动画效果失效等，严重时可能导致渲染进程崩溃，页面呈现空白。如图所示，依次排查：

（1）元素是否完整，html元素、结构是否正确。

（2）控制台是否有报错。

（3）网络里面是否有资源加载时间特别长等。

2.检查控制台，确认是否存在因MixedContent策略或CORS策略导致的异常，或JS错误等。可参考解决Web组件本地资源跨域问题。为了提高安全性，ArkWeb内核禁止file协议和resource协议访问跨域请求。因此，在使用Web组件加载本地离线资源的时候，Web组件会拦截file协议和resource协议的跨域访问。Web组件无法访问本地跨域资源时，DevTools控制台会显示报错信息：

Accesstoscriptat'xxx'fromorigin'xxx'has been blockedbyCORS policy:Crossorigin requestsareonlysupportedforprotocol schemes:  http, arkweb, data, chrome-extension, chrome, https, chrome-untrusted.

有如下两种解决方法：

方法一：

开发者应使用http或https协议替代file或resource协议，确保Web组件能够成功访问跨域资源。替代的URL域名应为自定义构造，仅限于个人或组织使用，以防止与互联网上的实际域名冲突。此外，开发者需要利用Web组件的onInterceptRequest方法，对本地资源进行拦截和相应替换。

以下结合示例说明如何使用http或者https等协议解决本地资源跨域访问失败的问题。其中，index.html和js/script.js文件置于工程的rawfile目录下。当使用resource协议访问index.html时，js/script.js文件因跨域而被拦截，无法加载。在示例中，使用https://www.example.com/域名替换了原有的resource协议，同时利用onInterceptRequest接口替换资源，确保js/script.js文件可以成功加载，从而解决跨域拦截问题。

// main/ets/pages/Index.ets
import{ webview }from'@kit.ArkWeb';
@Entry
@Component
structIndex{
@Statemessage:string='Hello World';
webviewController: webview.WebviewController=newwebview.WebviewController();
// 构造域名和本地文件的映射表
 schemeMap =newMap([
  ["https://www.example.com/index.html","index.html"],
  ["https://www.example.com/js/script.js","js/script.js"],
 ])
// 构造本地文件和构造返回的格式mimeType
 mimeTypeMap =newMap([
  ["index.html",'text/html'],
  ["js/script.js","text/javascript"]
 ])
build() {
 Row() {
  Column() {
   // 针对本地index.html,使用http或者https协议代替file协议或者resource协议，并且构造一个属于自己的域名。
   // 本例中构造www.example.com为例。
   Web({src:"https://www.example.com/index.html",controller:this.webviewController})
     .javaScriptAccess(true)
     .fileAccess(true)
     .domStorageAccess(true)
     .geolocationAccess(true)
     .width("100%")
     .height("100%")
     .onInterceptRequest((event) =>{
     if(!event) {
      return;
      }
     // 此处匹配自己想要加载的本地离线资源，进行资源拦截替换，绕过跨域
     if(this.schemeMap.has(event.request.getRequestUrl())) {
      letrawfileName:string=this.schemeMap.get(event.request.getRequestUrl())!;
      letmimeType =this.mimeTypeMap.get(rawfileName);
      if(typeofmimeType ==='string') {
       letresponse =newWebResourceResponse();
       // 构造响应数据，如果本地文件在rawfile下，可以通过如下方式设置
        response.setResponseData($rawfile(rawfileName));
        response.setResponseEncoding('utf-8');
        response.setResponseMimeType(mimeType);
        response.setResponseCode(200);
        response.setReasonMessage('OK');
        response.setResponseIsReady(true);
       returnresponse;
       }
      }
     returnnull;
     })
   }
   .width('100%')
  }
  .height('100%')
 }
}

// main/resources/rawfile/js/script.js
constbody =document.body;
constelement =document.createElement('div');
element.textContent='success';
body.appendChild(element);

方法二：

通过setPathAllowingUniversalAccess设置一个路径列表。当使用file协议访问该列表中的资源时，允许进行跨域访问本地文件。此外，一旦设置了路径列表，file协议将仅限于访问列表内的资源(此时，fileAccess的行为将会被此接口行为覆盖)。路径列表中的路径应符合以下任一路径格式：

1.应用文件目录通过Context.filesDir获取，其子目录示例如下：

/data/storage/el2/base/files/example

/data/storage/el2/base/haps/entry/files/example

2.应用资源目录通过Context.resourceDir获取，其子目录示例如下：

/data/storage/el1/bundle/entry/resource/resfile

/data/storage/el1/bundle/entry/resource/resfile/example

当路径列表中的任一路径不满足上述条件时，系统将抛出异常码401，并判定路径列表设置失败。如果路径列表设置为空，file协议的可访问范围将遵循fileAccess规则，具体示例如下。

// main/ets/pages/Index.ets
import{ webview }from'@kit.ArkWeb';
import{BusinessError}from'@kit.BasicServicesKit';
@Entry
@Component
structWebComponent{
controller:WebviewController=newwebview.WebviewController();
uiContext:UIContext=this.getUIContext();
build() {
 Row() {
  Web({src:"",controller:this.controller})
    .onControllerAttached(() =>{
    try{
     // 设置允许可以跨域访问的路径列表
     this.controller.setPathAllowingUniversalAccess([
      this.uiContext.getHostContext()!.resourceDir,
      this.uiContext.getHostContext()!.filesDir+"/example"
      ])
     this.controller.loadUrl("file://"+this.uiContext.getHostContext()!.resourceDir+"/index.html")
     }catch(error) {
     console.error(`ErrorCode:${(errorasBusinessError).code}, Message:${(errorasBusinessError).message}`);
     }
    })
    .javaScriptAccess(true)
    .fileAccess(true)
    .domStorageAccess(true)
  }
 }
}

 



 
 
 
 



 loadFile