Web 和 Native 是怎么“对话“的？JSBridge 解答

Web 与 Native 通信的核心桥梁技术

一、什么是 JSBridge

JSBridge（JavaScript Bridge）是一种在 Hybrid App 中实现 Web 页面（JavaScript）与 Native 原生代码（iOS/Android）双向通信的技术方案。它本质上是一个"翻译官"------将 JavaScript 的函数调用翻译成 Native 能理解的指令，同时将 Native 的执行结果翻译回 JavaScript 能处理的数据。

核心定义：

JSBridge 是连接 Web 层与 Native 层的通信协议和实现机制，它定义了消息的格式、传递方式和回调机制，使得两个不同运行环境中的代码能够相互调用对方的能力。

在移动互联网时代，纯 Native 开发成本高、迭代慢，纯 Web 体验差、能力受限。Hybrid App 结合了两者的优势：用 Web 实现快速迭代的业务页面，用 Native 提供高性能的底层能力。而 JSBridge 就是让这两个世界能够"对话"的关键技术。

JSBridge 的本质

从计算机科学的角度看，JSBridge 本质上是一种**跨进程/跨运行时通信（IPC）**机制。JavaScript 运行在 WebView 的 JS 引擎中（如 V8、JavaScriptCore），Native 代码运行在操作系统的原生运行时中。两者处于不同的执行上下文，无法直接互相调用函数。JSBridge 通过约定的协议和 WebView 提供的接口，打通了这道屏障。

二、为什么需要 JSBridge

2.1 Web 的局限性

浏览器出于安全考虑，对 Web 页面施加了严格的沙箱限制。Web 页面无法直接访问：

• 设备硬件： 摄像头（需要权限申请）、蓝牙、NFC、指纹传感器
• 系统能力： 通讯录、相册、文件系统、推送通知
• 性能敏感操作： 复杂动画、大量数据处理、音视频编解码
• App 级能力： 页面路由、登录态、支付、分享到社交平台

2.2 Native 的痛点

• 开发成本高（iOS + Android 双端开发）
• 发版周期长，需要应用商店审核
• 无法做到即时更新，热修复能力有限

2.3 JSBridge 的价值

能力扩展 动态化 跨平台 解耦 安全可控

JSBridge 让 Web 页面能够调用 Native 的强大能力，同时保持 Web 的灵活性和动态更新特性，实现了"鱼和熊掌兼得"。

三、整体架构与通信模型

通信模型的核心设计原则：

1. 异步通信： 所有跨层调用都是异步的，通过回调或 Promise 获取结果
2. 消息驱动： 通信以消息（Message）为单位，包含方法名、参数、回调 ID
3. 双向对等： JS 可以调用 Native，Native 也可以调用 JS，地位对等
4. 协议统一： 无论底层实现如何，上层 API 保持一致

四、核心实现方案

JSBridge 的实现方案经历了多代演进，主要有以下四种：

方案概览：

1. URL Scheme 拦截（第一代）--- 通过自定义协议 jsbridge://method?params 触发 Native 拦截
2. 注入 API（第二代，推荐）--- Native 向 JS 上下文注入全局对象，直接函数调用
3. 拦截 JS 弹窗（辅助方案）--- 重写 alert/confirm/prompt，Native 拦截弹窗获取消息
4. MessageChannel（新一代）--- 基于 postMessage 机制，支持结构化克隆传输

五、通信流程详解

JS 调用 Native 的完整流程

消息格式设计

// JS → Native 的消息结构
{
  "method": "getLocation",
  "params": {
    "enableHighAccuracy": true,
    "timeout": 5000
  },
  "callbackId": "cb_1716234567890_1"
}

// Native → JS 的响应结构
{
  "callbackId": "cb_1716234567890_1",
  "code": 0,
  "data": {
    "latitude": 30.2741,
    "longitude": 120.1551
  },
  "message": "success"
}

六、代码实现

6.1 JS 端 Bridge 核心实现

class JSBridge {
  constructor() {
    this.callbackMap = {};          // 回调函数映射表
    this.callbackId = 0;            // 自增 ID
    this.handlers = {};              // Native 调用 JS 的处理器
    this.messageQueue = [];          // 消息队列（Bridge 未就绪时缓存）
    this.isReady = false;
  }

  // JS 调用 Native
  call(method, params = {}) {
    return new Promise((resolve, reject) => {
      const id = `cb_${Date.now()}_${++this.callbackId}`;

      // 存储回调
      this.callbackMap[id] = { resolve, reject };

      // 构造消息
      const message = JSON.stringify({ method, params, callbackId: id });

      // 发送给 Native（注入 API 方式）
      if (window.webkit?.messageHandlers?.nativeBridge) {
        // iOS WKWebView
        window.webkit.messageHandlers.nativeBridge.postMessage(message);
      } else if (window.NativeBridge) {
        // Android WebView
        window.NativeBridge.postMessage(message);
      } else {
        // 降级：URL Scheme
        const iframe = document.createElement('iframe');
        iframe.style.display = 'none';
        iframe.src = `jsbridge://${method}?data=${encodeURIComponent(message)}`;
        document.body.appendChild(iframe);
        setTimeout(() => iframe.remove(), 100);
      }
    });
  }

