1. 跨端调用的核心逻辑与方案选型
移动端混合开发里，WebView 承载 H5 页面是再常见不过的架构。但 H5 的能力边界很清晰——它拿不到系统级的硬件接口，也调不动原生页面。当业务需要从 H5 里唤起一个原生 Activity（比如扫码、选图、调起支付面板），并且还要拿到原生页面处理完的结果回传给 JS 时，这就不是简单的window.location能解决的事了。
这个项目的核心目标就一句话：在 JS 环境里发起对安卓原生 Activity 的调用，等原生页面处理完毕后，把结果数据回传给 JS 层继续使用。听起来像是一个简单的桥接，但真正落地时会牵扯到线程切换、数据序列化、生命周期管理、回调丢失等一堆细节。适合谁看？做 Hybrid 架构的前端、安卓端开发，或者正在维护一套 WebView 容器的人。如果你只是写纯 H5 或者纯原生，这篇内容对你帮助有限；但只要你的项目里存在 WebView 与原生互相调用的场景，这里面的坑你大概率都会踩到。
我先把整体思路摆出来，再逐层拆。整个链路分四段：JS 发起调用 → 原生拦截并启动 Activity → Activity 处理并回传结果 → 原生把结果送回 JS。每一段都有多种实现方式，选哪种直接决定了后续的稳定性和维护成本。
1.1 三种主流桥接方式的取舍
在安卓 WebView 里做 JS 与原生通信，绕不开三种方式，我把它们的特性拉平了对比：
| 方式 | 调用方向 | 返回值获取 | 复杂度 | 适用场景 |
|---|---|---|---|---|
addJavascriptInterface | JS 调原生 | 同步返回或异步回调 | 低 | 简单数据、同步场景 |
shouldOverrideUrlLoading拦截 | JS 调原生 | 需二次回调 | 中 | 兼容性要求高的老项目 |
WebMessagePort/postWebMessage | 双向 | 原生支持异步 | 中高 | 新项目、需要双向通道 |
addJavascriptInterface是最直观的：原生注入一个对象，JS 直接window.AndroidBridge.xxx()就能调。但它有个致命问题——默认在 WebView 的 JS 线程执行，如果方法里做耗时操作会阻塞页面，而且早期版本存在安全风险（低版本系统上反射可调用任意方法）。所以用它的时候，方法体里必须立刻切到主线程去启动 Activity，不能在里面干重活。
shouldOverrideUrlLoading拦截方案是很多老容器的选择，JS 通过改变location.href触发一个约定好的 scheme，原生在拦截里解析参数。它的好处是兼容性极好，几乎不挑系统版本；坏处是返回值没法直接给，必须原生再通过evaluateJavascript回调回去，一来一回链路长，而且 URL 长度有限制，传大数据会截断。
WebMessagePort是相对现代的方案，支持双向消息，原生和 JS 各持一个端口，通信更像消息队列。但它的 API 在低版本上支持不全，需要做降级。
我的选择是：以
addJavascriptInterface为主通道，配合evaluateJavascript做结果回传。理由很直接——调用发起用注入对象最省事，结果回传用evaluateJavascript最灵活，两者组合能覆盖绝大多数场景，且代码量可控。下面所有实操都基于这个组合展开。
1.2 为什么结果回传不能同步返回
很多人第一反应是：既然 JS 调了原生方法，为什么不让原生方法直接return结果？问题在于，启动 Activity 是一个异步过程。startActivityForResult发出后，当前方法就返回了，真正的结果要等用户在原生页面上操作完、Activity 销毁时，才会在onActivityResult里拿到。这个时间差可能是几百毫秒，也可能是几十秒（用户在选图页面慢慢挑）。
所以 JS 侧的调用模型必须是异步回调：发起调用时注册一个回调函数，原生拿到结果后，通过evaluateJavascript执行一段 JS，去触发那个预先注册好的回调。这就引出了整个方案里最关键的设计——回调 ID 的管理机制。
如果同时有多个调用在飞，怎么知道回来的结果是哪一次的？答案就是给每次调用分配一个唯一 ID，原生回传时带上这个 ID，JS 侧根据 ID 找到对应的回调执行。这个机制听起来简单，但实际写的时候，ID 的生成、存储、清理、超时处理，每一步都有讲究，后面会详细拆。
2. 核心细节解析与实操要点
方案定了，接下来是把每个环节的细节抠清楚。这一块我按调用链的顺序来讲，从 JS 侧怎么发起，到原生怎么接，再到结果怎么回去。
2.1 JS 侧的回调注册与 ID 管理
JS 侧的核心任务是两件事：发起调用时把回调存起来，收到原生回传时把回调取出来执行。我用一个全局对象来存回调，key 是调用 ID，value 是回调函数。
// 全局回调池 const callbackPool = {}; let callIdSeed = 0; // 生成唯一调用 ID function genCallId() { callIdSeed += 1; return `native_call_${Date.now()}_${callIdSeed}`; } // 发起原生调用 function invokeNativeActivity(params, onSuccess, onFail) { const callId = genCallId(); callbackPool[callId] = { onSuccess, onFail, timestamp: Date.now() }; const payload = { callId: callId, action: params.action, extra: params.extra || {} }; // 调用注入的原生对象 if (window.AndroidBridge && window.AndroidBridge.startActivity) { window.AndroidBridge.startActivity(JSON.stringify(payload)); } else { // 桥不可用，直接失败 delete callbackPool[callId]; onFail && onFail({ code: -1, msg: 'bridge unavailable' }); } } // 供原生调用的全局回调入口 window.__onNativeResult = function(resultJson) { let result; try { result = JSON.parse(resultJson); } catch (e) { return; } const cb = callbackPool[result.callId]; if (!cb) return; delete callbackPool[result.callId]; if (result.code === 0) { cb.onSuccess && cb.onSuccess(result.data); } else { cb.onFail && cb.onFail(result); } };这段代码有几个点值得说。第一，ID 生成用了时间戳加自增种子，保证同一毫秒内多次调用也不会撞 ID。第二，回调池里存了 timestamp，这是为了后面做超时清理用的——如果原生因为某种原因没回调，这个回调会永远挂在内存里，时间长了就是内存泄漏。第三，__onNativeResult是挂在 window 上的全局函数，原生通过evaluateJavascript调它，所以命名要足够独特，避免和业务代码冲突，我习惯用双下划线前缀。
注意：
callbackPool里的回调执行后必须立即delete，否则同一个 ID 被回调两次会导致重复执行。原生侧如果因为异常路径重复回调，这个 delete 就是最后一道防线。
2.2 原生侧注入对象的线程处理
原生侧第一步是注入桥接对象。这里最容易出问题的地方是线程。addJavascriptInterface注入的方法默认运行在 WebView 的 JS 线程（不是主线程），而startActivityForResult必须在主线程调用。所以方法体里第一件事就是切线程。
public class NativeBridge { private final Activity activity; private final WebView webView; // 用 Map 记录 callId 与请求的映射，用于结果回传时匹配 private final Map<String, String> pendingCalls = new ConcurrentHashMap<>(); public NativeBridge(Activity activity, WebView webView) { this.activity = activity; this.webView = webView; } @JavascriptInterface public void startActivity(String payloadJson) { // 当前在 JS 线程，切到主线程 activity.runOnUiThread(() -> { try { JSONObject payload = new JSONObject(payloadJson); String callId = payload.getString("callId"); String action = payload.getString("action"); JSONObject extra = payload.optJSONObject("extra"); // 记录这次调用 pendingCalls.put(callId, action); // 根据 action 分发到不同的原生页面 Intent intent = buildIntent(action, extra); if (intent == null) { sendResult(callId, -2, "unknown action", null); return; } // 把 callId 塞进 Intent，结果回来时能对上 intent.putExtra("__call_id", callId); activity.startActivityForResult(intent, REQ_CODE_NATIVE); } catch (Exception e) { // 解析失败，无法拿到 callId，只能记日志 Log.e(TAG, "startActivity parse error", e); } }); } }这里有个关键设计：callId 通过 Intent 的 extra 传递。因为onActivityResult回调时，我们能拿到的只有requestCode、resultCode和data，如果不把 callId 塞进 Intent，结果回来时就不知道对应哪次调用。用putExtra("__call_id", callId)是最稳妥的做法，双下划线前缀同样是为了避免和业务参数冲突。
pendingCalls用ConcurrentHashMap是因为写入在主线程、读取可能在别的线程，虽然这个场景下竞争不激烈，但用并发容器是习惯问题，能省掉一类偶发的诡异 bug。
2.3 Intent 构建与参数传递的边界
buildIntent这个方法负责把 JS 传来的 action 和 extra 翻译成一个具体的 Intent。这一步的边界处理特别重要，因为 JS 传来的数据是不可信的——可能是 null，可能是类型不对，可能是超长的字符串。
private Intent buildIntent(String action, JSONObject extra) { Intent intent = new Intent(); switch (action) { case "scan": intent.setClass(activity, ScanActivity.class); break; case "pickImage": intent.setClass(activity, PickImageActivity.class); // 传递最大选择数量，做类型和范围校验 int maxCount = extra != null ? extra.optInt("maxCount", 1) : 1; if (maxCount < 1) maxCount = 1; if (maxCount > 9) maxCount = 9; intent.putExtra("max_count", maxCount); break; case "editProfile": intent.setClass(activity, EditProfileActivity.class); // 传递初始数据，注意长度限制 String initData = extra != null ? extra.optString("initData", "") : ""; if (initData.length() > 4096) { initData = initData.substring(0, 4096); } intent.putExtra("init_data", initData); break; default: return null; } return intent; }参数校验这块，我踩过的坑是没做范围限制导致原生页面崩溃。比如 JS 传了个maxCount: 999，原生页面按这个数量去初始化数组，直接 OOM。所以每个参数都要有明确的合法区间，超出就夹到边界值。字符串参数同理，Intent 传递的数据底层走 Binder，有大小限制（大约 1MB 左右），超了会抛TransactionTooLargeException，所以对长字符串要主动截断。
实操心得：不要相信 JS 传来的任何数据。类型、范围、长度、空值，四道校验一个都不能少。宁可返回一个明确的错误码，也不要让原生页面带着脏数据启动。
3. 实操过程与核心环节实现
前面把静态的结构讲清楚了，这一节走一遍完整的动态流程，从用户点击按钮到结果回到 JS，把每个环节的代码和意图都摊开。
3.1 完整调用链的时序拆解
假设用户在 H5 页面上点了一个"扫码"按钮，整个链路是这样跑的：
- JS 调用
invokeNativeActivity({action: 'scan'}, onSuccess, onFail)，生成 callId 存入回调池，调用AndroidBridge.startActivity。 - 原生
startActivity方法在 JS 线程被触发，立刻runOnUiThread切到主线程。 - 主线程解析 payload，构建
ScanActivity的 Intent，塞入 callId，调用startActivityForResult。 - 扫码页面启动，用户对准二维码，识别成功。
- 扫码页面
setResult把结果数据放进 Intent，finish()自己。 - 原 Activity 的
onActivityResult被回调，取出 callId 和结果数据。 - 原生调用
sendResult，通过evaluateJavascript执行window.__onNativeResult(...)。 - JS 侧
__onNativeResult根据 callId 找到回调，执行onSuccess，并从回调池删除。
这条链路里，第 3 步到第 6 步之间是"用户操作时间"，不可控。第 7 步的evaluateJavascript必须在主线程调用，而且要注意 WebView 此时是否还活着——如果用户在扫码期间把承载 WebView 的页面关了，evaluateJavascript会失败，这时候要静默处理，不能崩。
3.2 结果回传的代码实现
onActivityResult和sendResult是结果回传的核心，我把它们写在一起看：
@Override protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode != REQ_CODE_NATIVE) return; String callId = data != null ? data.getStringExtra("__call_id") : null; if (callId == null) { // 没有 callId，说明不是我们发起的调用，忽略 return; } if (resultCode == Activity.RESULT_OK && data != null) { String resultJson = data.getStringExtra("result_json"); sendResult(callId, 0, "ok", resultJson); } else if (resultCode == Activity.RESULT_CANCELED) { sendResult(callId, 1, "user canceled", null); } else { sendResult(callId, -3, "unknown result", null); } } private void sendResult(String callId, int code, String msg, String dataJson) { // 清理 pending 记录 pendingCalls.remove(callId); JSONObject result = new JSONObject(); try { result.put("callId", callId); result.put("code", code); result.put("msg", msg); if (dataJson != null) { result.put("data", new JSONObject(dataJson)); } } catch (JSONException e) { Log.e(TAG, "build result error", e); return; } final String js = "window.__onNativeResult && window.__onNativeResult(" + JSONObject.quote(result.toString()) + ")"; // evaluateJavascript 必须在主线程 webView.post(() -> { if (webView.isAttachedToWindow()) { webView.evaluateJavascript(js, null); } }); }这里有几个细节值得展开。第一，JSONObject.quote用来转义 JSON 字符串，因为我们要把一段 JSON 作为参数塞进 JS 代码里，如果不转义，里面的引号会把 JS 语法搞乱。这是很多人第一次写会翻车的地方——直接字符串拼接，结果数据里带个引号，整段 JS 就报语法错误了。
第二，webView.post确保在主线程执行，虽然onActivityResult本身就在主线程，但sendResult可能被其他路径调用，统一 post 一下更安全。
第三，isAttachedToWindow判断，防止 WebView 已经销毁还去执行 JS。这个判断不是万能的，但能挡掉大部分"页面已关闭"的场景。
3.3 超时清理与内存保护
回调池如果只进不出，迟早会撑爆内存。除了正常回调时删除，还需要一个超时清理机制。我在 JS 侧加了一个定时器，定期扫描回调池，把超过一定时间还没回调的记录清掉并触发失败回调。
const CALLBACK_TIMEOUT = 60000; // 60 秒 setInterval(() => { const now = Date.now(); Object.keys(callbackPool).forEach(callId => { const cb = callbackPool[callId]; if (now - cb.timestamp > CALLBACK_TIMEOUT) { delete callbackPool[callId]; cb.onFail && cb.onFail({ code: -4, msg: 'timeout' }); } }); }, 10000); // 每 10 秒扫一次超时时间设多少合适？这取决于业务。扫码、选图这类操作，用户可能磨蹭很久，60 秒是相对宽松的值。如果是调起一个即时确认的弹窗，10 秒就够了。超时时间宁可设长一点，因为误判超时会让用户的操作结果丢失，体验很差；而设长一点的代价只是内存里多挂一会儿回调，影响可控。
原生侧的pendingCalls同理，也需要在onDestroy或者合适的时机清理，避免 Activity 销毁后 Map 还持有引用。
注意：超时清理和正常回调之间存在竞争——如果回调刚好在清理的同一时刻到达，可能出现回调已删但结果又来的情况。JS 侧
__onNativeResult里取不到回调就直接 return，天然处理了这种竞争，不会报错。
4. 常见问题与排查技巧实录
这套方案我在几个项目里都用过，踩的坑不算少。这一节把典型问题和排查思路整理出来，基本都是文档里不会写、但实际一定会遇到的东西。
4.1 回调丢失的几种典型场景
回调丢失是最让人头疼的问题，因为现象是"点了没反应"，但原因可能有好几种。我整理了一个排查表：
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 完全没反应 | 桥对象未注入或注入时机晚于 JS 调用 | 在 JS 里打印typeof window.AndroidBridge |
| 原生页面正常但 JS 无回调 | evaluateJavascript执行失败 | 原生侧加日志，确认 JS 字符串是否合法 |
| 偶发丢失 | callId 冲突或回调池被提前清理 | 打印每次的 callId，检查是否有重复 |
| 特定机型丢失 | WebView 版本差异导致 API 行为不一致 | 换机型复现，对比 WebView 版本 |
最常见的是注入时机问题。addJavascriptInterface必须在页面加载之前调用，如果放在onPageFinished里，页面里的 JS 可能已经执行过了，桥还没注入，调用自然失败。正确做法是在WebViewClient的onPageStarted之前，或者直接在 WebView 初始化时就注入。
另一个高频问题是evaluateJavascript的字符串拼接错误。前面提过用JSONObject.quote转义，但有些人图省事直接拼，结果数据里带特殊字符就崩。排查方法很简单：把要执行的 JS 字符串先打日志出来，复制到浏览器控制台跑一下，语法对不对一目了然。
4.2 线程与生命周期的坑
addJavascriptInterface注入的方法运行在 JS 线程，这个前面强调过。但还有一个更隐蔽的问题：如果 JS 线程调用时 Activity 已经处于销毁中，runOnUiThread里的代码可能执行在一个已经 finish 的 Activity 上，startActivityForResult会抛异常或者静默失败。
我的处理方式是在runOnUiThread里先判断 Activity 状态：
activity.runOnUiThread(() -> { if (activity.isFinishing() || activity.isDestroyed()) { sendResult(callId, -5, "activity not available", null); return; } // ... 正常逻辑 });isDestroyed是 API 17 才有的，低版本需要做兼容判断。这个检查能挡掉一类"页面正在关闭时用户恰好点了按钮"的偶发崩溃。
还有一个生命周期相关的坑：WebView 所在的 Activity 被系统回收后重建。如果调用还在飞行中，重建后的 WebView 是全新的，回调池空了，原生回传的结果找不到接收方。这种场景比较极端，一般通过超时机制兜底，不追求完美恢复。
4.3 数据序列化的边界处理
JS 和原生之间传数据，本质是字符串传递，中间要经过 JSON 序列化和反序列化。这里有几个边界要注意：
- undefined 和 null：JS 的
undefined序列化后会丢失，JSON.stringify({a: undefined})得到{}。所以传参前要把 undefined 转成 null 或者空值。 - 循环引用：如果传的对象有循环引用，
JSON.stringify直接抛异常。业务数据一般不会有，但保险起见可以 try-catch。 - 大数字精度：JS 的 Number 是双精度浮点，超过 2^53 的整数会丢精度。如果原生传回一个 long 类型的 ID，JS 侧可能拿到一个不精确的值。解决办法是原生侧把大数字转成字符串再传。
- 特殊字符：换行、引号、反斜杠这些，经过
JSONObject.quote转义后是安全的，但前提是你用了转义，没用手动拼接。
实操心得：我习惯在开发阶段给所有跨端数据加一层日志，JS 侧打印发出的 payload，原生侧打印收到的 payload，回传时两边再各打一次。这样一旦数据对不上，一眼就能看出是哪一段出了问题。上线前把日志级别调高或者去掉即可。
4.4 性能与体验优化点
功能跑通只是第一步，体验上的优化还有不少空间。几个我实际做过的优化：
预加载原生页面。如果某个原生 Activity 启动慢（比如要初始化相机），可以在 WebView 加载完成后就预热，用户点击时直接复用，减少等待感。但要注意内存占用，不能无脑预加载所有页面。
结果数据的懒解析。原生回传的 JSON 如果很大，JS 侧解析会卡顿。可以在原生侧只回传必要字段，大块数据通过其他通道（比如本地存储）传递，JS 按需读取。
回调的防抖处理。用户快速连点按钮会发起多次调用，原生页面被启动多次。可以在 JS 侧加一个短时间的防抖，或者原生侧判断同一个 action 是否已有 pending 调用，有就忽略新的。
错误码的语义化。不要只回传一个数字错误码，带上可读的 msg，前端可以直接展示或者上报。错误码的划分要有体系，比如 -1 是桥不可用，-2 是未知 action，-3 是结果异常，-4 是超时，-5 是 Activity 不可用，这样排查问题时能快速定位。
5. 方案扩展与进阶思路
基础方案跑通后，如果项目规模上来了，可以考虑几个进阶方向。
5.1 从单次调用到通用桥接框架
上面这套代码是围绕"调起 Activity 拿结果"这个具体场景写的。但如果项目里跨端调用越来越多，每次都手写一套回调管理就很冗余。可以把它抽象成一个通用的桥接框架：统一的调用入口、统一的回调管理、统一的错误处理、可注册的 action 处理器。
原生侧维护一个Map<String, ActionHandler>，每个 action 对应一个处理器，新增功能只需要注册新的处理器，不用改核心逻辑。JS 侧同理，把invokeNativeActivity泛化成invokeNative(action, params)，回调管理逻辑复用。这样整个桥接层就变成了一个可扩展的基础设施。
5.2 双向通信与事件推送
目前的方案是"JS 发起、原生响应"的单向模式。但实际业务里，原生也可能主动给 JS 推事件，比如原生页面在后台完成了某个任务，需要通知 JS 刷新。这时候就需要一个反向通道。
实现方式是在 JS 侧也注册一个全局的事件接收函数，原生通过evaluateJavascript调用它。事件和回调的区别在于：回调是一次性的，事件是可以多次触发的。所以事件不需要 callId，而是用事件名来区分，JS 侧维护一个事件名到监听器列表的映射。
const eventListeners = {}; window.__onNativeEvent = function(eventName, dataJson) { const listeners = eventListeners[eventName] || []; let data; try { data = JSON.parse(dataJson); } catch (e) { return; } listeners.forEach(fn => fn(data)); }; function onNativeEvent(eventName, handler) { if (!eventListeners[eventName]) eventListeners[eventName] = []; eventListeners[eventName].push(handler); }有了事件通道，整个桥接层就从"请求-响应"升级成了完整的双向通信，能覆盖更多场景。
5.3 安全加固的几个要点
addJavascriptInterface在低版本系统上有安全风险，虽然现在主流系统版本已经修复了大部分问题，但加固措施还是值得做：
- 只暴露必要的方法，不要图省事把整个对象的所有 public 方法都暴露出去。
- 对传入参数做严格校验，前面讲的类型、范围、长度校验，同时也是安全防线。
- 敏感操作加权限校验，比如调起支付相关的原生页面，要确认当前用户已登录且有权限。
- 限制调用来源，如果 WebView 可能加载外部页面，要判断当前页面的 URL 是否在白名单内，非白名单页面不允许调用桥接方法。
这些措施在内部项目里可能显得多余，但只要 WebView 加载的内容不完全可控，就值得加上。安全这东西，出事之前都觉得没必要，出事之后都嫌加得少。
整套方案从最初的"JS 调原生拿结果"这个朴素需求出发，一路做到通用桥接框架，中间涉及的线程、生命周期、序列化、超时、安全，每一个点单独看都不复杂，但组合在一起就是一套需要认真对待的工程实践。我个人的体会是，跨端调用的难点从来不在"怎么调通"，而在"怎么在各种异常路径下都不出问题"——用户取消、页面关闭、网络超时、数据异常，这些才是真正消耗精力的地方。把错误码体系建好，把日志打全，把超时兜住，剩下的就是按部就班地填业务逻辑了。
