基于vux与vue全家桶的微信商城公众号接入实践

简介：基于 vux 与 vue 全家桶的微信商城公众号接入项目，专为有 Vue 基础、想实战移动端商城开发的中级前端或全栈学习者准备，适合作为二次开发或毕业设计的参照模板。它帮助读者梳理公众号 H5 商城从项目构建、路由分配到数据交互的完整链路，尤其突出 vux 组件在移动端界面中的实际调用方式。资源包为 565KB 的 zip 压缩包，共 118 个文件，主要包含 65 张 PNG、17 个 Vue 文件、17 个 JS 文件、10 张 JPG 图片，以及 Babel、EditorConfig、Git、HTML、CSS 等配套文件，其中 PNG/JPG 用于页面与轮播视觉素材，Vue/JS 分别承载组件结构与业务逻辑，配置文件保障工程规范。目前已有 28 人学习或下载，可作为学习热度参考。这份小体积资源胜在结构清晰，既能看到 swiper 轮播、banner 等实际素材在项目中的引用方式，也能直接分析公众号接入的前后端协作细节，适合快速学习、复用与改造。

1. 基于vux与vue全家桶的微信商城公众号接入，先别急着升级Vue3

接手一个在微信公众号里打开的商城 H5，技术栈是 vux 加 vue 全家桶，第一反应往往是“Vue3 都出这么多年了，直接重写吧”。我一般会劝团队先冷静：vux 虽然很多年没有大版本更新，但它对微信 WebView 的样式兼容已经很成熟，商城这种表单密集、弹层频繁、支付链路长的场景，贸然换一套组件库意味着重测几十个页面。这篇文章不铺理论框架，直接按一条可落地的路径走：vux 选型、vue 全家桶目录搭建、公众号网页授权与 JS-SDK 接入、JSAPI 支付，最后是打包上线后常见的坑。适合刚接手这类老项目的人，也适合新项目里被迫沿用 Vue2 技术栈的团队。

2. vux选型与vue全家桶工程结构：从依赖版本到启动配置

2.1 为什么微信内商城还在用vux：Vue2生态下的组件选择

先交代背景：vux 是 Vue2 时代的组件库，官方文档停更很久，但它的 Group、Cell、XInput、Popup、Picker 等组件在微信内置浏览器里的表现，是当年专门打磨过的。新项目如果从零开始，我也不会主动选 vux；但只要是“维护中的微信商城”且技术栈锁在 Vue2，vux 依然比重新引入 vant 2.x 省心。两者的对比可以从下面这张表看出差异：

这个表格不是否定 vant。如果你的项目需要后端管理端和用户端共用一套组件，vant 更合理；但纯微信商城场景，vux 的 Cell 配合右侧箭头、XInput 的占位与清空按钮、Popup 的底部弹层，都是现成的移动端交互范式。vux 最大的坑反而是文档散落，很多配置要靠读源码确认。

2.2 vue全家桶目录设计与依赖版本锁定

Vue2 环境下，全家桶的版本必须锁死：vue 用 2.6.x，vue-router 必须 3.x，vuex 必须 3.x，axios 随意。vue-router 4 和 vuex 4 只能配 Vue3，版本装错直接白屏。我在新老项目中都会用同一套目录结构：views 放页面，components 放业务组件，store 按模块拆，api 按后端模块拆，utils 放微信相关封装。页面组件里不要直接发请求，统一走 api 目录，后面公众号签名、支付回调的逻辑才有地方收。

{ "dependencies": { "vue": "^2.6.14", "vux": "^2.9.6", "vue-router": "^3.6.5", "vuex": "^3.6.2", "axios": "^0.21.1" }, "devDependencies": { "vux-loader": "^1.2.9", "vue-template-compiler": "^2.6.14", "@vue/cli-service": "^5.0.8" } }

vue-template-compiler 的版本必须与 vue 保持同版本，否则构建时会报 template compiler 版本不匹配，这是 Vue2 项目里出现频率最高的构建错误之一。vue-router 和 vuex 如果被 npm 自动升级到大版本，会在运行时报找不到相关 API，所以 package.json 里要写死主版本号。

2.3 vue安装与环境配置：接口地址不写死

vue 安装及环境配置，最值得注意的不是 vue create 那一步，而是装完后先把两件事做对。第一件是处理 vux 的 webpack 适配，因为 vux 部分组件依赖 vux-loader 做按需编译：