  // 注册 JS 端处理器（供 Native 调用）
  register(name, handler) {
    this.handlers[name] = handler;
  }

  // Native 回调 JS（Native 调用此方法传回结果）
  _handleResponse(responseJSON) {
    const { callbackId, code, data, message } = JSON.parse(responseJSON);
    const callback = this.callbackMap[callbackId];
    if (!callback) return;

    if (code === 0) {
      callback.resolve(data);
    } else {
      callback.reject(new Error(message));
    }
    delete this.callbackMap[callbackId];
  }

  // Native 主动调用 JS
  _handleNativeCall(name, params, nativeCallbackId) {
    const handler = this.handlers[name];
    if (handler) {
      const result = handler(params);
      this._respondToNative(nativeCallbackId, result);
    }
  }
}

// 全局挂载
window.JSBridge = new JSBridge();

6.2 iOS 端实现（Swift + WKWebView）

import WebKit

class BridgeHandler: NSObject, WKScriptMessageHandler {

    private var webView: WKWebView
    private var handlers: [String: (Any) -> Any?] = [:]

    // 注册 Native 方法
    func register(_ name: String, handler: @escaping (Any) -> Any?) {
        handlers[name] = handler
    }

    // 接收 JS 消息
    func userContentController(
        _ controller: WKUserContentController,
        didReceive message: WKScriptMessage
    ) {
        guard let body = message.body as? String,
              let data = body.data(using: .utf8),
              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
        else { return }

        let method = json["method"] as? String ?? ""
        let params = json["params"]
        let callbackId = json["callbackId"] as? String ?? ""

        // 路由到对应 handler
        if let handler = handlers[method] {
            let result = handler(params ?? [:])
            respondToJS(callbackId: callbackId, data: result)
        }
    }

    // 回传结果给 JS
    private func respondToJS(callbackId: String, data: Any?) {
        let response: [String: Any] = [
            "callbackId": callbackId,
            "code": 0,
            "data": data ?? NSNull()
        ]
        let jsonData = try! JSONSerialization.data(withJSONObject: response)
        let jsonStr = String(data: jsonData, encoding: .utf8)!
        let js = "window.JSBridge._handleResponse('\(jsonStr)')"

        webView.evaluateJavaScript(js, completionHandler: nil)
    }
}

6.3 Android 端实现（Kotlin）

class BridgeInterface(private val webView: WebView) {

    private val handlers = mutableMapOf<String, (Any?) -> Any?>()

    fun register(name: String, handler: (Any?) -> Any?) {
        handlers[name] = handler
    }

    // 暴露给 JS 调用的方法
    @JavascriptInterface
    fun postMessage(message: String) {
        val json = JSONObject(message)
        val method = json.getString("method")
        val params = json.opt("params")
        val callbackId = json.getString("callbackId")

        handlers[method]?.let { handler ->
            val result = handler(params)
            respondToJS(callbackId, result)
        }
    }

    private fun respondToJS(callbackId: String, data: Any?) {
        val response = JSONObject().apply {
            put("callbackId", callbackId)
            put("code", 0)
            put("data", data)
        }
        val js = "window.JSBridge._handleResponse('${response}')"
        webView.post { webView.evaluateJavascript(js, null) }
    }
}

// 注册到 WebView
webView.addJavascriptInterface(BridgeInterface(webView), "NativeBridge")

七、方案对比

|-----------------|------------------|--------------------|--------------------------|--------------|
| 方案 | 原理 | 优点 | 缺点 | 适用场景 |
| URL Scheme | 自定义协议拦截 | 兼容性极好，支持旧版 WebView | URL 长度限制（~2KB）、需要编码、有延迟 | 兼容老设备、简单调用 |
| 注入 API | Native 注入全局对象 | 直接调用、无长度限制、性能好 | Android 4.2 以下有安全漏洞 | 主流方案，推荐使用 |
| prompt 拦截 | 重写 JS 弹窗方法 | 同步返回结果、实现简单 | 语义不清、影响正常弹窗使用 | Android 辅助方案 |
| postMessage | WKWebView 原生消息通道 | 高性能、支持结构化数据 | 仅 iOS 8+/WKWebView | iOS 现代应用 |

性能评分

八、安全机制

