一、通信整体架构
小程序内嵌 H5 运行在独立 WebView 浏览器沙箱中,与小程序原生逻辑层线程隔离、环境隔离、全局变量隔离。
两者无法直接调用对方方法、无法直接共享内存、无法直接读取对方存储,只能通过微信官方桥接通信机制完成数据交互。
整个通信体系分为两套:
1. 小程序内置桥接:wx.miniProgram(无需引入 JS-SDK)
2. 公众号 JS-SDK 能力桥接(需引入 jweixin.js)
二、核心能力边界
2.1 wx.miniProgram 桥接能力(H5 专属小程序桥)
当且仅当 H5 运行在小程序 WebView 中,浏览器自动注入 window.wx.miniProgram。
支持API(仅路由+消息):
页面跳转:navigateTo / redirectTo / switchTab / reLaunch / navigateBack
环境判断:getEnv()
消息上行:postMessage(H5 → 小程序)
wx.miniProgram.navigateTo()
wx.miniProgram.redirectTo()
wx.miniProgram.switchTab()
wx.miniProgram.navigateBack()
wx.miniProgram.reLaunch()
wx.miniProgram.getEnv()
wx.miniProgram.postMessage()
绝对不支持:
不支持扫码、定位、拍照、授权、获取手机号
不支持小程序支付 requestPayment
不支持任何小程序原生设备 API
结论:wx.miniProgram 只是路由和消息通道,不是能力调用通道。
2.2 JS-SDK 能力边界(公众号体系)
H5 引入 jweixin-1.6.0.js 后可调用部分微信能力:
扫码、定位、拍照、选择图片、分享
公众号 JSAPI 支付(与小程序支付不互通)
无法调用小程序原生 API
无法拉起小程序支付
三、两种通信方式详细机制与坑点
3.1 H5 → 小程序:postMessage 上行通信
调用方式(H5 端):
wx.miniProgram.postMessage({
data: { type: 'xxx', value: 'xxx' }
})
官方致命机制:消息不是实时触发!
仅在以下时机,小程序才会接收消息:
WebView 页面关闭
WebView 页面后退
WebView 页面跳转
不能用于实时指令通信!不能用于实时回调!
适合:上报页面状态、页面关闭携带数据、埋点数据上报
不适合:支付唤起、定位回调、表单提交、实时校验
3.2 小程序 → H5:webview.postMessage 下行通信
小程序通过 selectComponent 获取 web-view 实例,主动向 H5 下发数据。
该通道是实时的!可用于双向实时通信!
小程序端代码:
const webview = this.selectComponent("#webview");
webview.postMessage({
token: "xxxx",
userInfo: {}
})
H5 端监听:
window.addEventListener('message', function(res){
console.log('小程序下发数据:', res.data)
})
唯一可靠、实时的双向通信下行通道
四、行业标准可靠通信方案(解决实时通信问题)
由于 wx.miniProgram.postMessage 不可实时,项目统一采用:
标准实时双向通信架构
1. H5 需要小程序能力 / 下发指令
H5 使用 wx.miniProgram.navigateTo 跳转到小程序原生中间业务页,携带参数。
小程序原生页完成:扫码/定位/支付/授权/获取手机号
完成后再跳回 WebView H5 页面,带回结果参数。
优势:100% 稳定、无异步时序问题、无兼容bug、所有原生能力全覆盖
2. 小程序主动同步登录态、用户信息给 H5
页面初始化后,小程序通过 webview.postMessage 实时下行 同步 Token、用户信息、权限。
五、完整通信场景适配规范
| 业务场景 | 推荐通信方式 | 禁止使用方式 |
|---|---|---|
| H5 获取登录态、用户信息 | 小程序 webview.postMessage 实时下发 | H5 上行 postMessage 拉取 |
| H5 唤起扫码/定位 | 跳转小程序原生页执行能力后回传 | H5 JSSDK 直接调用(兼容差) |
| H5 唤起小程序支付 | 跳转小程序原生支付中间页 | JSSDK 公众号支付(体系不互通) |
| H5 关闭页面、返回首页 | wx.miniProgram.navigateBack | 前端 history 回退 |
| H5 上报页面关闭数据 | wx.miniProgram.postMessage | 实时指令通信 |
六、通信安全规范(建议强制执行)
H5 属于外网资源,所有双向消息默认不可信,必须做安全校验。
6.1 消息协议规范
所有通信数据统一格式:
{
"type": "指令类型",
"data": {},
"timestamp": xxxxxx,
"sign": "签名"
}
6.2 安全校验规则
小程序接收 H5 消息必须校验时间戳、签名、指令白名单
禁止 H5 直接触发小程序跳转、支付、权限操作
所有高危指令必须二次鉴权
WebView 加载域名必须前端白名单校验 + 小程序后台业务域名配置
七、常见问题与坑点总结
1. postMessage 无法实时通信:仅页面销毁触发,绝对不能用于业务回调
2. wx.miniProgram 没有任何设备能力:只能跳转和发消息
3. H5 无法调用小程序支付:只能通过原生页中转
4. JSSDK 能力属于公众号体系:与小程序能力、商户、授权不互通
5. 双向消息无默认隔离:必须自行加协议防伪造、防篡改
八、方案总结
H5 与小程序核心桥接通道为 wx.miniProgram(路由) 和 webview.postMessage(实时下行)。
官方 H5 上行 postMessage 不实时,不能用于业务交互。
所有微信原生核心能力(支付、扫码、定位、授权)必须通过小程序原生中间页中转架构实现,为唯一稳定方案。
所有跨环境通信必须遵循统一协议与安全校验规范,防止消息伪造与安全攻击。