1# 定位与解决Web白屏问题 2<!--Kit: ArkWeb--> 3<!--Subsystem: Web--> 4<!--Owner: @yp99ustc--> 5<!--Designer: @LongLie--> 6<!--Tester: @ghiker--> 7<!--Adviser: @HelloCrease--> 8 9Web页面出现白屏的原因众多，本文列举了若干常见白屏问题的排查步骤，供开发者快速定位。 10 111. 首先排查权限和网络状态。 122. 通过[使用DevTools工具调试前端页面](web-debugging-with-devtools.md)定位具体报错类型（跨域、资源404、JS异常）。 133. 在复杂布局场景中，排查渲染模式及组件约束条件的问题。 144. 处理H5代码兼容性问题。 155. 从日志中排查生命周期和网络加载相关关键字。 16 17## 检查权限和网络状态 18如果应用未开启联网或文件访问权限或者设备网络状态不佳，将导致Web组件加载失败或页面元素缺失，进而引起白屏。 19* 验证设备的网络状态，包括是否已连接网络，设备自带的浏览器能否正常访问网页等（在线页面场景）。 20* 确保应用已添加网络权限：ohos.permission.INTERNET（在线页面必需）。 21 ``` 22 // 在module.json5中添加相关权限 23 "requestPermissions":[ 24 { 25 "name" : "ohos.permission.INTERNET" 26 } 27 ] 28 ``` 29* 开启相关权限： 30 | 名称 | 说明 | 31 | ---- | -------------------------------- | 32 | [domStorageAccess](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#domstorageaccess) | DOM Storage API权限，若不开启，无法使用localStorage存储数据，任何调用localStorage的代码都将失效，依赖本地存储的功能会异常。 | 33 | [fileAccess](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#fileaccess) | 若不开启，文件读写功能完全被阻断，依赖文件的模块会崩溃。 | 34 | [imageAccess](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#imageaccess) | 设置是否允许自动加载图片资源。 | 35 | [onlineImageAccess](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#onlineimageaccess) | 设置是否允许从网络加载图片资源（通过HTTP和HTTPS访问的资源）。 | 36 | [javaScriptAccess](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#javascriptaccess) | 设置是否允许执行JavaScript脚本。 | 37 38 39 ```ts 40 // xxx.ets 41 import { webview } from '@kit.ArkWeb'; 42 43 @Entry 44 @Component 45 struct WebComponent { 46 controller: webview.WebviewController = new webview.WebviewController(); 47 48 build() { 49 Column() { 50 Web({ src: 'www.example.com', controller: this.controller }) 51 .domStorageAccess(true) 52 .fileAccess(true) 53 .imageAccess(true) 54 .onlineImageAccess(true) 55 .javaScriptAccess(true) 56 } 57 } 58 } 59 ``` 60* 修改[UserAgent](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#setcustomuseragent10)后再观察页面是否恢复正常。 61 62 ```ts 63 // xxx.ets 64 import { webview } from '@kit.ArkWeb'; 65 import { BusinessError } from '@kit.BasicServicesKit'; 66 67 @Entry 68 @Component 69 struct WebComponent { 70 controller: webview.WebviewController = new webview.WebviewController(); 71 @State customUserAgent: string = ' DemoApp'; 72 73 build() { 74 Column() { 75 Web({ src: 'www.example.com', controller: this.controller }) 76 .onControllerAttached(() => { 77 console.info("onControllerAttached"); 78 try { 79 let userAgent = this.controller.getUserAgent() + this.customUserAgent; 80 this.controller.setCustomUserAgent(userAgent); 81 } catch (error) { 82 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 83 } 84 }) 85 } 86 } 87 } 88 ``` 89## 使用DevTools工具进行页面内容验证 90在确保网络与权限配置无误后，若仍出现白屏，则应利用DevTools工具调试前端页面以及监听Web相关错误上报接口，来定位具体报错类型。 91 921. 查阅控制台的错误信息，定位具体的资源加载失败问题。资源加载失败会导致页面元素缺失，布局紊乱，图片和动画效果失效等，严重时可能导致渲染进程崩溃，页面呈现空白。如图所示，依次排查：<br> 93 （1）元素是否完整，html元素、结构是否正确。<br> （2）控制台是否有报错。<br>（3）网络里面是否有资源加载时间特别长等。<br> 94  95 962. 检查控制台，确认是否存在因MixedContent策略或CORS策略导致的异常，或JS错误等。可参考[解决Web组件本地资源跨域问题](web-cross-origin.md)。为了提高安全性，ArkWeb内核禁止file协议和resource协议访问跨域请求。因此，在使用Web组件加载本地离线资源的时候，Web组件会拦截file协议和resource协议的跨域访问。Web组件无法访问本地跨域资源时，DevTools控制台会显示报错信息： 97 ``` 98 Access to script at 'xxx' from origin 'xxx' has been blocked by CORS policy: Cross origin requests are only supported for protocol schemes: http, arkweb, data, chrome-extension, chrome, https, chrome-untrusted. 99 ``` 100 有如下两种解决方法： 101 102 方法一： 103 104 开发者应使用http或https协议替代file或resource协议，确保Web组件能够成功访问跨域资源。替代的URL域名应为自定义构造，仅限于个人或组织使用，以防止与互联网上的实际域名冲突。此外，开发者需要利用Web组件的[onInterceptRequest](../reference/apis-arkweb/arkts-basic-components-web-events.md#oninterceptrequest9)方法，对本地资源进行拦截和相应替换。 105 106 以下结合示例说明如何使用http或者https等协议解决本地资源跨域访问失败的问题。其中，index.html和js/script.js文件置于工程的rawfile目录下。当使用resource协议访问index.html时，js/script.js文件因跨域而被拦截，无法加载。在示例中，使用https:\//www\.example.com/域名替换了原有的resource协议，同时利用onInterceptRequest接口替换资源，确保js/script.js文件可以成功加载，从而解决跨域拦截问题。 107 ```ts 108 // main/ets/pages/Index.ets 109 import { webview } from '@kit.ArkWeb'; 110 111 @Entry 112 @Component 113 struct Index { 114 @State message: string = 'Hello World'; 115 webviewController: webview.WebviewController = new webview.WebviewController(); 116 // 构造域名和本地文件的映射表 117 schemeMap = new Map([ 118 ["https://www.example.com/index.html", "index.html"], 119 ["https://www.example.com/js/script.js", "js/script.js"], 120 ]) 121 // 构造本地文件和构造返回的格式mimeType 122 mimeTypeMap = new Map([ 123 ["index.html", 'text/html'], 124 ["js/script.js", "text/javascript"] 125 ]) 126 127 build() { 128 Row() { 129 Column() { 130 // 针对本地index.html,使用http或者https协议代替file协议或者resource协议，并且构造一个属于自己的域名。 131 // 本例中构造www.example.com为例。 132 Web({ src: "https://www.example.com/index.html", controller: this.webviewController }) 133 .javaScriptAccess(true) 134 .fileAccess(true) 135 .domStorageAccess(true) 136 .geolocationAccess(true) 137 .width("100%") 138 .height("100%") 139 .onInterceptRequest((event) => { 140 if (!event) { 141 return; 142 } 143 // 此处匹配自己想要加载的本地离线资源，进行资源拦截替换，绕过跨域 144 if (this.schemeMap.has(event.request.getRequestUrl())) { 145 let rawfileName: string = this.schemeMap.get(event.request.getRequestUrl())!; 146 let mimeType = this.mimeTypeMap.get(rawfileName); 147 if (typeof mimeType === 'string') { 148 let response = new WebResourceResponse(); 149 // 构造响应数据，如果本地文件在rawfile下，可以通过如下方式设置 150 response.setResponseData($rawfile(rawfileName)); 151 response.setResponseEncoding('utf-8'); 152 response.setResponseMimeType(mimeType); 153 response.setResponseCode(200); 154 response.setReasonMessage('OK'); 155 response.setResponseIsReady(true); 156 return response; 157 } 158 } 159 return null; 160 }) 161 } 162 .width('100%') 163 } 164 .height('100%') 165 } 166 } 167 ``` 168 169 ```html 170 <!-- main/resources/rawfile/index.html --> 171 <html> 172 <head> 173 <meta name="viewport" content="width=device-width,initial-scale=1"> 174 </head> 175 <body> 176 <script crossorigin src="./js/script.js"></script> 177 </body> 178 </html> 179 ``` 180 181 ```js 182 // main/resources/rawfile/js/script.js 183 const body = document.body; 184 const element = document.createElement('div'); 185 element.textContent = 'success'; 186 body.appendChild(element); 187 ``` 188 189 方法二： 190 191 通过[setPathAllowingUniversalAccess](../reference/apis-arkweb/arkts-apis-webview-WebviewController.md#setpathallowinguniversalaccess12)设置一个路径列表。当使用file协议访问该列表中的资源时，允许进行跨域访问本地文件。此外，一旦设置了路径列表，file协议将仅限于访问列表内的资源(此时，[fileAccess](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#fileaccess)的行为将会被此接口行为覆盖)。路径列表中的路径应符合以下任一路径格式： 192 193 1.应用文件目录通过[Context.filesDir](../reference/apis-ability-kit/js-apis-inner-application-context.md#context)获取，其子目录示例如下： 194 195 * /data/storage/el2/base/files/example 196 * /data/storage/el2/base/haps/entry/files/example 197 198 2.应用资源目录通过[Context.resourceDir](../reference/apis-ability-kit/js-apis-inner-application-context.md#context)获取，其子目录示例如下： 199 200 * /data/storage/el1/bundle/entry/resource/resfile 201 * /data/storage/el1/bundle/entry/resource/resfile/example 202 203 当路径列表中的任一路径不满足上述条件时，系统将抛出异常码401，并判定路径列表设置失败。如果路径列表设置为空，file协议的可访问范围将遵循[fileAccess](../reference/apis-arkweb/arkts-basic-components-web-attributes.md#fileaccess)规则，具体示例如下。 204 205 ```ts 206 // main/ets/pages/Index.ets 207 import { webview } from '@kit.ArkWeb'; 208 import { BusinessError } from '@kit.BasicServicesKit'; 209 210 @Entry 211 @Component 212 struct WebComponent { 213 controller: WebviewController = new webview.WebviewController(); 214 uiContext: UIContext = this.getUIContext(); 215 216 build() { 217 Row() { 218 Web({ src: "", controller: this.controller }) 219 .onControllerAttached(() => { 220 try { 221 // 设置允许可以跨域访问的路径列表 222 this.controller.setPathAllowingUniversalAccess([ 223 this.uiContext.getHostContext()!.resourceDir, 224 this.uiContext.getHostContext()!.filesDir + "/example" 225 ]) 226 this.controller.loadUrl("file://" + this.uiContext.getHostContext()!.resourceDir + "/index.html") 227 } catch (error) { 228 console.error(`ErrorCode: ${(error as BusinessError).code}, Message: ${(error as BusinessError).message}`); 229 } 230 }) 231 .javaScriptAccess(true) 232 .fileAccess(true) 233 .domStorageAccess(true) 234 } 235 } 236 } 237 ``` 238 239 ```html 240 <!-- main/resources/resfile/index.html --> 241 <!DOCTYPE html> 242 <html lang="en"> 243 244 <head> 245 <meta charset="utf-8"> 246 <title>Demo</title> 247 <meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no, viewport-fit=cover"> 248 <script> 249 function getFile() { 250 var file = "file:///data/storage/el1/bundle/entry/resources/resfile/js/script.js"; 251 // 使用file协议通过XMLHttpRequest跨域访问本地js文件。 252 var xmlHttpReq = new XMLHttpRequest(); 253 xmlHttpReq.onreadystatechange = function(){ 254 console.info("readyState:" + xmlHttpReq.readyState); 255 console.info("status:" + xmlHttpReq.status); 256 if(xmlHttpReq.readyState == 4){ 257 if (xmlHttpReq.status == 200) { 258 // 如果ets侧正确设置路径列表，则此处能正常获取资源 259 const element = document.getElementById('text'); 260 element.textContent = "load " + file + " success"; 261 } else { 262 // 如果ets侧不设置路径列表，则此处会触发CORS跨域检查错误 263 const element = document.getElementById('text'); 264 element.textContent = "load " + file + " failed"; 265 } 266 } 267 } 268 xmlHttpReq.open("GET", file); 269 xmlHttpReq.send(null); 270 } 271 </script> 272 </head> 273 274 <body> 275 <div class="page"> 276 <button id="example" onclick="getFile()">loadFile</button> 277 </div> 278 <div id="text"></div> 279 </body> 280 281 </html> 282 ``` 283 284 ```javascript 285 // main/resources/resfile/js/script.js 286 const body = document.body; 287 const element = document.createElement('div'); 288 element.textContent = 'success'; 289 body.appendChild(element); 290 ``` 291 2923. 查看onErrorReceive、onHttpErrorReceive、onSslErrorEvent、onHttpAuthRequest、onClientAuthenticationRequest等错误上报接口是否有被调用。请根据返回的错误码，对照[网络协议栈错误列表](../reference/apis-arkweb/arkts-apis-netErrorList.md)进行排查。 293 294 | 名称 | 说明 | 295 | ---- | -------------------------------- | 296 | [onErrorReceive](../reference/apis-arkweb/arkts-basic-components-web-events.md#onerrorreceive) | 资源加载失败会上报该回调，比如访问内核不支持的scheme， 会报302(UNKNOWN_URL_SCHEME)。 | 297 | [onHttpErrorReceive](../reference/apis-arkweb/arkts-basic-components-web-events.md#onhttperrorreceive) | 服务器返回HTTP错误码，这类问题一般需要跟服务器进行联调。 | 298 | [onHttpAuthRequest](../reference/apis-arkweb/arkts-basic-components-web-events.md#onhttpauthrequest9) | 服务器返回407需要端侧提供用户名密码认证，如果不正确处理，可能会导致加载异常、白屏。 | 299 | [onClientAuthenticationRequest](../reference/apis-arkweb/arkts-basic-components-web-events.md#onclientauthenticationrequest9) | 服务器向端侧请求证书，如果不正确处理，会导致页面加载异常。 | 300 | [onSslErrorEvent](../reference/apis-arkweb/arkts-basic-components-web-events.md#onsslerrorevent12) | 证书错误，需要应用根据证书错误信息进行排查，是证书配错了？还是过期了。 | 301 302 303## 复杂的布局与渲染模式导致白屏 304若页面使用了复杂布局或渲染模式，需注意其应用场景和约束条件，不当使用可能导致布局混乱或白屏。 305Web组件提供了两种渲染模式，能够根据不同的容器大小进行适配，从而满足使用场景中对容器尺寸的需求，详情见[Web组件渲染模式](web-render-mode.md)。在使用过程中需要注意以下几点： 306- 异步渲染模式下（renderMode: [RenderMode](../reference/apis-arkweb/arkts-basic-components-web-e.md#rendermode12).ASYNC_RENDER），Web组件的宽高不能超过7,680px（物理像素），超过会导致白屏。 307 308Web组件提供了自适应页面布局的能力，详情见[ Web组件大小自适应页面内容布局](web-fit-content.md)，使用时也需要注意以下约束条件： 309- 配置同步渲染模式：`webSetting({renderingMode: WebRenderingMode.SYNCHRONOUS})`。 310- 关闭滚动效果：`webSetting({overScrollMode: OverScrollMode.NEVER})`。 311- 此模式下不支持动态调整组件高度，确保页面高度固定。 312- 避免在FIT_CONTENT模式下启用键盘避让属性RESIZE_CONTENT，以免导致布局失效。 313- css样式`height：<number> vh`和Web组件大小自适应页面布局存在计算冲突，请检查`height：<number> vh`是否是由body节点而内的第一个高度css样式。如以下结构，id为2的dom节点高度将为0，导致白屏。 314 315 ``` 316 <body> 317 <div id = "1"> 318 <div id = "2" style = "height: 100vh">子dom</div> 319 <div id = "3" style = "height: 20px">子dom</div> 320 </div> 321 </body> 322 ``` 323 解决此白屏问题的参考方案如下： 324 - 子dom使用具体高度样式撑开父元素。 325 ``` 326 <body> 327 <div id = "1"> 328 <div id = "2"><div style = "height: 20px"><div/></div> 329 <div id = "3" style = "height: 20px">子dom</div> 330 </div> 331 </body> 332 ``` 333 - 父元素使用实际高度样式。 334 ``` 335 <body> 336 <div id = "1"> 337 <div id = "2" style = "height: 20px">子dom</div> 338 <div id = "3" style = "height: 20px">子dom</div> 339 </div> 340 </body> 341 ``` 342 343## 处理H5代码兼容性 344兼容性问题处理不当也会导致页面白屏。 345* 特殊协议拦截。 346* 若H5页面调用tel:、mailto:等协议导致白屏，需通过onInterceptRequest拦截并调用系统拨号能力： 347 ```c 348 .onInterceptRequest((event) => { 349 if (event.request.url.startsWith('tel:')) { 350 // 调用系统拨号能力 351 call.makeCall({ phoneNumber: '123456' }); 352 return { responseCode: 404 }; // 阻止默认行为 353 } 354 return null; 355 }) 356 ``` 357## 监控内存与生命周期 358内存达到阈值会导致渲染进程被终止，从而引发白屏现象；同样，渲染进程创建失败或非正常销毁也会导致白屏。可从日志中排查原因。检查Web组件是否与WebController正确绑定，或是否因过早释放导致白屏。关注日志中与Render进程相关的信息：是否存在内存泄漏使渲染内存不足。关键字“MEMORY_PRESSURE_LEVEL_CRITICAL”表明内存已达到阈值，此情形下Web可能遭遇黑屏、花屏或闪屏等异常状况，需排查是否存在内存泄漏问题。Render进程是否成功启动或异常退出。 359 360下面列举一些日志中的关键字和对应的情况说明： 361 362| 日志关键字 | 说明 | 363| ---- | -------------------------------- | 364| StartRenderProcess failed | 渲染render进程启动失败。 | 365| MEMORY_PRESSURE_LEVEL_CRITICAL | 整机内存压力达到阈值，继续使用可能造成黑屏、闪屏白屏等问题。 | 366| crashpad SandboxedHandler::HandlerCrash, received signo = xxx | 渲染render进程crash，会造成白屏、Web组件卡死等问题。 | 367| SharedContextState context lost via Skia OOM | 共享内存不足，会导致应用闪退、花屏卡死等问题。 368| CreateNativeViewGLSurfaceEGLOhos::normal surface | 创建egl surface成功，如果没有该日志打印则会造成白屏问题。| 369| INFO: request had no response within 5 seconds | 网络超时。 | 370| final url: ***, error_code xxx(net::ERR_XXX) | 主资源加载报错。| 371 372下面说明一下Web组件网络加载过程中的关键日志，正常情况下一个Web组件的加载过程应该包含这些关键节点： 373 374 375| 日志关键字 | 说明 | 376| ---- | -------------------------------- | 377| NWebRenderMain start | 子进程启动。 | 378| RendererMain startup 、<br> render thread init | 子进程初始化开始。 | 379| event_message: WillProcessNavigationResponse source_id xxx navigation_handle id: xxx| 收到主资源的response。 | 380| event_message: commit navigation in main frame, routing_id: 4, url: *** | Commit到子进程。 381| RenderFrameImpl::CommitNavigation、<br> event_message: page load start | 子进程收到commit。| 382| NWebHandlerDelegate::OnNavigationEntryCommitted、<br> event_message: Commit source_id xxx | 主进程收到DidCommitNavigation。| 383| event_message: load_timing_info errpr_code:0,...| 主资源加载完成，以及各阶段耗时。| 384| event_message: MarkFirstContentfulPaint| 标记解析到有可显示内容的元素。| 385| NWebHandlerDelegate::OnPageVisible| 第一帧展示。| 386| NWebHandlerDelegate::OnFirstContentfulPaint| 第一帧有内容展示。| 387| event_message: content load finished | 页面解析完成。| 388| event_message: page load finished、<br> NWebHandlerDelegate::OnLoadEnd、<br> NWebHandlerDelegate::MainFrame OnLoadEnd、<br> NWebHandlerDelegate::OnFirstMeaningfulPaint | 页面以及子资源加载完成。| 389 390
