背景：一次线上"白屏"投诉引出的 WebView 治理问题
某电商 App 的营销活动页用 WebView 承载，H5 团队独立发布内容，Android 端只负责容器。上线后陆续收到用户反馈："点了活动按钮没反应""页面突然白屏""偶尔闪退"。排查后发现，这不是单一 bug，而是 WebView 容器在 JSBridge 通信、生命周期管理、异常兜底三个层面长期缺位导致的系统性问题。这篇文章记录完整的排查过程和治理方案，重点是 JSBridge 的设计边界、安全校验，以及如何把"偶发线上崩溃"变成"可复现、可定位、可预防"的问题。
一、先复盘：WebView 容器最容易埋雷的三个点
1. JSBridge 通信没有协议约束
最初的实现是简单粗暴的字符串拼接式调用：
// 反面教材：早期版本
webView.addJavascriptInterface(object {
@JavascriptInterface
fun call(action: String, params: String) {
when (action) {
"share" -> doShare(params)
"openPage" -> openPage(params)
"toast" -> Toast.makeText(context, params, Toast.LENGTH_SHORT).show()
// 新需求来了就往下加 case，没有版本管理
}
}
}, "AppBridge")问题很典型：H5 传什么参数、Native 期望什么格式，全靠口头约定；一旦 H5 那边字段拼错或类型不对，Native 端直接崩溃，且没有任何日志能定位是哪个页面、哪次调用出的问题。
2. 生命周期与 WebView 销毁时机不匹配
Activity 销毁时如果 WebView 还持有未完成的 JS 回调或网络请求，很容易出现"访问已销毁 Context"的崩溃：
override fun onDestroy() {
super.onDestroy()
webView.destroy() // 直接销毁，忽略了正在执行的 evaluateJavascript 回调
}3. 异常没有兜底，白屏无法自愈
H5 页面加载失败、JS 执行报错、网络中断，容器层完全没有处理，用户看到的就是一片空白，且无法重试。
二、JSBridge 重新设计：协议化 + 版本化 + 白名单
1. 定义统一的通信协议
先约定请求和响应的 JSON 结构，避免裸字符串传参：
data class BridgeRequest(
val action: String,
val callbackId: String? = null,
val data: JSONObject = JSONObject()
)
data class BridgeResponse(
val code: Int, // 0 成功，非 0 按错误码约定
val message: String = "",
val data: JSONObject = JSONObject()
)2. 用注解 + 反射管理 Action，替代 when-case 硬编码
@Target(AnnotationRetention.RUNTIME)
annotation class BridgeAction(val name: String, val minVersion: Int = 1)
class ShareHandler : IBridgeHandler {
@BridgeAction("share", minVersion = 2)
override fun handle(request: BridgeRequest, callback: BridgeCallback) {
val title = request.data.optString("title")
val url = request.data.optString("url")
if (title.isEmpty() || url.isEmpty()) {
callback.onResult(BridgeResponse(code = 400, message = "参数缺失"))
return
}
ShareManager.share(title, url) { success ->
callback.onResult(BridgeResponse(code = if (success) 0 else 500))
}
}
}
class JsBridgeDispatcher(private val handlers: Map) {
@JavascriptInterface
fun postMessage(rawJson: String) {
val request = runCatching { parseRequest(rawJson) }.getOrElse {
Log.w("JsBridge", "解析请求失败: $rawJson", it)
return
}
val handler = handlers[request.action]
if (handler == null) {
respond(request.callbackId, BridgeResponse(code = 404, message = "未注册的 action"))
return
}
// 每个 handler 单独 try-catch，避免一个 action 崩溃拖垮整个 Bridge
runCatching {
handler.handle(request) { response -> respond(request.callbackId, response) }
}.onFailure { e ->
Log.e("JsBridge", "action=${request.action} 执行异常", e)
respond(request.callbackId, BridgeResponse(code = 500, message = "Native 内部异常"))
}
}
}关键改动：把每个 action 拆成独立 Handler，异常隔离到单个 action 内，不会因为一个功能出错导致整条 Bridge 通道不可用；同时统一走 callbackId 异步回调 H5，而不是同步返回值。
3. 安全校验：域名白名单 + 敏感 action 二次确认
JSBridge 最大的安全风险是"任意页面都能调用 Native 能力"。必须加白名单：
object BridgeSecurity {
private val trustedHosts = setOf("activity.example.com", "m.example.com")
fun isTrusted(url: String?): Boolean {
val host = runCatching { Uri.parse(url).host }.getOrNull() ?: return false
return trustedHosts.any { host == it || host.endsWith(".$it") }
}
// 涉及支付、通讯录等敏感能力的 action 单独加一层确认
val sensitiveActions = setOf("startPay", "readContacts", "openCamera")
}webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
// 拦截非白名单域名的跳转，防止被恶意重定向后仍持有 Bridge 权限
if (!BridgeSecurity.isTrusted(request.url.toString())) {
openInSystemBrowser(request.url)
return true
}
return false
}
}
// dispatcher 内部对敏感 action 增加校验
if (request.action in BridgeSecurity.sensitiveActions && !BridgeSecurity.isTrusted(webView.url)) {
respond(request.callbackId, BridgeResponse(code = 403, message = "非可信页面禁止调用"))
return
}三、生命周期治理：让 WebView 销毁不再引发崩溃
WebView 必须严格跟随宿主生命周期释放资源，且要先取消回调再销毁：
class SafeWebViewContainer(private val webView: WebView) : DefaultLifecycleObserver {
override fun onPause(owner: LifecycleOwner) {
webView.onPause()
webView.pauseTimers()
}
override fun onResume(owner: LifecycleOwner) {
webView.resumeTimers()
webView.onResume()
}
override fun onDestroy(owner: LifecycleOwner) {
// 先清空 JS 接口引用，避免销毁后仍被回调持有的 Context 访问
webView.removeJavascriptInterface("AppBridge")
webView.webChromeClient = null
webView.webViewClient = object : WebViewClient() {} // 空实现，切断旧引用
(webView.parent as? ViewGroup)?.removeView(webView)
webView.stopLoading()
webView.clearHistory()
webView.loadUrl("about:blank")
webView.destroy()
}
}把这个 Observer 注册到 Activity/Fragment 的 Lifecycle 上，容器层的资源释放就不再依赖开发者手动在各处调用，减少遗漏。
四、异常兜底：白屏可自愈、崩溃可定位
1. 加载失败自动降级为原生兜底页
override fun onReceivedError(view: WebView, request: WebResourceRequest, error: WebResourceError) {
if (request.isForMainFrame) {
// 主资源加载失败才展示兜底页，避免子资源（图片、埋点）失败误伤整页
showFallbackView(errorCode = error.errorCode) {
webView.reload() // 提供重试入口，而非死白屏
}
}
}2. 捕获 JS 层未处理异常并上报
约定 H5 侧全局捕获错误后通过 Bridge 上报，Native 侧统一打点，形成前后端联合排查的证据链：
window.onerror = function (message, source, lineno, colno, error) {
AppBridge.postMessage(JSON.stringify({
action: 'reportJsError',
data: { message, source, lineno, stack: error && error.stack }
}));
};class JsErrorHandler : IBridgeHandler {
@BridgeAction("reportJsError")
override fun handle(request: BridgeRequest, callback: BridgeCallback) {
val pageUrl = currentWebViewUrl()
Monitor.reportJsError(
page = pageUrl,
message = request.data.optString("message"),
stack = request.data.optString("stack")
)
callback.onResult(BridgeResponse(code = 0))
}
}3. Native 侧渲染进程崩溃兜底（Android O+）
WebView 底层渲染进程崩溃不会直接崩掉 App 进程，但必须显式处理，否则页面卡死无响应：
override fun onRenderProcessGone(view: WebView, detail: RenderProcessGoneDetail): Boolean {
Log.e("WebView", "渲染进程崩溃 didCrash=${detail.didCrash()}")
(view.parent as? ViewGroup)?.removeView(view)
view.destroy()
Monitor.reportRenderProcessGone(currentPageUrl(), detail.didCrash())
showFallbackView(errorCode = -1) { recreateWebView() }
return true // 返回 true 表示已自行处理，避免系统默认行为
}五、治理效果与验证方式
- JSBridge 通信全部走协议化请求，H5 传参错误只会返回错误码，不再引发 Native 崩溃；
- 敏感能力增加白名单校验后，第三方页面无法越权调用支付、通讯录等接口；
- WebView 销毁流程标准化后，"访问已销毁 Context"类崩溃在灰度期间归零；
- 白屏场景提供重试兜底，配合渲染进程崩溃监听，用户不再遇到无响应死页面；
- JS 异常上报打通后，H5 和 Native 排查同一个问题时能对上同一份日志，定位时间明显缩短。
验证方式上，除了灰度观察崩溃率和白屏率指标，还写了针对 JsBridgeDispatcher 的单元测试，覆盖未知 action、参数缺失、Handler 内部抛异常三种典型场景，确保后续新增 action 不会破坏既有的异常隔离机制。
六、小结
WebView 容器类问题往往不是某一行代码的 bug，而是协议设计、生命周期管理、异常兜底三者长期缺失的累积结果。把 JSBridge 当成一个需要版本管理、权限校验的正式接口来设计，把 WebView 的销毁流程收敛成统一的生命周期观察者，再补齐异常上报链路，才能把"line 上又崩了"变成"日志一看就知道哪里出的问题"。