// vue.config.js const vuxLoader = require('vux-loader') module.exports = { publicPath: './', transpileDependencies: ['vux'], configureWebpack: config => { vuxLoader.merge(config, { plugins: ['vux-ui'] }) } }

publicPath 设为 ./ 是为了让打包产物能部署在任意 nginx 子路径下；transpileDependencies 让 webpack 对 vux 的 ES6 源码做降级编译，避免低版本安卓 WebView 解析报错；configureWebpack 里的 vux-ui 插件负责把组件的 import 语句转换成按需加载，同时自动引入组件样式，这里不能漏。

第二件是环境变量分离。axios 的 baseURL 不要写死，从环境文件读取：

# .env.development VUE_APP_API_BASE=https://api.example.com/wxshop

# .env.production VUE_APP_API_BASE=https://m.example.com/wxshop

VUE_APP_ 开头的变量会打进前端包，所以只放 appid、接口地址这类公开信息。微信的 secret 永远只留在后端，不能出现在任何前端工程文件里，这个问题在公众号项目里必须从第一天就守住。

3. 微信公众号接入：网页授权、JS-SDK签名与JSAPI支付前置

3.1 入口怎么来：公众号链接怎么获取，以及进H5后先做什么

先解决入口问题。用户在公众号里进入商城 H5 的方式通常是菜单栏、自动回复、图文消息里的“阅读原文”，少数是通过分享卡片。公众号链接怎么获取，取决于入口类型：菜单和自动回复的链接要在公众号后台的“内容与互动”里配置；图文消息的链接可以直接从素材编辑页复制。但这些链接最终都指向同一个 web 地址，H5 自己不需要区分来源。

真正要区分的是“用户是否已经授权”。我习惯在路由的全局 beforeEach 里做统一判断：没有 openid 且 URL 里没有 code，就发起网页授权；有 code 就交给后端换 openid，换完再继续渲染。不要在商品页、购物车页各自处理授权，否则授权回跳会打断支付流程。如果项目用的是 hash 路由，授权前先把当前路由存到本地，回调后再 router.replace 回去，否则用户会被直接送回首页。

3.2 网页授权：先用snsapi_base拿到openid再补用户信息

公众号网页授权分两个 scope。snsapi_base 是静默的，用户无感知；snsapi_userinfo 需要用户点击确认，能拿到头像、昵称。商城里绝大多数页面用 snsapi_base 就够了，只有个人中心这类需要展示头像昵称的页面才升级到 snsapi_userinfo。前端发起授权的代码可以统一收在 utils/wechat.js：

const getUrlParam = name => { const reg = new RegExp('[?&]' + name + '=([^&]+)') const match = location.href.match(reg) return match ? decodeURIComponent(match[1]) : '' } export function ensureAuthorize(appid) { if (localStorage.getItem('openid')) return null const code = getUrlParam('code') if (code) return code const redirectUri = encodeURIComponent(location.origin + location.pathname) const url = 'https://open.weixin.qq.com/connect/oauth2/authorize' + `?appid=${appid}&redirect_uri=${redirectUri}&response_type=code` + '&scope=snsapi_base&state=wxshop#wechat_redirect' window.location.replace(url) return null }

redirect_uri 只取 origin 加 pathname，不带 query 也不带 hash。如果带了原有 query，授权回调后参数会叠在一起；如果带了 hash，微信会丢弃 hash，路由直接回到首页。授权成功后微信会跳到 redirect_uri 并附上 code 和 state，前端再从 location.href 里取 code 传给后端。

后端用 code 换 openid：

// Node.js 后端 app.get('/api/wx/auth', async (req, res) => { const { code } = req.query const url = 'https://api.weixin.qq.com/sns/oauth2/access_token' + `?appid=${WX_APPID}&secret=${WX_SECRET}&code=${code}` + '&grant_type=authorization_code' const data = await fetch(url).then(r => r.json()) if (!data.openid) return res.status(502).json(data) res.json({ openid: data.openid, accessToken: data.access_token, refreshToken: data.refresh_token }) })

code 有效期 5 分钟，必须一次性使用；data.access_token 是网页授权的用户 access_token，不是全局 access_token，两者别混。openid 建议直接作为商城用户主键落地，换 token 的过程不要让前端自己请求 api.weixin.qq.com，secret 会暴露。

