简介:本资源是一份面向微信小程序初学者与H5开发者的技术实践包,聚焦将现有H5网站快速封装为合规可上线的微信小程序,解决跨平台复用、轻量交付与微信生态接入等实际痛点。资源共19个文件,包含5个json(用于页面路由、全局配置及sitemap定义)、4个js(含工具函数与页面逻辑封装)、3个wxss(适配小程序样式的CSS转换结果)、2个wxml(H5结构转译后的页面模板)以及README.md和LICENSE等辅助文档,整体压缩包仅355KB,轻量易导入。已有993人学习下载,内容结构清晰,覆盖从项目初始化、WXML/WXSS/JS三端重构、静态资源路径调整到域名配置与真机调试的全流程关键节点,特别提供app.json、project.config.json等核心配置文件范例及pages目录组织方式,便于开发者直接参考迁移、规避常见兼容性陷阱。
1. 微信小程序封装H5域名:不是“套个壳就上线”,而是把网页变成可交互、可审核、能过审的小程序实体
你手头有个跑在 https://xxx.com 上的 H5 网站,页面流畅、功能完整,用户也习惯用它。现在想快速上微信生态——不是重写,不是重构,是“原样搬进去”。但现实很骨感:直接用微信开发者工具新建项目、填个域名、点“预览”,99% 的人会卡在第一步:白屏、报错 navigateTo:fail url not in domain list 、控制台疯狂刷 request:fail net::ERR_CONNECTION_REFUSED 。这不是网络问题,是微信对 H5 封装的硬性规则在起作用: 它不接受裸域名跳转,也不允许跨域 iframe 嵌套,更拒绝未备案/未配置业务域名的任何资源加载 。这份 h5_xcx-master.zip 不是“一键生成器”,而是一套经过真实项目验证的轻量级封装骨架——它用 web-view 作为主容器,但绕开了 web-view 的权限黑洞;它保留了原有 H5 的路由和状态,却让 onLoad 、 onShow 、 onShareAppMessage 这些生命周期真正可用;它把 app.json 的 pages 配置、 sitemap.json 的索引逻辑、 project.config.json 的调试开关全写死在结构里,省去你反复试错。适合三类人:运营团队要快速上线活动页、传统企业想复用现有官网、前端工程师接手 legacy H5 项目但没时间重写小程序。它解决的不是“能不能显示”,而是“怎么让微信平台认你这个‘小程序’是合法、可交互、能过审的实体”。
2. 封装核心: web-view 是入口,但必须配 custom-tab-bar + page-router 才算真落地
2.1 为什么不用 WebView 组件?——微信的 web-view 和浏览器 iframe 本质不同
微信小程序的 <web-view> 组件不是简单的 iframe 嵌套。它运行在独立的 WebView 环境中,与小程序 JS 引擎隔离,无法直接调用 wx.request 、 wx.getLocation 、 wx.login 等 API,也不能监听小程序页面生命周期。但它的优势在于: 支持 HTTPS 域名直连、兼容主流 H5 框架(Vue/React)、支持 bindmessage 与 H5 双向通信 。本项目放弃“纯静态 HTML 转 WXML”的老路(那种方式要重写所有 DOM 事件、适配 rpx、处理 window.location ),而是以 web-view 为唯一视图容器,把整个 H5 当作“子应用”加载。关键点在于: web-view 必须放在 pages/index/index.wxml 的根节点,且 src 属性必须是 HTTPS 协议 + 已在微信公众平台配置的业务域名 (注意:不是服务器域名,是“业务域名”,且仅支持 https:// 开头,不支持 http:// 或 www. 前缀)。
<!-- pages/index/index.wxml -->
<view class="container">
<web-view src="{{webUrl}}" bindmessage="handleMessage"></web-view>
</view>
提示:
webUrl必须是字符串,不能是模板表达式如{{'https://xxx.com' + path}},否则web-view初始化失败。实际开发中,我一般在index.js的onLoad中拼接完整 URL 并setData,而非在 WXML 中计算。
2.2 custom-tab-bar :让 H5 页面拥有小程序原生导航栏
H5 页面本身没有顶部导航栏,但微信用户已习惯“左上角返回、右上角更多、中间标题”。本项目在 app.json 中启用了自定义 tabBar,并在 pages/index/index.wxml 中插入 <custom-tab-bar /> 组件。该组件位于 components/custom-tab-bar/ ,其 index.js 内部通过 wx.getMenuButtonBoundingClientRect() 获取胶囊按钮位置,动态计算导航栏高度(适配 iPhone X+、安卓刘海屏),再用 wx.setNavigationBarColor() 同步设置背景色。重点是: 它不接管 H5 的路由,只提供视觉层统一入口 。当用户点击 tab 切换时, custom-tab-bar 触发 wx.switchTab({url: '/pages/index/index'}) ,并通知 H5 页面执行 location.reload() 或 history.pushState() ,保持单页应用体验。
// components/custom-tab-bar/index.js
Component({
methods: {
switchToIndex() {
wx.switchTab({ url: '/pages/index/index' })
// 通知 H5 页面刷新或跳转
this.triggerEvent('tabchange', { tab: 'home' })
}
}
})
2.3 page-router :用小程序路由劫持 H5 的 history.pushState
H5 页面内部跳转(如 Vue Router 的 router.push('/detail?id=123') )默认触发 window.history.pushState() ,但小程序 web-view 不会响应。本项目在 H5 页面中注入一段 postMessage 监听脚本(见 utils/webview-bridge.js ),当 H5 调用 history.pushState() 时,自动向小程序发送消息:
// H5 页面中引入(需部署到你的 H5 域名下)
if (window.__wxjs_environment === 'miniprogram') {
window.addEventListener('popstate', (e) => {
window.postMessage({ type: 'HISTORY_CHANGE', data: e.state }, '*')
})
}
小程序端在 pages/index/index.js 的 handleMessage 方法中接收该消息,并调用 wx.navigateTo({ url: '/pages/web-wrapper/web-wrapper?url=' + encodeURIComponent(newUrl) }) ,跳转到一个中间页 web-wrapper 。该页同样使用 <web-view> 加载新 URL,但携带 query 参数,实现“伪路由”。这样既保持 H5 的 SPA 体验,又让小程序路由栈可追踪、可返回。
3. 域名配置与 HTTPS 强制:微信审核的生死线,不是“填对就行”,而是“填对+测通+留痕”
3.1 业务域名 vs 服务器域名:微信后台的两个必填项
微信公众平台 > 开发管理 > 开发管理 > 业务域名,这里填的是 H5 页面中所有 fetch 、 XMLHttpRequest 、 <img> 、 <script> 标签引用的域名 (即你 H5 里 api.xxx.com 、 static.xxx.com )。而 web-view 的 src 域名,必须单独填在 开发管理 > 开发管理 > 业务域名 下的“ web-view 业务域名 ”字段(微信文档中叫“公众号 JS 接口安全域名”,但小程序 web-view 共用此列表)。两者必须同时配置,缺一不可。常见错误:只配了 web-view 域名,忘了配 API 域名,导致 H5 页面内请求 404;或配了 www.xxx.com ,但 H5 实际请求 api.xxx.com ,被拦截。
3.2 HTTPS 强制校验:证书链必须完整,不能有中间 CA 缺失
微信要求所有业务域名必须使用有效 HTTPS 证书,且证书链完整。测试方法:用 Chrome 访问 https://your-h5-domain.com ,点击地址栏锁图标 → “连接是安全的” → “证书有效” → 查看“证书路径”,确保从站点证书到根 CA 的每一级都显示“有效”。若出现“此证书由未知权威颁发”,说明中间证书未部署。Nginx 配置示例:
ssl_certificate /path/to/fullchain.pem; # 必须是 fullchain,包含站点证书+中间证书
ssl_certificate_key /path/to/privkey.pem;
注意:
fullchain.pem≠cert.pem。很多 Let's Encrypt 用户只上传cert.pem,漏掉chain.pem,导致微信校验失败。用openssl s_client -connect your-domain.com:443 -servername your-domain.com可验证证书链是否完整。
3.3 域名白名单调试技巧:用 wx.openURL 临时绕过限制
开发阶段常遇到“域名未配置,但想快速验证逻辑”。微信提供 wx.openURL (需基础库 2.27.0+)作为临时方案:它打开一个新窗口,不走 web-view 安全校验,可用于调试 H5 页面本身。但注意: wx.openURL 无法与小程序通信,且上线前必须替换回 web-view 。代码示例:
// 仅用于开发环境
if (process.env.NODE_ENV === 'development') {
wx.openURL({ url: 'https://test-h5-domain.com' })
} else {
this.setData({ webUrl: 'https://prod-h5-domain.com' })
}
4. 避坑指南:H5 封装小程序的五个血泪现场,每个都曾让我重启三次开发者工具
4.1 现象: web-view 白屏,控制台无报错,Network 里看不到任何请求
原因 : web-view 的 src 属性值为空字符串 "" 或 undefined ,微信会静默失败,不抛异常。常见于 data.webUrl 初始化晚于 WXML 渲染,或 onLoad 中异步获取 URL 未加 setData 。
解决 :在 index.js 的 onLoad 中强制初始化 webUrl ,哪怕先设为 https://weixin110.qq.com (微信官方空白页),再异步替换:
onLoad() {
this.setData({ webUrl: 'https://weixin110.qq.com' }) // 防白屏
this.loadH5Url().then(url => {
this.setData({ webUrl: url })
})
}
4.2 现象:H5 页面能加载,但点击按钮无反应, console.log 不输出
原因 :H5 页面中 window.postMessage 发送消息时,目标 origin 写错。 web-view 的 postMessage 要求 targetOrigin 必须精确匹配 web-view 加载的域名(如 https://xxx.com ),不能是 * 或 https://www.xxx.com 。
解决 :H5 页面中发送消息时,显式指定 origin:
// H5 页面中
window.postMessage({ type: 'LOGIN_SUCCESS', data: token }, 'https://xxx.com') // 必须精确
4.3 现象:iOS 真机上 web-view 无法滚动,Android 正常
原因 :iOS 微信 8.0.30+ 对 web-view 的 overflow-y: scroll 支持异常,需在 H5 页面 CSS 中强制添加 -webkit-overflow-scrolling: touch 。
解决 :在 H5 的全局 CSS 中加入:
body, html, .app-container {
-webkit-overflow-scrolling: touch !important;
overflow-y: scroll !important;
}
4.4 现象:分享到朋友圈后,链接打开是空白页,或提示“该链接来自非认证公众号”
原因 :分享时 onShareAppMessage 返回的 path 参数未携带 ?from=miniprogram ,微信无法识别来源,降级为普通网页打开。
解决 : onShareAppMessage 必须返回带参数的 path,且该 path 对应的小程序页面必须存在:
onShareAppMessage() {
return {
title: '分享标题',
path: '/pages/index/index?url=' + encodeURIComponent('https://xxx.com/share'),
imageUrl: '/images/share.jpg'
}
}
4.5 现象:H5 页面中调用 wx.miniProgram.navigateTo 报错 wx is not defined
原因 :H5 页面未引入微信 JSSDK,或引入时机晚于执行。 wx.miniProgram 是微信注入的全局对象,仅在 web-view 环境中存在,且需等 wx.ready 后才能用。
解决 :H5 页面中必须按微信文档规范引入 SDK,并监听 ready :
<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>
<script>
wx.miniProgram.getEnv(res => {
if (res.miniprogram) {
wx.miniProgram.navigateTo({ url: '/pages/detail/detail?id=123' })
}
})
</script>
5. 审核提包前的终极 checklist:不是“功能跑通就行”,而是“微信审核员看到什么就信什么”
5.1 页面截图必须体现“小程序感”,而非“网页截图”
微信审核员第一眼看到的是你提交的 5 张截图。如果全是 H5 页面的 PC 风格截图(如宽屏布局、悬浮按钮、底部固定导航),会被判定为“非小程序形态”。正确做法:
- 截图必须是真机或开发者工具“预览”模式下的画面;
- 首屏必须显示微信原生导航栏(
custom-tab-bar或navigationStyle: custom配置的标题栏); - 至少一张截图展示
web-view加载中的 loading 状态(本项目utils/loading.js提供了骨架屏组件); - 分享卡片截图需包含
onShareAppMessage返回的imageUrl,且图片尺寸为 500×400px,无文字水印。
5.2 sitemap.json 配置:让微信爬虫“读懂”你的 H5 页面结构
sitemap.json 不是可选项,是审核硬性要求。本项目 sitemap.json 已预置:
{
"desc": "关于本小程序的页面描述",
"rules": [
{
"action": "allow",
"page": "/pages/index/index"
},
{
"action": "disallow",
"page": "*"
}
]
}
但关键在 page 字段:它必须是你 app.json 中 pages 数组里声明的路径(如 /pages/index/index ),不能写 H5 的 URL(如 /product/list )。微信爬虫只认小程序页面路径,不解析 web-view 内容。所以 sitemap.json 的作用是告诉微信:“我这个小程序只有首页一个页面,其他内容都在 web-view 里”,避免因“未声明页面”被拒。
5.3 隐私协议与用户授权:H5 页面里的弹窗,必须同步到小程序侧
如果你的 H5 页面有“获取手机号”、“获取位置”弹窗,微信审核会检查:
- 小程序
app.json中是否声明了permission字段(如"scope.userLocation": {"desc": "用于获取您的位置信息"}); -
onLoad中是否调用wx.authorize主动申请(即使 H5 自己弹窗,小程序侧也必须申请); - 隐私协议页面(
pages/privacy/privacy.wxml)是否在app.json的tabBar或pages中声明,且内容与 H5 一致。
本项目 pages/privacy/privacy.wxml 已内置标准模板,只需替换为你公司的条款文本。重点: H5 页面的隐私弹窗文案,必须与小程序侧完全一致,包括“我们收集哪些信息”、“如何使用”、“如何删除”三部分 。微信会人工比对。
5.4 真机调试日志:导出 log 文件,比截图更有说服力
审核被拒时,微信会提供“审核不通过原因”。但很多时候原因是“页面功能异常”,却没说哪异常。此时,用真机调试导出日志最有效:
- 微信开发者工具 → 调试器 → Console → 点击右上角“导出日志”;
- 在真机上完整走一遍流程(打开、跳转、分享、登录);
- 导出的
.log文件里搜索web-view、postMessage、navigateTo,确认无fail关键字; - 将日志文件与截图一起打包,邮件发给微信客服(support@weixin.qq.com),附言“H5 封装小程序审核问题,日志已附”。
从那以后我每次提审前,都强制走一遍真机全流程并导出日志——不是为了应付审核,而是确保 web-view 的每一次 postMessage 都被正确接收,每一个 navigateTo 都有 success 回调。这比任何文档都管用。希望帮到你。
本文聚焦微信小程序通过web-view组件封装H5页面的全流程实践,涵盖业务域名与服务器域名配置、HTTPS证书链完整性校验、web-view与H5双向通信、路由劫持实现SPA体验、iOS滚动异常修复、分享链接白屏问题解决,以及审核必备的截图规范、sitemap配置、隐私协议同步和真机调试日志导出等关键环节,直击H5转小程序过审核心痛点。
9303

被折叠的 条评论
为什么被折叠?



