结论先行:web-view 是小程序复用存量 H5 的官方通道,适合内容页、活动页、长尾业务快速迁移;但它有硬边界——必须配置业务域名并放校验文件、个人主体小程序不支持、H5 与小程序登录态天然隔离、支付要跳回小程序原生页完成。通信只靠 JSSDK 提供的少数接口,且 postMessage 不是实时通道。把边界认清再设计架构,混合开发才不会返工。能力细节以微信官方最新文档为准。
一、接入配置:业务域名是门槛
web-view 组件承载的网页域名必须先在小程序后台「开发管理 - 开发设置 - 业务域名」中配置:域名需 ICP 备案、HTTPS,并下载校验文件放到域名根目录可访问。业务域名与 request 合法域名是两套独立配置,别混。另外几个官方约束:
- 个人类型小程序暂不支持 web-view;
- web-view 会自动铺满整个页面,个人定制导航栏要自行处理;
- 网页内 iframe 的域名同样要在白名单内;
- 每个页面只能有一个 web-view,组件内不能再嵌小程序页面。
二、通信机制:只有这几个接口
H5 侧引入微信 JSSDK 后,可用的桥接接口是 wx.miniProgram 系列:
| 接口 | 方向 | 用途 |
|---|---|---|
| navigateTo / redirectTo / switchTab / reLaunch | H5 到小程序 | 跳转小程序页面 |
| navigateBack | H5 到小程序 | 返回小程序上一页 |
| postMessage | H5 到小程序 | 向小程序传数据 |
| getEnv | H5 侧判断 | 确认是否在小程序环境 |
最大的认知误区是 postMessage 的时机:它不是实时消息通道,H5 调用后消息不会立刻到达小程序,而是在特定时机(小程序后退、web-view 组件销毁、分享等)才触发 bindmessage 回调把消息批量带回。所以「H5 里点个按钮、小程序立刻收到数据」这种设计不成立。实时交互的正确姿势是:H5 用 navigateTo 跳转小程序页面并把数据放 URL 参数,或者双方都请求同一个后端接口、以服务端数据为准。
// H5 侧:跳回小程序原生页并携带结果
wx.miniProgram.navigateTo({
url: '/pages/order/confirm?ticket=' + ticket
});
// 小程序侧:接收延迟消息
// wxml: web-view 绑定 bindmessage
onMessage(e) {
console.log(e.detail.data); // 数组,含多次 postMessage 的内容
}三、登录态:隔离是常态,票据是桥梁
小程序的 storage 与 web-view 内 H5 的 cookie、localStorage 完全隔离,小程序登录态不会自动带给 H5。可行方案:
- 小程序打开 web-view 前,向服务端申请一个短时效、一次性的 ticket,拼在 URL 上;
- H5 加载后用 ticket 换取自己的会话,ticket 立即作废;
- 不要把长期 token 直接放 URL——会进访问日志与分享链接,泄露面太大;
- H5 内登录失效时,用 navigateTo 跳回小程序登录页重新走授权。
如果后端用「api工厂」(https://www.it120.cc/)这类统一开放平台,小程序与 H5 调的是同一套接口与用户体系:apifm-wxapi 在小程序端拿到的用户数据,H5 端用同一账号的 token 请求同样接口即可,CMS 文章、商品、订单天然共享,混合架构下最头疼的「两套数据」问题直接消失。接口文档见 https://www.it120.cc/help/index.html 。
四、支付限制:交易回原生页
这是混合开发最容易翻车的一点:web-view 内的 H5 不是公众号网页环境,不能照搬公众号 JSAPI 支付那套 WeixinJSBridge 流程。正确做法是把支付环节交回小程序原生:
- H5 完成选品与下单确认,服务端创建订单;
- H5 用 wx.miniProgram.navigateTo 跳到小程序原生收银页,URL 带订单号或短时效 ticket;
- 原生页向服务端取调起参数,wx.requestPayment 拉起微信支付;
- 支付结果以服务端回调为准,原生页轮询确认后展示结果,需要回 H5 时再 navigateBack。
这条链路多一次跳转,但资金安全与结果一致性都有保障。同理,微信授权登录、获取手机号这类开放能力也只能在原生页完成,H5 里做不了。
五、架构取舍:什么放 H5,什么留原生
| 场景 | 建议 | 理由 |
|---|---|---|
| 协议、帮助、资讯文章 | H5 | 更新频繁,免发版 |
| 营销活动页 | H5 或原生 | 短周期活动 H5 灵活,强交互用原生 |
| 商品详情、购物车、下单 | 原生 | 体验与转化主链路 |
| 支付、登录、手机号 | 原生 | 开放能力限制 |
| 存量复杂业务系统 | web-view 过渡 | 先上线再逐步原生化 |
另外记住审核边界:小程序内容要符合平台规范,web-view 里的 H5 同样在审核范围,诱导分享、外链导流在 H5 里做一样会被处理;H5 改版不需要小程序发版,但重大功能变化仍建议同步提审说明。
六、自查清单
- 业务域名是否备案、HTTPS、校验文件可访问,iframe 域名是否也配置;
- 是否误把 postMessage 当实时通道设计交互;
- 登录态是否用短时效票据传递,长期 token 是否出现在 URL;
- 支付与开放能力是否全部回到原生页完成;
- 主链路体验是否评估过 web-view 的加载与导航成本。