3.3 JS-SDK签名：后端算好这5个参数，前端只做配置和回调

网页授权解决“知道是谁”，JS-SDK 解决“能做什么”。分享、支付、定位这些微信能力都要先过 wx.config。JS-SDK 签名的关键是 jsapi_ticket，它由全局 access_token 换出：

const crypto = require('crypto') const cache = { ticket: '', expiresAt: 0 } async function getJsapiTicket() { if (cache.ticket && Date.now() < cache.expiresAt - 60000) { return cache.ticket } const token = await getGlobalAccessToken() const data = await fetch( 'https://api.weixin.qq.com/cgi-bin/ticket/getticket' + `?access_token=${token}&type=jsapi` ).then(r => r.json()) cache.ticket = data.ticket cache.expiresAt = Date.now() + data.expires_in * 1000 return data.ticket } async function buildSignature(url) { const ticket = await getJsapiTicket() const nonceStr = Math.random().toString(36).slice(2, 15) const timestamp = Math.floor(Date.now() / 1000) const raw = `jsapi_ticket=${ticket}&noncestr=${nonceStr}` + `&timestamp=${timestamp}&url=${url}` return { nonceStr, timestamp, signature: crypto.createHash('sha1').update(raw, 'utf8').digest('hex') } }

签名字符串的顺序必须和官方文档一致：jsapi_ticket、noncestr、timestamp、url 都是小写，顺序不能换，拼接结果不能做 encodeURIComponent。ticket 有效期为 7200 秒，后端要缓存并提前 60 秒刷新，避免请求排队时拿到刚过期的 ticket。url 取前端页面的完整地址，去掉 # 及之后的部分。

前端拿到签名后：

wx.config({ debug: false, appId, timestamp, nonceStr, signature, jsApiList: [ 'updateAppMessageShareData', 'updateTimelineShareData', 'chooseWXPay', 'getLocation' ] }) wx.ready(() => { console.log('jssdk ready') }) wx.error(err => { console.error('jssdk error', err) })

debug 只在上线前开。真正上线后把 debug 关掉，在 wx.error 里记录 errMsg，签名过期、域名不符、接口不存在都会在这里有线索。常用 jsApiList 里，商城项目最需要这三个：

到这里公众号接入口已经通了。网页授权负责登录态，JS-SDK 负责分享与支付，接着看商城自己的核心链路。

4. 商城核心链路：vue-router路由参数、vuex购物车与微信支付接口

4.1 商品详情页的路由参数：params与query怎么选

商城 H5 里最典型的路由是商品详情页。商品 ID 这种“定位一个资源”的参数，用 params 放在路径里；来源标记这种“这次访问是谁带的”参数，用 query 放在 ? 后面。改造前常见写法是 this.$route.query.id，问题不在刷新，而在于分享出去的链接里参数位置混乱，后端归因时拿不到结构化字段。

// router/index.js const routes = [ { path: '/goods/:id', name: 'GoodsDetail', component: () => import('@/views/GoodsDetail.vue'), props: true } ]

props 设为 true 后，组件里直接用 props.id 接参，不再依赖 this.$route，组件更容易单测和复用。query 保留给 utm_source、share_uid 这类透传参数，下单时一并带给后端，这样分销归因和活动来源统计都能在服务端完成。

4.2 用vuex管理购物车与登录态，顺手解决刷新丢失

购物车数据放在 vuex 的 cart 模块里，刷新页面会清空，所以要同步写 localStorage。常见做法是在 mutation 里做同步持久化，简单直接，不引入 vuex-persistedstate 也能工作：

// store/modules/cart.js const CART_KEY = 'wxshop_cart' const state = { items: JSON.parse(localStorage.getItem(CART_KEY) || '[]') } const mutations = { addItem(state, goods) { const found = state.items.find(i => i.id === goods.id) if (found) { found.count += goods.count } else { state.items.push({ ...goods, count: goods.count }) } localStorage.setItem(CART_KEY, JSON.stringify(state.items)) }, removeItem(state, id) { state.items = state.items.filter(i => i.id !== id) localStorage.setItem(CART_KEY, JSON.stringify(state.items)) } } const getters = { totalAmount(state) { return state.items.reduce((sum, i) => sum + i.price * i.count, 0) } } export default { state, mutations, getters }

