1. 项目全景uni-app 如何撑起公众号H5开发做微信生态开发的时间长了你迟早会遇到一个需求公司公众号菜单里要放一个H5活动页或者绑定一个业务系统。这个页面要能获取微信用户身份要能调微信的分享还要能发布上线。接手这种任务我优先想到的技术栈就是 uni-app。原因很直接团队已经有 Vue 基础而且这套代码以后还能编译成小程序不至于这一个页面就重写一遍。这篇文章我就从实际项目出发讲讲怎么用 uni-app 开发公众号H5以及在微信开发者工具里完成调试和上线的完整链路。这个项目能解决的问题很简单一个纯公众号内的 H5 页面从登录态、信息展示到分享传播全流程跑通。适合正在做微信公众号页面的前端开发、全栈工程师以及打算把 uni-app 项目从“小程序”扩展到“H5”的团队参考。我会把授权流程、JS-SDK 接入、开发者工具调试和常见报错都拆开讲尽量说人话让初级开发者也能直接照着做。1.1 为什么选 uni-app 而不是直接上 Vue/React如果只是做一个公众号H5理论上直接用 Vue 或 React 就够了但现实项目的麻烦在于“多端复用”。产品经理今天要公众号H5明天很可能就提“App 里也放一个”后天可能又说“小程序来一个”。用 uni-app 之后同一套业务代码可以分别编译成 H5、小程序和 App虽然不可能做到一次编写零改动但业务逻辑、接口层、组件层大部分能复用省下来的时间非常可观。另一个关键点是 uni-app 对 Vue 开发者特别友好。它使用 Vue 语法开发原有的模板语法、计算属性、组件通信都能直接用。项目内还有大量现成的 uni-ui 插件和社区组件遇到表单、轮播、地图这类需求直接拉插件就能跑。对于公众号H5这种页面数量不多、交互相对简单的项目上手成本非常低。相比原生 H5 项目uni-app 还天然规避了“打包”问题。用 Vite 或 Webpack 统一构建自动处理 ES6 转译、资源压缩、CDN 路径这些事。开发时热更新也很流畅改了代码页面立刻刷新具体配置我会在后面的项目基础配置里展开。当然直接用纯 Vue 随手开一个 Vite 项目也能实现但如果团队已经有 uni-app 技术栈或者后续有多端需求那选 uni-app 就不是“大炮打蚊子”而是合理的长期规划。1.2 公众号H5和普通H5的差异点公众号H5本质上是个网页但它运行在微信内置浏览器里和普通浏览器打开网页的“用户习惯”与“能力边界”差了很远。最大的差异是公众号H5走微信授权后能拿到用户的 openid 和用户信息这一点决定了它和“普通H5”完全是两个世界的产品。普通H5靠 Cookie、Session 或 Token 维护登录态公众号H5虽然也靠这些但获取用户身份的入口是微信 OAuth。访问页面时应用需要把用户引导到微信的授权页用户同意后微信会回调你的页面并携带一个 code之后你拿 code 到后端换 openid。如果还需要昵称头像等资料则要申请用户信息授权体验上会多一步“同意”的弹窗。此外公众号H5还能调用微信的 JS-SDK实现分享朋友圈、隐藏右上角菜单、扫一扫、选择图片等能力。普通H5没有这些接口只能用浏览器原生 API微信分享出去的效果也只是一个普通链接卡片没有自定义标题和缩略图。在开发时还要特别关注微信浏览器的一些“怪癖”缓存策略激进、部分安卓系统对某些 CSS 支持不稳定、首次加载和回退场景下的 URL 不一致等。这些问题在桌面浏览器里基本不会出现但公众号用户一多各种奇怪的反馈就来了所以代码里提前做兜底非常重要。1.3 项目目录与基础配置从零创建一个 uni-app H5 项目我习惯用 HBuilderX 或者命令行初始化模板。这里我给出一个基于vue3 vite的 CLI 初始化命令方便不习惯 HBuilderX 的开发者npx degit dcloudio/uni-preset-vue#vite my-wechat-h5 cd my-wechat-h5 npm install npm run dev:h5项目结构里需要注意几个核心文件src/pages.json页面路由与窗口样式配置。src/manifest.jsonH5 相关的应用名、路由模式、跨域配置。src/vite.config.js开发服务器端口、代理等。src/App.vue应用生命周期适合放全局逻辑。对公众号H5来说路由模式我建议直接用hash模式。原因后面会详细说主要是因为微信授权回调、分享签名、Nginx 部署都能少踩很多坑。在manifest.json的h5节点里可以这样配h5: { router: { mode: hash, base: / }, devServer: { port: 8080, proxy: { /api: { target: https://your-backend.com, changeOrigin: true } } } }devServer.proxy很重要开发阶段后端接口多半不满足跨域条件本地代理能直接把/api开头的请求转发到后端省掉后端 CORS 配置的麻烦。页面路径使用 hash 路由后服务器只需要托管index.html这一个入口文件不需要额外的 rewrite部署成本低很多。2. 核心开发细节微信授权与 JS-SDK 打通公众号H5的第一步是搞定登录态。登录态不解决后面的业务数据、用户识别全是白扯。要用 uni-app 接微信网页授权先要把整个流程理清楚否则很容易出现“跳转后 code 丢失”“授权回调后页面空白”这种问题。2.1 微信 OAuth 授权的完整流程以最常见的snsapi_base静默授权为例核心流程如下用户访问 H5 页面。前端检测到本地没有登录态比如没有openid或token。前端跳转到微信授权链接https://open.weixin.qq.com/connect/oauth2/authorize?appidAPPIDredirect_uriREDIRECT_URIresponse_typecodescopesnsapi_basestateSTATE#wechat_redirect用户确认后微信重定向回到redirect_uri并在 URL 上携带code参数。后端拿到code后调用微信接口https://api.weixin.qq.com/sns/oauth2/access_token?appidAPPIDsecretSECRETcodeCODEgrant_typeauthorization_code换取openid和access_token。后端把openid或自己的token返回给前端前端写入本地存储。在 uni-app 里前端不需要直接拼授权链接更常见的做法是让后端返回一个授权跳转 URL。比如请求后端接口/api/wechat/auth-url?redirect_uri当前页面的编码值后端返回完整的微信授权链接然后前端用window.location.href跳过去。这样做的好处是 appid、secret 都留在后端不会暴露到前端代码里。相对麻烦的是snsapi_userinfo这种需用户点同意授权的流程。它在第二步会弹出微信的“授权并登录”页面用户体验多一步但能拿到用户头像、昵称等资料。如果业务只需要 openid优先用snsapi_base因为体验更顺滑。2.2 使用 hash 路由时如何正确接收 code 参数如果项目用了 hash 模式授权回调地址的形式往往是这样的https://yourdomain.com/#/pages/index?codexxxstateyyy注意code不在search部分而是在hash里面。如果你直接用window.location.search去取什么都拿不到。正确做法是解析window.location.hashfunction getQueryFromHash() { const hash window.location.hash.split(?)[1] || ; const params new URLSearchParams(hash); return { code: params.get(code), state: params.get(state) }; }拿到code后调用后端接口换取用户信息然后存到uni.setStorageSync或localStorage。需要在App.vue里做一个全局的登录检查在页面启动时判断是否有有效 token如果没有再去跳转授权链接。注意要避免死循环授权跳转redirect_uri会和当前页面地址保持一致如果每次都检测不到 token就会无限跳转微信授权页。通常的做法是携带一个state标志位或者后端在换 token 时做好记录。还有一个小细节授权回调后URL 里的code应该立刻清理掉。如果不清理用户手动刷新页面时可能会重复使用同一个 code微信端会报错或者拿到无效数据也可能被第三方截取造成安全问题。我一般在拿到 code 并完成登录后用history.replaceState或location.hash的重写把code参数去掉。2.3 在 uni-app 里接入微信 JS-SDK很多公众号H5要做自定义分享这时必须接入微信 JS-SDK。步骤看起来多但每一步都是必要的在index.html中引入微信 JS 文件或使用npm i weixin-js-sdk在代码中导入。前端请求后端签名接口比如/api/wechat/jssdk-signature?url当前页面URL。后端用jsapi_ticket计算签名返回appId、timestamp、nonceStr、signature。前端调用wx.config注入配置然后在wx.ready中调用分享等接口。分享到朋友圈或发送给朋友比较常用的两个接口是updateAppMessageShareData和updateTimelineShareData。import wx from weixin-js-sdk; async function initWxShare(shareData) { const currentUrl window.location.href.split(#)[0]; const res await request(/api/wechat/jssdk-signature, { url: currentUrl }); wx.config({ debug: false, appId: res.appId, timestamp: res.timestamp, nonceStr: res.nonceStr, signature: res.signature, jsApiList: [updateAppMessageShareData, updateTimelineShareData] }); wx.ready(() { wx.updateAppMessageShareData({ title: shareData.title, desc: shareData.desc, link: shareData.link, imgUrl: shareData.imgUrl, success() {} }); }); }签名时后端拿到的 URL 必须和前端实际 URL 保持一致尤其是协议部分。开发环境是http://localhost:8080手机上预览可能是https://yourdomain.com这两个环境要分别请求签名接口。最容易翻车的点是当前页面 URL 带#hash而 JS-SDK 要求签名用的 URL 去掉#后的部分所以我在上面用split(#)[0]取到干净地址。2.4 开发阶段的限制与绕过方案开发者工具和本地浏览器都不是真实微信环境JS-SDK 在普通浏览器里调用会报“invalid signature”或“errMsg: xxx is not a function”。我一般会在代码里判断当前环境const isWechat /MicroMessenger/i.test(navigator.userAgent); if (isWechat) { initWxShare(shareData); } else { console.log(非微信环境跳过JS-SDK初始化); }如果只是调试页面的业务逻辑用 Chrome 的移动端模拟器足够。但是要验证微信授权、分享、调用 JSSDK 这些就必须退回真机。真机预览时需要把项目跑在一个公网可访问的 HTTPS 地址上。域名必须是 ICP 备案过的域名并且和公众号后台配置的“网页授权域名”“JS接口安全域名”保持一致。开发期最常见的替代方案是用一些公网映射工具把本地端口映射成临时域名。但我建议正式联调还是直接部署到测试环境服务器比起映射工具更稳定也避免临时域名随时失效的问题。3. 微信开发者工具里的公众号调试从创建到跑通很多同学以为微信开发者工具只能调试小程序其实它还有一个“公众号网页项目”模式专门用来调试公众号H5。这个功能对前端开发最大的价值在于它能模拟微信浏览器的 UA、唤起 JS-SDK 的能力、模拟授权流程让你不用一遍遍扫真机二维码就能排查大部分兼容性问题。3.1 在微信开发者工具里创建公众号网页项目先确保已安装最新版微信开发者工具然后按下面的步骤操作打开工具点击“导入项目”或“新建项目”。在项目类型里选择“公众号网页项目”。项目名称随便填比如wechat-h5-debug。在“URL”输入框填入本地开发地址。如果是 HBuilderX 启动的 uni-app默认是http://localhost:8080如果用了自定义端口就填对应的端口。创建完成后开发者工具里会出现一个手机屏幕样式的窗口加载你填入的 URL底部还有和微信聊天界面很像的入口。这个模式下工具会带上微信浏览器的 UA右上角菜单也能唤起微信 JS-SDK 的部分能力非常适合快速验证页面。如果 HBuilderX 和开发者工具“配合不好”出现“无法通过 HBuilderX 打开”的情况不必纠结。手工创建一个公众号网页项目把 URL 填进去就行。HBuilderX 里的集成按钮只是帮你省去手动创建那几秒手工操作完全等价。3.2 处理创建后的页面白屏与“network unavailable”我在调试 uni-app H5 时最常见的报错是页面白屏控制台提示“uni-app network: unavailable”。这个报错听起来像是网络不通实际上大多数时候是因为微信开发者工具默认校验了 web 域名而localhost不在合法域名列表里。解决办法点击工具的“详情”按钮进入“本地设置”。勾选“不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书”。刷新页面。如果是其他接口跨域报错优先检查本地 devServer 是否配置了代理或者后端是否允许对应域名跨域。用微信开发者工具调试本地接口时代理配置要正确否则 Network 面板里能看到请求但返回状态是CORS error或ERR_FAILED。还有可能是端口冲突。HBuilderX 默认会用8080端口如果 8080 被别的服务占了它可能自动切到8081或者直接跑不起来。在启动的 Console 窗口里确认最终的访问地址再用这个地址在开发者工具里创建项目。3.3 真机调试与扫码预览的区别微信开发者工具自带的模拟器可以调试大部分逻辑但真机上微信浏览器的内核版本杂、缓存策略不同最终还是要用真机预览。工具有两种真机方式真机调试手机和电脑在同一局域网通过工具生成的二维码手机扫码后可以加载本地开发页面。这时手机能调用真实微信环境适合调试 JS-SDK 和授权。预览需要填一个公网 HTTPS 地址。工具会生成一个 URL 或二维码手机能通过微信访问到这个页面。真机调试较方便但对“同一局域网”要求严格如果手机连的是 4G/5G就无法加载电脑上的本地服务。最好的联调方式仍然是部署一套测试环境。而且无论哪种方式都要保证手机上的微信版本不至于太老否则部分接口不支持。在开发者工具的“模拟操作”面板里还可以模拟微信授权。即使没有真实后端也能用随意的code走通页面逻辑。但上线前还是建议在真机环境做一次完整流程验证因为模拟授权省去的步骤可能会藏问题。3.4 用好 Network 和 Storage 面板定位问题微信开发者工具的调试面板和 Chrome DevTools 布局很像。我每次调试公众号H5优先看两个面板一个是Network。打开“Preserve log”后在微信授权回跳页能清楚看到请求的顺序页面加载 - 获取签名 - 换取 openid - 拉取业务数据。如果授权跳转后出现两次页面加载很可能是state参数或者重定向配置写错了。还有一点微信开发者工具默认会为部分静态资源启用内存缓存调试样式改动后好半天不生效可以直接勾选 “Disable cache” 再刷新。另一个是Storage。因为公众号H5本质是网页它可以正常使用localStorage、sessionStorage也能读写 Cookie。要模拟“老用户”或“新用户”场景直接在 Storage 面板删除token、openid等关键字段再刷新页面就能重新走一遍授权流程。这比清空缓存、退出重进快得多排查登录态相关 bug 时特别高效。4. 上线之前必须处理的细节与坑页面在开发者工具里跑通了只是完成了长征第一步。真正部署上线还要处理构建、路由、签名、缓存、兼容性等一系列问题。这一章的每个点都是我在项目里真实踩过的写出来让你提前绕开。4.1 H5 构建与静态资源部署uni-app 的 H5 构建产物在dist/build/h5部署前先执行npm run build:h5将dist/build/h5目录整个上传到服务器的 Web 根目录。这里有几个经验值如果部署到域名根路径manifest.json里h5.publicPath可以直接用/。如果要部署到二级目录比如https://yourdomain.com/wx-h5/最好把publicPath配成./或/wx-h5/避免静态资源 404。hash 路由模式部署后无需额外配置任意路径刷新都能加载根入口。如果后端接口和页面不在同一个域名Nginx 侧要配置反向代理或后端开启 CORS。在公众号安全设置里也需要将最终域名加入“JS接口安全域名”“网页授权域名”一个域名对应一个公众号不要搞混。4.2 高频报错排查速查表我把实际开发中遇到频率最高的几个问题整理成表方便你对照处理。现象可能原因解决办法页面提示uni-app network: unavailable开发者工具校验了域名或接口跨域勾选“不校验合法域名”检查代理和 CORS微信授权后一直跳回授权页redirect_uri与当前地址不一致或 code 被重复使用确认回调地址和初始地址一致拿到 code 后立即清除自定义分享设置了没反应JS-SDK 未初始化成功或签名 URL 与实际 URL 不一致从后端换成真实的location.href.split(#)[0]签名H5 页面在微信里刷新 404使用的是 history 路由服务器没有配置 rewrite改用 hash 路由或配置 Nginxtry_files指向index.html发布新版本后用户看到旧页面微信浏览器缓存太强静态资源加版本号Nginx 对 html 设置no-cache对其他静态资源设置较短的max-age安卓部分手机样式错乱微信浏览器内核版本较老CSS 兼容性问题使用低版本 ES 目标尽量避免某些新的 CSS 特性做好兼容降级每次排查问题都要先明确是不是环境和配置的问题再去看代码逻辑。很多时候是域名配置、签名地址之类的外部条件不对并不是代码本身有 bug。4.3 微信浏览器缓存与性能优化微信内置浏览器的缓存机制比 Chrome 还要激进我吃过很多亏。明明代码已经重新构建并上传到服务器但用户手机打开看到的还是旧页面。解决办法分两步第一静态资源文件名带 hash。uni-app 构建后 JS/CSS 文件名本来就带 hash 戳新版本文件名会变天然能解决一部分缓存问题。第二针对index.html设置不缓存。Nginx 配置可以这样写location /index.html { add_header Cache-Control no-cache, no-store, must-revalidate; } location /static/ { add_header Cache-Control public, max-age31536000, immutable; }这样保证入口文件每次拉取最新而强缓存的静态资源则能提升首次加载速度。开发环境中微信开发者工具里也可以直接开启“Disable cache”减少调试时的干扰。性能上uni-app 编译成 H5 后本质是 SPA 单页应用。首屏资源如果过大初始加载会非常慢。我一般会在vite.config.js里做代码分割把路由页面改成异步组件同时把体积较大的图表库、富文本库放到特定业务组件里再异步加载避免进入首页就把所有 JS 全拉下来。如果项目中有很多图片考虑使用 CDN 和图床图片路径尽量在编译后转化为绝对地址避免微信里出现图片裂开的情况。4.4 安全区适配与边界情况现在手机屏幕种类很多公众号H5如果不做安全区适配在 iPhone 刘海屏和底部横条手机上会有内容被遮挡的问题。最简单的方法是在manifest.json的 H5 节点里设置 viewport 参数同时在全局样式中加入page { padding-bottom: constant(safe-area-inset-bottom); padding-bottom: env(safe-area-inset-bottom); }如果是弹窗、底部操作栏还要考虑键盘弹起时是否遮挡输入框。微信开发者工具的“模拟器”可以选择多款设备包括带小刘海的机型开发时多切换几种机型预览能提前暴露不少布局问题。边界情况还包括用户从聊天会话里点开链接进入页面和从公众号菜单进入页面浏览器上下文不同在支付场景下用户可能调起微信支付后再返回部分低端安卓机对 Canvas 支持不完善海报生成要做降级处理。这些情况虽然不常遇到但一旦遇到就是线上事故建议在开发规划阶段就留出兜底方案。5. 个人实操心得与最后一点建议项目做得多了我最大的感受是公众号H5开发并不难难点全在于“微信生态的细节”。授权回调、JS-SDK 签名、开发者工具配置、缓存策略、多设备兼容每一条都值得写进团队的检查清单。个人强烈建议项目从一开始就走微信开发者工具 hash 路由 后端签名接口的稳定链路。hash 路由虽然不利于 SEO但公众号页面通常不需要搜索引擎收录换来的却是部署简单和授权回调省心。不要一开始为了 URL 好看去配 history 路由除非你非常熟悉 Nginx rewrite 的种种边界情况。最后分享一个小技巧开发过程中把微信开发者工具的“模拟器”和 Chrome 的“设备模拟模式”配合使用。微信开发者工具负责验证微信 APIChrome 负责调试样式和性能两者并行效率极高。如果遇到“开发者工具里正常真机里异常”这类问题不要急着改代码先用真机扫描日志看看是网络请求差异还是渲染层差异再精准定位。反复切换环境会浪费大量时间一次只修一个问题。只要这一套流程搭顺了后续接其他公众号、小程序甚至 App 端都能复用大部分经验。