1. 从一个真实需求说起为什么要在JS里调用安卓原生Activity做过混合开发的人大概率都遇到过这种场景你手上有一个用WebView承载的H5页面或者一个基于React Native、Cordova、Capacitor之类的跨平台应用某个功能用纯前端实现起来特别别扭——比如调用系统相机拍照、扫描二维码、选择本地文件、读取设备传感器数据、拉起一个原生支付页面。这些东西用JS直接写不是不行但要么性能拉胯要么权限处理麻烦要么根本拿不到系统级的能力。这时候最自然的思路就是让JS去调用已经写好的安卓原生Activity等原生页面处理完再把结果回传给JS。这个模式在业内一般叫“JS Bridge”或者“混合通信”核心就是三件事——JS怎么把调用请求传过去、原生怎么接收并启动Activity、Activity结束后怎么把数据送回JS。我最早接触这套东西是在一个跨平台项目里当时需要在H5里调起一个原生的图片裁剪页面裁剪完把图片路径返回给前端做预览和上传。一开始想纯前端用Canvas搞定结果发现不同机型兼容性一塌糊涂内存稍微小点的机器直接崩。后来改成原生Activity处理JS只负责传参和收结果稳定性立刻上了一个台阶。从那以后凡是遇到重计算、重系统交互的功能我都优先考虑这种“JS发起、原生执行、结果回传”的方案。这篇文章就把这套流程从头到尾拆一遍。不管你是刚接触混合开发的新手还是已经写过Bridge但总在回调丢失、数据格式错乱上踩坑的老手下面这些内容应该都能对你有用。我会从整体设计思路讲起然后深入到参数传递、Activity启动、结果回传、异常处理这些关键环节最后把我自己踩过的坑和排查经验整理出来。2. 整体设计思路JS与原生到底怎么“对话”2.1 三种主流通信方式的取舍JS要和安卓原生通信摆在面前的路其实就那么几条我先把它们列出来对比一下你就知道为什么大多数场景下我们会选特定的那一种。通信方式方向是否支持返回值实现复杂度适用场景addJavascriptInterfaceJS调原生同步返回但无法等待异步结果低简单的同步查询、获取配置WebViewClient拦截URLJS调原生需配合回调较绕中老项目兼容、无返回值通知evaluateJavascript原生调JS单向低原生主动通知JS自定义Scheme 回调双向支持中高需要异步返回结果的场景单纯从“调用Activity并获取返回结果”这个需求来看addJavascriptInterface配合evaluateJavascript回调是最直接、最可控的组合。原因很简单Activity的启动和结果是异步的JS调用原生方法的那一刻拿不到结果必须等原生页面关闭后才能回传。所以我们需要一个“JS调原生”的入口再加一个“原生调JS”的出口两者配合才能完成一次完整的往返。注意addJavascriptInterface在早期版本有过安全漏洞所以在注入对象时一定要控制好暴露的方法范围不要图省事把整个对象的所有方法都开放出去。另外从Android 4.2开始被JS调用的方法必须显式加上JavascriptInterface注解否则不会生效这个坑新手经常踩。2.2 一次完整调用的生命周期我把整个流程拆成六个阶段这样你在写代码的时候心里有个清晰的时序概念JS侧发起调用前端通过注入的对象调用一个约定好的方法把参数比如操作类型、配置项传过去。原生侧接收请求被JavascriptInterface标注的方法在主线程被触发解析JS传来的参数。原生启动Activity通过Intent拉起目标Activity如果需要返回值用startActivityForResult或者ActivityResultLauncher。用户在原生页面操作拍照、裁剪、选择、填写这一步和JS完全无关。Activity结束并回传数据在onActivityResult或注册的回调里拿到结果整理成JS能识别的格式。原生回调JS通过evaluateJavascript执行一段JS代码把结果作为参数传回去JS侧的回调函数被触发。这六个阶段里最容易出问题的就是第3步和第6步。第3步涉及Intent的构造和requestCode的管理第6步涉及线程切换和JSON序列化。后面我会分别展开讲。2.3 为什么不用纯前端方案替代有人可能会问拍照、选文件这些H5不是有input标签吗为什么非要绕一圈调原生这个问题我专门做过对比测试。以拍照为例H5的input typefile acceptimage/* capturecamera在部分机型上确实能拉起相机但问题在于你拿不到原图系统会压缩你控制不了裁剪界面不同厂商的浏览器行为差异巨大而且用户取消拍照后前端很难准确判断是取消了还是出错了。相比之下原生Activity可以精确控制每一个环节返回的图片质量、路径、状态都是确定的。再比如扫描二维码纯前端方案要么依赖摄像头权限的反复申请要么识别率受限于浏览器实现。原生调用系统的扫码能力或者集成成熟的扫码库识别速度和准确率完全不是一个量级。所以结论很明确凡是涉及系统级交互、需要精确控制结果、对性能和稳定性有要求的功能都值得走原生Activity这条路。JS负责界面和业务逻辑原生负责重活和系统交互各司其职。3. 核心细节拆解参数、启动、回传三件套3.1 JS侧怎么把参数传得漂亮JS调原生参数传递看似简单其实有很多讲究。最朴素的做法是传一个字符串原生收到后再解析。但实际项目里参数往往不止一个而且类型各异——有字符串、有数字、有布尔值、还有嵌套的对象。我的建议是统一用JSON字符串传递。JS侧把参数对象序列化成JSON原生侧用JSONObject解析。这样做的好处是结构清晰、扩展方便加字段不用改方法签名。// JS侧调用示例 window.AndroidBridge.startNativePage( JSON.stringify({ action: cropImage, sourcePath: /storage/emulated/0/DCIM/photo.jpg, aspectRatio: 1.0, outputQuality: 90, requestId: req_20240101_001 }) );这里有几个细节值得说requestId这个字段非常关键。如果你的应用可能同时发起多个原生调用没有唯一标识就分不清哪个结果对应哪个请求。我一般用时间戳加随机数生成保证不重复。action用一个字段区分不同的原生操作这样一个Bridge方法就能处理多种需求不用为每个功能单独开一个接口。参数校验JS侧传之前最好做一次基本校验比如路径不能为空、比例必须是正数。原生侧收到后也要再校验一次不能信任前端传来的任何数据。实操心得JSON序列化时注意特殊字符的转义。如果参数里包含引号、换行符直接拼接字符串会出问题。用JSON.stringify是最稳妥的不要自己手动拼。3.2 原生侧接收参数的完整实现原生这边首先要在WebView初始化的时候注入桥接对象。我一般会写一个专门的Bridge类把所有暴露给JS的方法集中管理。public class JsBridge { private Context context; private WebView webView; private ActivityResultLauncherIntent launcher; private String currentRequestId; public JsBridge(Context context, WebView webView) { this.context context; this.webView webView; } JavascriptInterface public void startNativePage(String paramsJson) { try { JSONObject params new JSONObject(paramsJson); String action params.optString(action); String requestId params.optString(requestId); this.currentRequestId requestId; if (cropImage.equals(action)) { Intent intent new Intent(context, CropActivity.class); intent.putExtra(source_path, params.optString(sourcePath)); intent.putExtra(aspect_ratio, (float) params.optDouble(aspectRatio, 1.0)); intent.putExtra(output_quality, params.optInt(outputQuality, 90)); launcher.launch(intent); } } catch (JSONException e) { callbackToJs(requestId, false, 参数解析失败, null); } } }这里我用了ActivityResultLauncher而不是传统的startActivityForResult原因是后者在新版本里已经被标记为废弃而且requestCode的管理容易混乱。ActivityResultLauncher的注册需要在Activity或Fragment创建时完成回调逻辑更清晰。// 在Activity的onCreate中注册 launcher registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), result - { if (result.getResultCode() Activity.RESULT_OK result.getData() ! null) { String croppedPath result.getData().getStringExtra(result_path); callbackToJs(currentRequestId, true, 裁剪成功, croppedPath); } else { callbackToJs(currentRequestId, false, 用户取消, null); } } );3.3 结果回传evaluateJavascript的正确用法Activity处理完拿到结果后最后一步是把数据送回JS。这里必须用evaluateJavascript而且必须在主线程执行。private void callbackToJs(String requestId, boolean success, String message, String data) { JSONObject result new JSONObject(); try { result.put(requestId, requestId); result.put(success, success); result.put(message, message); result.put(data, data); } catch (JSONException e) { e.printStackTrace(); } final String jsCode javascript:window.onNativeResult( result.toString() ); webView.post(() - webView.evaluateJavascript(jsCode, null)); }几个关键点webView.post确保在主线程执行evaluateJavascript必须在UI线程调用。javascript:前缀虽然有些版本不加也能执行但加上更保险兼容性更好。JSON转义result.toString()出来的字符串如果直接拼进JS代码里面的引号会破坏语法。正确做法是用JSONObject.quote()对字符串做转义或者干脆把整个JSON作为字符串参数传递。踩过的坑有一次回传的图片路径里包含中文和空格直接拼接导致JS报语法错误。后来改成先对路径做URLEncoder编码JS侧再解码问题解决。所以凡是回传字符串都要考虑特殊字符的处理。4. 实操全流程从零搭一个可运行的Demo4.1 环境准备与项目结构假设你用的是Android Studio创建一个带WebView的基础项目。目录结构大概是这样app/src/main/java/com/example/hybrid/ ├── MainActivity.java // 承载WebView的Activity ├── JsBridge.java // 桥接类 ├── CropActivity.java // 原生功能页面 └── assets/ └── index.html // 前端页面MainActivity的布局就是一个全屏WebView加载assets里的index.html。WebView需要开启JavaScript支持并注册桥接对象。WebView webView findViewById(R.id.webview); WebSettings settings webView.getSettings(); settings.setJavaScriptEnabled(true); settings.setAllowFileAccess(true); settings.setDomStorageEnabled(true); JsBridge bridge new JsBridge(this, webView); webView.addJavascriptInterface(bridge, AndroidBridge); webView.loadUrl(file:///android_asset/index.html);4.2 前端页面的调用与回调index.html里放一个按钮点击后调用原生方法并定义好回调函数。!DOCTYPE html html head meta charsetutf-8 title混合调用示例/title /head body button onclickcallNative()调用原生裁剪/button div idresult/div script function callNative() { var params { action: cropImage, sourcePath: /sdcard/test.jpg, aspectRatio: 1.0, outputQuality: 90, requestId: req_ Date.now() }; window.AndroidBridge.startNativePage(JSON.stringify(params)); } // 原生回调入口必须挂到window上 window.onNativeResult function(result) { var data typeof result string ? JSON.parse(result) : result; if (data.success) { document.getElementById(result).innerText 成功 data.data; } else { document.getElementById(result).innerText 失败 data.message; } }; /script /body /html这里有个细节evaluateJavascript传回来的如果是JSON字符串JS侧收到的是字符串类型需要手动JSON.parse。如果传的是对象字面量则可以直接用。我一般统一传字符串解析逻辑放在JS侧这样原生侧不用关心JS的数据结构。4.3 原生Activity的编写要点CropActivity就是一个普通的Activity负责展示裁剪界面处理用户操作最后通过setResult回传数据。public class CropActivity extends AppCompatActivity { Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_crop); String sourcePath getIntent().getStringExtra(source_path); float ratio getIntent().getFloatExtra(aspect_ratio, 1.0f); int quality getIntent().getIntExtra(output_quality, 90); // 初始化裁剪控件加载图片 // ...省略具体UI逻辑 findViewById(R.id.btn_confirm).setOnClickListener(v - { String outputPath performCrop(sourcePath, ratio, quality); Intent result new Intent(); result.putExtra(result_path, outputPath); setResult(RESULT_OK, result); finish(); }); findViewById(R.id.btn_cancel).setOnClickListener(v - { setResult(RESULT_CANCELED); finish(); }); } }注意在AndroidManifest.xml里注册这个Activity如果涉及文件读写还要申请对应的权限。从Android 6.0开始危险权限需要运行时申请这个在拉起Activity之前就要处理好否则Activity里操作文件会直接崩溃。4.4 参数计算与选择过程以裁剪功能为例aspectRatio和outputQuality这两个参数不是随便填的。aspectRatio决定了裁剪框的宽高比1.0是正方形16/9是宽屏这个要根据业务需求来。outputQuality影响图片质量和文件大小90通常是个平衡点再高文件会明显变大再低画质损失肉眼可见。我在实际项目里做过测试一张4000x3000的原图quality从100降到90文件大小从4.2MB降到1.8MB肉眼几乎看不出差别降到70文件大小1.1MB放大后能看出轻微模糊。所以除非有特殊要求90是个比较稳妥的默认值。requestId的生成也有讲究。如果只是单次调用用时间戳就够了。但如果短时间内可能发起多次时间戳可能重复需要加上随机数或者自增序列。我一般用req_加时间戳加三位随机数重复概率极低。5. 常见问题与排查技巧实录5.1 回调丢失为什么JS收不到结果这是最高频的问题。表现是原生Activity正常关闭了但JS侧的回调函数就是不执行。排查思路按这个顺序来排查项可能原因解决方法evaluateJavascript是否执行不在主线程调用用webView.post包裹JS函数是否挂载函数名拼写错误或未挂到window检查window.onNativeResult是否存在参数是否合法JSON字符串含未转义字符用JSONObject.quote处理WebView是否已销毁Activity已finish但WebView还在回调回调前判断webView是否为空线程是否阻塞回调在子线程执行强制切回主线程我遇到过一次特别隐蔽的情况Activity在回调之前被系统回收了webView引用变成nullevaluateJavascript直接抛异常但异常被吞掉了导致看起来像“回调丢失”。后来在回调方法里加了空判断和日志才定位到问题。避坑技巧在callbackToJs方法里加一行日志打印requestId和结果。这样一旦回调没触发你能快速判断是原生没执行回调还是JS没接收到。5.2 数据格式错乱中文乱码与特殊字符JS和原生之间传字符串编码问题几乎不可避免。最常见的是中文变成问号或者乱码。原因是JSON序列化时如果没指定编码某些环节会按默认编码处理。解决方法很简单全程用UTF-8。JS侧JSON.stringify默认就是UTF-8原生侧JSONObject也支持UTF-8。如果还是乱码检查WebView的编码设置确保settings.setDefaultTextEncodingName(UTF-8)。另一个坑是特殊字符。比如路径里有单引号、双引号、反斜杠直接拼进JS代码会破坏语法。我的做法是所有回传给JS的字符串先用JSONObject.quote()做转义这样引号和反斜杠都会被正确处理。5.3 内存泄漏WebView与Activity的引用关系WebView是个很容易造成内存泄漏的组件。如果JsBridge持有Activity的强引用而WebView又持有JsBridgeActivity销毁时这一串引用都释放不掉。我的处理方式是JsBridge里用WeakReference持有Context和WebView或者在Activity的onDestroy里主动调用webView.destroy()并清空桥接对象。另外addJavascriptInterface注入的对象在WebView销毁后仍然可能被JS调用所以要在销毁前把桥接对象置空。Override protected void onDestroy() { if (webView ! null) { webView.removeJavascriptInterface(AndroidBridge); webView.destroy(); webView null; } super.onDestroy(); }5.4 权限问题Activity启动前的必要检查如果目标Activity需要相机、存储等权限必须在启动前申请。否则Activity启动后操作相关硬件会直接崩溃。我的做法是在JsBridge的startNativePage方法里先检查权限没有就申请申请通过后再启动Activity。这里有个时序问题权限申请是异步的申请结果回来后才能启动Activity。所以需要把启动逻辑放到权限回调里不能直接顺序执行。这一点在写代码时容易忽略导致第一次调用失败第二次才成功。6. 进阶优化让这套方案更稳更快6.1 回调管理的规范化当原生调用变多之后零散的回调逻辑会变得难以维护。我建议做一个简单的回调管理器用requestId作为key把JS侧的回调函数存起来原生回传时根据requestId找到对应的回调执行。var callbackMap {}; function callNative(action, params, callback) { var requestId req_ Date.now() _ Math.floor(Math.random() * 1000); callbackMap[requestId] callback; params.requestId requestId; params.action action; window.AndroidBridge.startNativePage(JSON.stringify(params)); } window.onNativeResult function(resultStr) { var result JSON.parse(resultStr); var cb callbackMap[result.requestId]; if (cb) { cb(result); delete callbackMap[result.requestId]; } };这样调用方只需要关心自己的回调不用管requestId的生成和匹配。原生侧也不用改仍然是原样回传。6.2 超时处理与异常兜底原生Activity有可能因为各种原因不返回结果——用户按了Home键、系统杀进程、Activity崩溃。如果JS侧一直等回调用户体验会很差。所以需要加超时机制。function callNativeWithTimeout(action, params, callback, timeout) { var timer setTimeout(function() { delete callbackMap[params.requestId]; callback({ success: false, message: 操作超时 }); }, timeout || 30000); callNative(action, params, function(result) { clearTimeout(timer); callback(result); }); }30秒是个比较合理的默认值具体可以根据操作类型调整。拍照可能10秒就够文件选择可能要60秒。6.3 多进程与多WebView场景如果应用里有多个WebView或者运行在多进程环境桥接对象的管理会更复杂。每个WebView需要独立的JsBridge实例requestId也要全局唯一否则回调会串。我的做法是在requestId里加上WebView的标识回调时根据标识找到对应的WebView执行evaluateJavascript。这套方案我从最早的单一WebView用到现在多进程多WebView核心逻辑没变过只是在外围加了一层管理。只要把requestId这个纽带维护好再复杂的场景也能hold住。最后分享一个我个人的习惯每次写完Bridge相关代码我都会在JS侧加一个测试按钮模拟各种异常情况——传空参数、传非法JSON、中途取消、超时。把这些边界情况都跑一遍上线后基本不会出大问题。混合开发的坑大多不在正常流程而在这些边边角角的地方。