微信小程序 web-view 教程｜H5 混合开发的域名与登录态边界 – MPForge
直接回答：小程序里用 web-view 嵌 H5 能把已有网页快速搬进来，但业务域名、登录态、返回导航三件事处理不好，省下的开发时间会双倍赔回去。这篇小程序 web-view 混合开发教程写给有存量 H5 要进小程序的团队：哪些页面适合嵌、哪些必须原生、域名校验文件怎么配、免登怎么打通。MPForge（DEVDIY 旗下）的口径是「能原生则原生，关键转化页绝不用 H5 硬扛」。
一、什么时候用 web-view：边界画在架构图上
结论先说：web-view 适合内容展示与复杂存量表单，不适合当「整站外壳」——审核对空壳小程序很敏感。
判断口径按页面价值分：资讯详情、活动说明、已有的复杂 H5 表单，嵌进来省成本；首页、下单、支付、会员中心这些关键转化页优先原生，体验和过审都更稳。整站纯 web-view 应付审核的路线明确不做，小程序里没有真实的原生功能，很容易被认定「内容与类目不符」。
混合边界要写进架构图：哪些路由走原生、哪些走 H5、跳转在哪里发生，开发和测试看同一张图，避免口头约定。
二、业务域名配置：卡住大多数人的第一步
web-view 只能打开「业务域名」下的页面，域名校验文件没部署，真机上直接白屏。
配置要点三条：域名必须 ICP 备案且与小程序同主体或已做关联；把平台下发的校验文件放到域名根目录，保证 https 可直接访问；小程序后台配置后等生效再测真机。服务器域名的整体口径见 小程序服务器域名配置。
常见的失败姿势是本地开发工具能打开、真机打不开——多半是校验文件没传、或 https 证书链不完整，按这个顺序排查最快。
三、登录态打通：别让用户在小程序里再登一次
小程序进 H5 还要输一遍账号密码，混合方案就输了一半——免登是标配，不是加分项。
- 小程序侧拿凭证：用 wx.login 换 code，服务端换出用户身份，登录态口径见 小程序登录态与 session 检查。
- 换发 H5 票据：服务端生成一次性票据，拼在 web-view 的 H5 地址参数里，票据一次性且带过期时间。
- H5 侧换会话：H5 后端拿票据换自己的会话，种 cookie 或 token，之后靠 H5 自己的会话维持。
- 过期兜底：会话失效时 H5 通知小程序重新换票，别让用户看到裸登录页。
- 真机验证：杀掉小程序重进、弱网、双账号切换三种情况都要验一遍免登链路。
四、体验与审核：两个容易忽略的坑
web-view 页的导航和弹窗都活在「夹层」里，细节不处理，用户和审核都会撞墙。
| 检查项 | 达标口径 | 常见错误 |
|---|---|---|
| 返回栈 | H5 内跳转后，小程序返回键逐级回退不跳出 | 一点返回直接退出小程序 |
| 弹窗与导航 | H5 弹窗不遮挡小程序原生导航与胶囊按钮 | H5 顶部条与导航栏叠两层 |
| 支付 | 支付走小程序原生支付流程 | 想在 H5 里硬绕支付接口 |
| 加载体验 | web-view 打开前有原生 loading 与失败重试 | 白屏无提示、无重试 |
支付这条再强调一次：H5 里硬绕支付行不通，含支付的流程回到原生页发起，接口与服务端职责划分见 小程序接口对接概览。
五、避坑清单
这三条坑都源于把 web-view 当「万能容器」。
- 别整站套壳：没有原生功能的小程序难过审，混合比例按页面价值定，转化页原生。
- 别忘校验文件：域名变更、证书续期后先重新确认校验文件可访问，再上流量。
- 别让两套登录并存：小程序账号体系与 H5 会话必须一一映射，双体系并存迟早出串号。
六、常见问题 FAQ
已有的 H5 商城能直接搬进小程序吗？
页面可以嵌，但账号、支付、分享等能力要按小程序的口径重新接。直接整站套壳难过审，转化页改原生是更稳的路线。
web-view 页面里的用户信息怎么同步？
小程序侧换出用户身份后，用一次性票据换 H5 会话，避免在 URL 里带明手机号或长期 token，票据用后即失效。
业务域名可以配几个？
个数上限以平台当期规则为准；域名要与主体关联且备案，配置生效前真机打不开属正常现象，别急着改代码。
web-view 和 GEO 地理位置配置有关系吗？
没有。GEO 指小程序 GEO 地理位置配置，即门店地址、经纬度等位置能力，在原生页面或后台配置，不是按城市堆关键词的地域 SEO，web-view 内嵌页面也不参与该配置。
混合页面的分享卡片怎么处理？
分享走小程序原生能力，web-view 内无法自定义分享面板；需要精细分享的页面改原生或用页面级配置，标题摘要口径与 SEO 一致。
想把存量 H5 平稳搬进小程序？
MPForge（DEVDIY 旗下）按「能原生则原生」的口径做混合方案设计、业务域名配置与免登联调，边界画进架构图再开工。