JSBridge 暴露了 Native 能力给 Web 层，如果不加以控制，恶意网页可能利用 Bridge 窃取用户数据或执行危险操作。因此安全设计至关重要：

8.1 域名白名单

只有在白名单内的域名加载的页面才能调用 Bridge。Native 端在接收到 JS 消息时，首先检查当前 WebView 加载的 URL 是否在允许列表中。

val allowedDomains = listOf(
    "app.example.com",
    "h5.example.com"
)

fun isAllowed(url: String): Boolean {
    val host = URI(url).host
    return allowedDomains.any { host.endsWith(it) }
}

8.2 方法权限分级

• 公开级： 获取设备信息、获取网络状态（任何页面可调用）
• 普通级： 拍照、定位、分享（需要域名白名单）
• 敏感级： 支付、获取通讯录、修改用户信息（需要额外鉴权 Token）

8.3 参数校验与防注入

所有从 JS 传入的参数都必须经过严格校验，防止 SQL 注入、路径穿越等攻击。Native 端应对参数进行类型检查、长度限制和特殊字符过滤。

8.4 通信加密

对于敏感数据的传输，可以在 Bridge 层增加加密机制：使用 AES 对消息体加密，密钥通过安全通道协商。防止中间人攻击和数据窃取。

⚠️ 安全提示：

Android 4.2 以下版本的 addJavascriptInterface 存在远程代码执行漏洞（CVE-2012-6636），攻击者可以通过反射调用任意 Java 方法。务必设置 targetSdkVersion >= 17 并使用 @JavascriptInterface 注解。

九、工程实践与最佳实践

9.1 Bridge Ready 机制

WebView 加载页面和 Native 注入 Bridge 对象存在时序问题。JS 代码可能在 Bridge 注入之前就执行了。解决方案：

// 方案一：事件监听
document.addEventListener('BridgeReady', () => {
  window.JSBridge.call('getDeviceInfo');
});

// 方案二：轮询检测 + 消息队列
function waitForBridge(callback, maxRetry = 20) {
  if (window.JSBridge?.isReady) {
    callback();
  } else if (maxRetry > 0) {
    setTimeout(() => waitForBridge(callback, maxRetry - 1), 50);
  }
}

9.2 超时与错误处理

async function callWithTimeout(method, params, timeout = 5000) {
  const timer = new Promise((_, reject) =>
    setTimeout(() => reject(new Error(`Bridge call "${method}" timeout`)), timeout)
  );
  return Promise.race([window.JSBridge.call(method, params), timer]);
}

9.3 版本管理与降级策略

随着 App 版本迭代，Bridge API 也会演进。需要设计版本协商机制：

• JS 端通过 bridge.call('getSDKVersion') 获取当前 Native Bridge 版本
• 根据版本号决定使用哪些 API，对不支持的 API 提供降级方案
• 使用语义化版本号（SemVer）管理 Bridge API 的兼容性

工程化架构全景

十、未来演进

10.1 当前生态中的 JSBridge

JSBridge 并非一个孤立的技术，它是整个 Hybrid 技术栈的基石。当前主流的跨端方案都依赖类似的桥接机制：

|--------------|-------------------------|------------------------------------|
| 框架 | 桥接机制 | 特点 |
| 微信小程序 | WeixinJSBridge（内部） | 双线程模型，逻辑层与渲染层通过 Native 中转 |
| React Native | Bridge → JSI（新架构） | 从异步 JSON Bridge 演进到同步 C++ 接口 |
| Flutter | Platform Channel | MethodChannel / EventChannel，二进制编码 |
| Capacitor | Native Bridge Plugin | 标准化插件体系，TypeScript 类型安全 |
| Uni-app | uni.requireNativePlugin | 统一 API 抹平平台差异 |

10.2 技术趋势

1. 同步化： React Native 新架构（JSI）实现了 JS 与 Native 的同步调用，消除了异步序列化开销
2. **类型安全：**通过 Codegen 自动生成 Bridge 接口的 TypeScript 类型定义，编译期发现错误
3. **标准化：**W3C正在推进更多 Web API（如 Web Bluetooth、Web NFC），减少对 Bridge 的依赖
4. Rust/WASM： 使用 WebAssembly 作为中间层，实现近原生性能的跨平台计算
5. 声明式 Bridge： 通过 DSL 或 Schema 定义 Bridge 接口，自动生成多端代码

总结

JSBridge 是 Hybrid App 开发的核心基础设施。它解决了 Web 与 Native 之间的通信鸿沟，让开发者能够在享受 Web 灵活性的同时，充分利用 Native 的强大能力。理解 JSBridge 的原理和实现，不仅有助于日常 Hybrid 开发，更能帮助你理解 React Native、小程序、Flutter 等现代跨端框架的底层设计思想。

掌握 JSBridge = 掌握 Web 与 Native 世界的连接方式。