第37篇WebView 空白无错误用加载账本和桥接握手定位摘要WebView 空白最麻烦的是页面看起来没崩也没有明确报错。实际问题可能在 URL、网络、证书、页面脚本、JSBridge 握手或容器尺寸。更稳的做法是给 WebView 加加载账本每个阶段记录 trace、超时、桥接握手和可见错误页不再让用户面对一块白屏。有个活动页上线后运营反馈“偶尔打开一片白”。设备日志里没有 ArkTS 崩溃接口也没有明显失败。后来补了加载账本才看到有的用户 URL 拼错有的用户 HTML 加载成功但 JSBridge 没握手有的是 WebView 高度被父容器压成 0。以前只在页面上放一个 loading问题自然看不出来。这篇文章解决四个实际问题把 WebView 加载拆成 URL 校验、开始加载、首屏可见、桥接握手、业务 ready。超时后展示错误页并把 traceId、URL 类型和阶段写清楚。JSBridge 调用先经过握手状态不让页面脚本空调用。用日志和本地开关复现白屏而不是只让用户重试。白屏先按阶段拆不先猜网络WebView 白屏不是一个原因。先把页面从进入到 ready 的阶段列出来才能判断是容器问题、加载问题还是桥接问题。位置现象风险处理方向URL 拼接空字符串或缺少 queryWebView 加载无效地址进入前校验容器布局高度为 0 或被遮挡实际已加载但看不见加最小高度和可见日志网络/证书onError 触发只停留 loading错误页展示阶段JSBridgeH5 ready 未回调业务按钮不可用握手超时这一步的价值是先把问题放回运行链路。只要能确认问题停在哪个位置后面就不用靠猜测改页面。WebView 容器只负责阶段不负责业务兜底WebView 容器应该把阶段和错误暴露出来活动页、会员页或协议页再根据业务决定是否允许重试、刷新或退出。模块应该负责不应该负责WebShellPageURL、标题、加载状态活动业务规则WebLoadLedger阶段时间和错误码页面文案BridgeGuard握手是否完成具体营销逻辑ErrorPresenter错误类型和重试入口WebView 内部脚本FeatureService业务参数和兜底方案容器生命周期细节边界定清后代码就不会在页面、服务和回调之间来回复制同一段判断。后续新增场景也能先判断应该落在哪一层。用加载账本记录每一步exportenumWebLoadStage{Idleidle,UrlCheckedurl_checked,Loadingloading,DomVisibledom_visible,BridgeReadybridge_ready,Failedfailed}exportinterfaceWebLoadLedger{traceId:stringurl:stringstage:WebLoadStage startedAt:numberlastChangedAt:numbererrorText:string}exportfunctioncreateWebLedger(url:string):WebLoadLedger{return{traceId:web_${Date.now()},url,stage:WebLoadStage.Idle,startedAt:Date.now(),lastChangedAt:Date.now(),errorText:}}账本不是为了多写状态而是为了让空白页有证据。每次状态变化都能记录在哪个阶段停住而不是只看到一个 loading。这类模型最好放在models或common中页面、Service 和仓储都使用同一份类型避免各层用字符串互相猜。进入前先做 URL 闸门exportclassWebUrlPolicy{normalize(input:string):string{constvalueinput.trim()if(value.length0){return}if(!value.startsWith(https://)){return}returnvalue}canOpen(url:string):boolean{returnurl.startsWith(https://example.com/)||url.startsWith(https://m.example.com/)}}URL 闸门把空地址、非 https 和非白名单域名挡在 WebView 外面。这样错误能在 ArkTS 页面里展示不会变成一个没有上下文的空白容器。Service 的目标不是把所有逻辑都塞进去而是把跨页面、跨生命周期或需要持久化的判断集中起来。页面只表达用户动作。页面层把 loading 和错误页分开Componentstruct WebShellPage{Stateledger:WebLoadLedgercreateWebLedger()privateurlPolicy:WebUrlPolicynewWebUrlPolicy()aboutToAppear():void{consturlthis.urlPolicy.normalize(readRouteUrl())if(url.length0||!this.urlPolicy.canOpen(url)){this.ledger{...createWebLedger(url),stage:WebLoadStage.Failed,errorText:链接不可用}return}this.ledger{...createWebLedger(url),stage:WebLoadStage.UrlChecked}}build(){Stack(){if(this.ledger.stage!WebLoadStage.Failed){this.WebContent()}if(this.ledger.stageWebLoadStage.Failed){WebErrorPanel({messageText:this.ledger.errorText,retryTap:()this.retryLoad()})}}}}页面不再让 WebView 自己吞掉所有失败。URL 不合法、超时、桥接失败都能进入同一个错误面板用户也能看到可重试入口。页面层要控制展示和交互节奏但不应该拥有底层事实。这样页面重建、横竖屏变化或返回前台时都能重新从 Service 拿到可信结果。Bridge 握手要有超时exportclassBridgeGuard{privateready:booleanfalseprivatetimer:number-1start(timeoutMs:number,timeoutAction:()void):void{this.readyfalsethis.timersetTimeout((){if(!this.ready){timeoutAction()}},timeoutMs)}markReady():void{this.readytrueif(this.timer0){clearTimeout(this.timer)this.timer-1}}canCallBridge():boolean{returnthis.ready}}桥接握手失败不能一直转圈。超过约定时间就进入错误状态并带上 traceId方便 H5 和客户端一起查。实际项目里很多问题不是第一次进入页面暴露而是在冷启动、返回前台、页面重建或回调晚到时暴露。把这段生命周期补上修复才算闭环。错误页要说清楚是哪一层失败情况页面表现工程处理URL 不合法页面内提示链接不可用不要创建 WebView加载超时显示重试和 traceId同时记录阶段Bridge 超时提示页面初始化失败让 H5 查 ready 回调容器不可见记录尺寸和父容器状态先修布局约束兜底路径不是可有可无。用户遇到异常时页面至少要给出当前状态、可执行动作和可排查线索。排查命令先找吞错位置rg-nWeb\(|WebView|javaScriptProxy|Bridge|onError|onPageentry features common rg-nheight\(0|visibility|clip\(|loading|retryLoadentry features common rg-ntraceId|WebLoadStage|BridgeReady|Failedentry features common第一组命令找旧路径第二组命令找新边界第三组命令看生命周期或回调位置。命中后不要只看字段名要判断它是否仍在直接改页面状态。验证清单验证项预期结果空 URL直接展示错误页非白名单域名不创建 WebView断网加载进入失败状态可重试H5 不回 ready握手超时后展示 trace长页面容器高度正常不被父布局压扁这些验证最好在真机或模拟器里按顺序走一遍。只看源码很难发现冷启动、重启和回调晚到这类问题。常见问题和处理方式现象常见原因处理方式一直 loading没有阶段超时给 Loading 和 Bridge 分别加超时有内容但看不见父容器高度问题检查布局约束和 Stack 层级按钮无响应Bridge 未 ready调用前先看 BridgeGuard用户只能重启无错误页失败状态必须有重试入口如果现象没有出现在表里仍然建议按“输入来源 - 中间状态 - 持久化或页面展示 - 失败兜底”的顺序排查。小结WebView 白屏要留下阶段证据WebView 空白不是靠多放一个 loading 解决的。先校验 URL再记录加载阶段桥接必须握手失败要有错误页和 trace。这样前端、客户端、服务端都能看到问题卡在哪里用户也不会只能面对一块白屏。重启 | 无错误页 | 失败状态必须有重试入口 |如果现象没有出现在表里仍然建议按“输入来源 - 中间状态 - 持久化或页面展示 - 失败兜底”的顺序排查。小结WebView 白屏要留下阶段证据WebView 空白不是靠多放一个 loading 解决的。先校验 URL再记录加载阶段桥接必须握手失败要有错误页和 trace。这样前端、客户端、服务端都能看到问题卡在哪里用户也不会只能面对一块白屏。