Android WebView JSBridge 治理实战：从线上白屏崩溃到协议化通信

背景：一次线上"白屏"投诉引出的 WebView 治理问题

某电商 App 的营销活动页用 WebView 承载，H5 团队独立发布内容，Android 端只负责容器。上线后陆续收到用户反馈："点了活动按钮没反应""页面突然白屏""偶尔闪退"。排查后发现，这不是单一 bug，而是 WebView 容器在 JSBridge 通信、生命周期管理、异常兜底三个层面长期缺位导致的系统性问题。这篇文章记录完整的排查过程和治理方案，重点是 JSBridge 的设计边界、安全校验，以及如何把"偶发线上崩溃"变成"可复现、可定位、可预防"的问题。

一、先复盘：WebView 容器最容易埋雷的三个点

1. JSBridge 通信没有协议约束

最初的实现是简单粗暴的字符串拼接式调用：

kotlin 复制代码

// 反面教材：早期版本
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"的崩溃：

kotlin 复制代码

override fun onDestroy() {
    super.onDestroy()
    webView.destroy() // 直接销毁，忽略了正在执行的 evaluateJavascript 回调
}

3. 异常没有兜底，白屏无法自愈

H5 页面加载失败、JS 执行报错、网络中断，容器层完全没有处理，用户看到的就是一片空白，且无法重试。

二、JSBridge 重新设计：协议化 + 版本化 + 白名单

1. 定义统一的通信协议

先约定请求和响应的 JSON 结构，避免裸字符串传参：

kotlin 复制代码

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()
)`data class BridgeResponse(
val code: Int,          // 0 成功，非 0 按错误码约定
val message: String = "",
val data: JSONObject = JSONObject()
)`

2. 用注解 + 反射管理 Action，替代 when-case 硬编码

kotlin 复制代码

@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<String, IBridgeHandler>) {



@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 能力"。必须加白名单：

kotlin 复制代码

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")




}`}`

kotlin 复制代码

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 必须严格跟随宿主生命周期释放资源，且要先取消回调再销毁：

kotlin 复制代码

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. 加载失败自动降级为原生兜底页

kotlin 复制代码

override fun onReceivedError(view: WebView, request: WebResourceRequest, error: WebResourceError) {
    if (request.isForMainFrame) {
        // 主资源加载失败才展示兜底页，避免子资源（图片、埋点）失败误伤整页
        showFallbackView(errorCode = error.errorCode) {
            webView.reload() // 提供重试入口，而非死白屏
        }
    }
}

2. 捕获 JS 层未处理异常并上报

约定 H5 侧全局捕获错误后通过 Bridge 上报，Native 侧统一打点，形成前后端联合排查的证据链：

javascript 复制代码

window.onerror = function (message, source, lineno, colno, error) {
  AppBridge.postMessage(JSON.stringify({
    action: 'reportJsError',
    data: { message, source, lineno, stack: error && error.stack }
  }));
};

kotlin 复制代码

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 进程，但必须显式处理，否则页面卡死无响应：

kotlin 复制代码

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 上又崩了"变成"日志一看就知道哪里出的问题"。