这个写法把 localStorage 的读写集中在 mutation 里，比在页面里分别 setItem 更可控。还有一个容易被忽略的点：localStorage 写入的是价格和数量，结算时必须以服务端的实时价格为准，前端 getter 里的 totalAmount 只做展示。

登录态也可以放 vuex。网页授权拿到 openid 后写入 state，同时存一份到 localStorage。公众号的 WebView 每次冷启动可能直接换进程，sessionStorage 存在被清空的可能，所以 openid 这类长期身份标识存 localStorage 更可靠。

4.3 微信支付接口JSAPI流程：统一下单到chooseWXPay

微信支付接口里，JSAPI 支付是公众号 H5 的唯一选择。流程是前端调自己的后端下单接口，后端调微信统一下单，拿到 prepay_id 后组装支付参数返回前端，前端再 wx.chooseWXPay 拉起收银台。前端不要直接调支付接口，签名参数都在后端。

后端统一下单的核心参数：

前端拿到后端返回的支付参数后调用：

const payParams = await api.createOrder({ orderId: order.orderId, openid: store.state.openid, totalAmount: cartTotalAmount }) wx.chooseWXPay({ timestamp: payParams.timestamp, nonceStr: payParams.nonceStr, package: payParams.package, signType: 'MD5', paySign: payParams.paySign, success(res) { // 注意：这里成功不代表钱已到账，仅表示收银台已发起支付 }, fail(err) { if (err.errMsg.includes('cancel')) { // 用户主动取消，不要提示系统错误 } } })

这里有两个常见的坑。第一，wx.chooseWXPay 里的参数名是小写 timestamp，而后端返回的统一下单参数里常见的是大写 timeStamp，取字段时要转一下。第二，success 回调只代表用户操作流程走完了，最终以 notify_url 收到的通知为准，前端不能在 success 里直接改订单为已支付，被刷单的风险就在这里。支付完成后订单详情页重新拉订单状态，展示逻辑比支付回调更可靠。商城核心链路的代码到这里是完整的：路由进详情、vuex 管购物车、微信支付接口收尾，下面是上线后绕不开的适配与排查。

5. 打包适配与线上定位：vConsole、vue devtools与三个必查项

5.1 vue打包后布局异常先查这三处

vue 打包后布局异常，在微信里表现为样式错乱或页面空白，最多见的是三个原因。第一，publicPath 用了默认的 /，部署在子目录时所有静态资源 404，重新检查 vue.config.js 里 publicPath 是否为 './'。第二，路由开启了 history 模式而 nginx 没有做 try_files 重写，用户刷新页面 404，公众号内商城里路由模式建议直接用 hash，省掉一层服务器配置。第三，在大屏手机或 iPad 上打开时字体和间距异常，检查 index.html 里 viewport meta 是否有 width=device-width 和 initial-scale=1.0。

5.2 微信内JSSDK签名失败，按这个顺序查

JSSDK 签名失败是最容易反复排查的问题，我一般按四个位置定位。首先确认 JS 接口安全域名和网页授权域名是否都在公众号后台配置且指向同一域名，域名最多配置 3 个，且不支持 IP 和端口。然后检查签名用的 url 是否与当前页面实际 URL 完全一致，取签名时用 location.href.split('#')[0]，如果页面地址末尾多了一个斜杠，签名必失败。第三，确认后端 jsapi_ticket 是全局 access_token 换出来的，不要误用网页授权的 access_token 去换。最后对照签名字符串的顺序和大小写，noncestr 是纯小写，不是 nonceStr，这个字段写错时 wx.error 返回的信息最容易误导人。

5.3 生产环境开vConsole，配合vue devtools远程定位

生产环境没法直接打开 devtools，vConsole 是把调试终端搬进微信里的最直接手段。需要按需加载，避免所有正常用户都看到调试面板：

// main.js if (location.href.includes('vconsole=1')) { import('vconsole').then(({ default: VConsole }) => new VConsole()) }

这段代码写在 main.js 里，只在 URL 带 vconsole=1 时动态加载，不影响正常用户。线上用户报问题时，让他把带参数的链接发过来，就能看到 console 和网络请求。配合 vue devtools 在本地复现组件状态，vConsole 看线上网络请求和报错，两者互补。微信内置浏览器的 DOM 检查没有专门入口，vConsole 定位逻辑问题，devtools 定位组件状态问题，两个都开是公众号商城调试的标准姿势。

本文还有配套的精品资源，点击获取