一、为什么要做“统一桥接层”“Write once, run anywhere” 对于纯展示型 H5 是成立的。但只要涉及到业务交互比如调起原生登录、保存图片到相册、修改系统状态栏颜色、分享到朋友圈浏览器标准的 Web API 根本无能为力。此时H5 的宿主环境通常有这几种自有 iOS App底层是 WKWebView自有 Android / 鸿蒙 App可能是原生 WebView也可能是 UniApp 壳子嵌套微信小程序底层是web-view组件微信内置浏览器公众号 H5依赖 JSSDK纯外部浏览器Safari、Chrome 等如果让前端业务组件直接去写if (isIOS) {...} else if (isWechat) {...}代码不出三个月就会变成一座屎山。因此我们需要一层Adapter适配器业务侧只管调用bridge.toLogin()具体怎么发消息交给桥接层内部去分发。二、环境探测一切通信的前提要精准分发首先要知道自己在哪。主流的做法是依托window.navigator.userAgent配合端上约定的特殊标识。export const getEnvironment () { const ua navigator.userAgent.toLowerCase(); if (ua.includes(micromessenger)) { if (ua.includes(miniprogram) || window.__wxjs_environment miniprogram) { return miniprogram; // 微信小程序 } return wechat; // 微信内置浏览器公众号 } // 假设 Android 端是用 UniApp 打包的通常会有 Html5Plus 标识 if (ua.includes(html5plus) || ua.includes(uni-app)) return android_uni; // 假设自有 iOS 原生开发约定了特殊的 UA 后缀如 MyApp/iOS if (ua.includes(iphone) ua.includes(myapp)) return ios_native; // 假设鸿蒙端约定了 OpenHarmony 标识 if (ua.includes(openharmony)) return harmony; return h5; // 兜底纯普通浏览器 };踩坑提示UA 是可以被伪造的。环境判断仅作为“前端体验分支”的依据。涉及发券、支付等核心安全逻辑必须由服务端通过 Token/Cookie 进行最终鉴权。三、各端通信底层原理与官方规范知其然也知其所以然先来扒一扒各个环境底层的通信机制。1. iOS (WKWebView)参考苹果官方文档现代 iOS 均使用WKWebView。前端向原生发消息的标准写法是window.webkit.messageHandlers.约定好的方法名.postMessage(参数)特性只能前端单向调用原生。原生如果想回传结果只能通过evaluateJavaScript直接执行一段全局挂载的 JS 函数比如window.onLoginSuccess(token)。注意postMessage的参数类型有限制强烈建议前端统一JSON.stringify传字符串iOS 端再解析避免特殊字符导致闪退或静默失败。2. Android / Harmony (以 UniApp WebView 为例)如果客户端是用 UniApp 套壳或者引入了类似的 JSBridge SDK根据 DCloud 官方文档必须先动态引入uni.webview.js建议按需动态加载单独封装。// 如果考虑极端情况原生注入极慢情况下必须在 UniAppJSBridgeReady 后才进行调用正常可以直接加载源有兴趣可以看源码最后一行触发document.dispatchEvent(new CustomEvent(UniAppJSBridgeReady)); document.addEventListener(UniAppJSBridgeReady, function() { uni.postMessage({ data: { action: toLogin, // 动作名 payload: { ... } // 业务参数 } }); });特性相比于原生 Android 的addJavascriptInterface挂载全局对象postMessage模式更符合现代前端通信规范数据结构更统一。3. 微信小程序 (web-view)参考 微信官方文档H5 端需要引入 JSSDKjweixin使用wx.miniProgram命名空间。wx.miniProgram.postMessage({ data: { foo: bar } }) wx.miniProgram.navigateTo({ url: /pages/login/login })巨大天坑小程序的postMessage绝对不是实时触发的文档明确指出只有在小程序后退、组件销毁、分享时宿主才能收到消息。所以它绝不能用来做同步的 RPC 调用比如实时获取地理位置。替代方案如果是跳页面直接用wx.miniProgram.navigateTo如果是传参直接拼在 URL 后面让小程序去解析。4. 微信内嵌 H5 (公众号 JSSDK)这块大家应该最熟不熟自己再去网上找找资料前端调后端接口拿signature执行wx.config。主要用于自定义分享卡片、扫一扫、微信支付等等。四、封装useBridge进行统一管理了解了各端差异那么就可以设计一个门面Facade。屏蔽掉这些恶心的判断逻辑。// src/hooks/useBridge.ts import { getEnvironment } from /utils/env; export function useBridge() { const env getEnvironment(); // 1. 登录能力封装 const toLogin () { switch (env) { case ios_native: // 调用 iOS 原生登录页 window.webkit?.messageHandlers?.iOSLoginIn?.postMessage(); break; case android_uni: // 通知 UniApp 宿主弹登录 uni.postMessage({ data: { action: toLogin } }); break; case miniprogram: // 跳转到小程序自己的登录页面并把当前 H5 链接带过去方便回跳 const currentUrl encodeURIComponent(window.location.href); wx.miniProgram.redirectTo({ url: /pages/login/index?webview${currentUrl} }); break; case h5: default: // 纯 H5 环境跳转到统一的 M 站登录页 window.location.href https://m.yoursite.com/login?redirect${encodeURIComponent(location.href)}; break; } }; // 2. 跳转原生页面封装 // 业务侧不需要关心各端的路由差异全传进来内部按环境取用 const openNativePage ({ ios_url, android_url, mp_url }) { if (env ios_native ios_url) { window.webkit?.messageHandlers?.iOSOpenPage?.postMessage(ios_url); } else if (env android_uni android_url) { uni.postMessage({ data: { action: openPage, url: android_url } }); } else if (env miniprogram mp_url) { wx.miniProgram.navigateTo({ url: mp_url }); } else { console.warn(当前环境不支持或未提供对应 URL); } }; return { toLogin, openNativePage /*, share, openCamera, etc. */ }; }在业务组件里script setup langts import { useBridge } from /hooks/useBridge const bridge useBridge() const handleBuy () { if (!isLogined) { bridge.toLogin() return } // 打开不同端的支付聚合页 bridge.openNativePage({ ios_url: PayViewController?sourceh5, android_url: /pages/pay/index?sourceh5, mp_url: /packagePay/pages/checkout/index }) } /script五、打通业务闭环以 Axios 401 拦截器为例Bridge 写好了怎么融入现有的业务流最经典的场景就是Token 失效后的无缝重登录。在src/utils/request.ts中import axios from axios; import { useBridge } from /hooks/useBridge; import { useUserStore } from /store/user; const instance axios.create({ /* ... */ }); const bridge useBridge(); instance.interceptors.response.use( (response) response, (error) { if (error.response?.status 401) { // 1. 清理本地前端状态 const userStore useUserStore(); userStore.clearToken(); // 2. 召唤神龙触发跨端登录 bridge.toLogin(); // 3. 挂起当前请求或抛出错误 return Promise.reject(new Error(未登录或登录已失效)); } return Promise.reject(error); } );通过这种设计前端业务请求完全不需要关心自己在哪。401 一触发如果在 App 里App 会自动弹出原生登录框体验最佳如果在微信里就会跳转到小程序的授权页。六、血与泪的实践建议避坑指南做跨端 H5 很容易扯皮因为出了问题往往不知道是前端没发出去还是客户端没拦截到。分享几个经验协议一定要文档化/枚举化不要在代码里到处写魔法字符串Magic Strings。把动作定义成 Enum比如BridgeAction.TO_LOGIN前后端、客户端三端对齐一份在线文档。永远要写兜底逻辑Fallback哪怕你的 H5 99% 的流量都在 App 内也要考虑被分享到浏览器外打开的情况。如果env h5对于必须要 App 才能用的功能请老老实实给个 Toast 提示“请在 App 内使用此功能”或者做一个拉起 App 的引导DeepLink / Scheme。巧用请求头传递环境标识在 Axios 请求拦截器里把getSource()塞到 Header比如x-client-source里。后端可以通过这个字段做接口隔离、埋点统计甚至专门给某些坑爹环境做特殊的下发逻辑。