简介基于 uni-app 开发的微信商城小程序通用模板适合小程序入门者、前端学习者及需要快速搭建商城原型的学生或开发者。压缩包共 490 个文件体积仅 2.04MB以 275 个 JS 逻辑文件、117 个 Vue 页面组件为核心辅以 JSON 配置、SCSS 样式、PNG 图标及 WXML/WXSS 等小程序文件覆盖商品展示、购物车、订单等常见商城模块并带有 u-charts 图表库与 goeasy 实时通信脚本便于扩展数据可视化与消息推送能力。当前已有 382 人学习下载。模板内全部源码经过测试可直接运行目录结构清晰还包含说明文档、字体图标与许可信息既可作为课程设计、毕业设计或工程实训的项目基底也适合有基础的开发者在此基础上修改页面、接入接口快速实现个性化商城功能。1. 引言一份直接能上手的 uniapp 微信商城模板如果你接手过小程序项目大概都有过这种经历从零搭一个商城光是轮播图、分类、购物车、订单、支付这套基础结构写两周都觉得不够稳。这份基于 uniapp 开发的微信商城小程序通用模板把商城最常用的一套完整流程全部封装好了——商品列表、分类筛选、购物车、结算下单、微信支付、个人中心代码按模块分得清清楚楚原生支持 HBuilderX 一键编译到微信小程序连分包、隐私协议、登录态都处理好了。如果你是中小团队、外包开发或者想找个架子做二次开发的开发者拿到手改配置、换接口就能跑省掉的不只是重复造轮子还有你自己踩坑的时间。这套模板不是那种只摆了个界面的空壳里面订单状态机、支付回调、token 刷新这些配送环节都有实现能当正式项目的地基。2. 技术选型与整体架构从 HBuilderX 到微信开发者工具的完整链路2.1 技术栈与选型理由模板的技术栈很集中uni-app 框架 Vue 2 语法 Vuex 状态管理 uni.request 封装网络请求。整套东西都是围绕一套代码、多端编译这个核心目标来组织的。为什么用 Vue 2 而不是 Vue 3因为 uniapp 对 Vue 2 的生态支持最成熟第三方插件、原生插件、社区示例基本都是 Vue 2 版本对于做商城这类需要大量购物车、订单交互的业务系统稳定性优先级比新语法特性高。网络层没有引 axios 之类的库而是直接在common/request.js里用uni.request做了一层 Promise 封装。这个决策很务实小程序里uni.request本身就是跨端的再套 axios 反而要处理适配层多一份依赖多一份风险。请求封装里做了 token 自动附加、401 统一跳转登录、错误提示统一处理这些是商城这类业务最需要的通用能力。2.2 目录结构拆解├── pages/ # 页面目录 │ ├── index/ # 首页轮播图、分类入口、商品瀑布流 │ ├── category/ # 分类页左侧分类列表 右侧商品列表 │ ├── cart/ # 购物车数量增减、选中状态、结算入口 │ ├── order/ # 订单列表待付款/待发货/待收货/已完成 │ ├── goods/ # 商品详情SKU 选择、加入购物车、立即购买 │ ├── pay/ # 支付结果页 │ └── user/ # 个人中心登录状态、订单入口、地址管理 ├── components/ # 公共组件 │ ├── goods-card/ # 商品卡片组件 │ ├── sku-popup/ # SKU 选择弹窗 │ └── number-box/ # 数字输入框 ├── common/ │ ├── request.js # 请求封装 │ └── config.js # 全局配置接口域名、secret 等 ├── store/ │ ├── index.js # Vuex 入口 │ ├── cart.js # 购物车 module │ └── user.js # 用户与登录状态 module ├── static/ # 静态资源 ├── App.vue # 应用入口文件 ├── main.js # Vue 实例挂载 └── manifest.json # uniapp 配置appid、小程序配置这个结构是典型的页面 组件 状态 工具四层划分。pages.json里已经配好了底部 tabBar、页面路由和分包结构manifest.json里要改的主要是微信小程序的 appid。对二次开发最友好的部分是store/目录购物车和用户状态单独拆了 module改业务逻辑不需要在整个项目里翻找。2.3 请求封装与拦截器设计common/request.js是整个模板网络层的核心几乎所有页面都走这一个入口。它的设计思路是外部调用只管传 url、method、data封装内部处理 token、loading、错误码。// common/request.js const config require(./config.js) function request(options) { return new Promise((resolve, reject) { uni.request({ url: config.baseUrl options.url, method: options.method || GET, data: options.data || {}, header: { Content-Type: application/json, token: uni.getStorageSync(token) || }, success: (res) { // 业务状态码约定0 表示成功非 0 按业务错误处理 if (res.data.code 0) { resolve(res.data.data) } else if (res.data.code 401) { // token 失效清理本地登录态并跳转登录页 uni.removeStorageSync(token) uni.navigateTo({ url: /pages/login/login }) reject(res.data) } else { uni.showToast({ title: res.data.msg, icon: none }) reject(res.data) } }, fail: (err) { uni.showToast({ title: 网络异常请稍后重试, icon: none }) reject(err) } }) }) }这段封装里几个细节值得说明。header里的 token 每次请求都自动附加业务代码里不用每个接口单独传省了很多重复劳动。code 401时统一处理登录失效避免每个页面各自判断、各自跳转造成逻辑分散。success里先解包res.data.data让页面拿到的直接是业务数据而不是一层层嵌套的响应体这是很常见的接口约定。实际对接后端时你得和后端确认两件事业务状态码字段名是code还是status成功值是0还是200。模板默认是code 0如果后端用的status 200那只需改一个判断条件比在几十个页面里找请求代码要省事得多。3. 核心模块拆解商品、购物车、订单与支付的完整链路3.1 商品列表与分类筛选首页和分类页共同依赖商品列表接口。分类页用了左侧一级分类 右侧二级分类商品的经典布局左侧滚动时右侧联动切换。这个页面的核心逻辑不是界面渲染而是如何在切换分类时既不丢失滚动位置、又能按需加载数据。// pages/category/category.vue 核心逻辑 data() { return { categories: [], // 一级分类列表 currentCategory: 0, // 当前选中的一级分类下标 goodsList: [], // 右侧商品列表 page: 1, loading: false, finished: false } }, methods: { switchCategory(index) { this.currentCategory index this.page 1 this.goodsList [] this.finished false this.loadGoods() }, async loadGoods() { if (this.loading || this.finished) return this.loading true const data await getGoodsByCategory({ categoryId: this.categories[this.currentCategory].id, page: this.page }) this.goodsList this.page 1 ? data.list : this.goodsList.concat(data.list) this.finished data.list.length 10 this.page this.loading false } }switchCategory里先把数据源重置再拉新数据避免旧分类的数据残留导致界面闪现错乱。loadGoods里的concat而不是push是为了生成全新数组触发 Vue 的响应式更新这一点在 Vue 2 里尤其重要——直接push虽然也能渲染但配合上拉加载更多时容易出现渲染不及时。finished标志位用来阻止重复请求滚动到底部时如果已经没有更多数据就不会再发请求。商品卡片组件goods-card.vue被首页、分类页、搜索结果页复用封装了图片懒加载、价格格式化、库存状态、点击跳转详情这几件事。这个组件不持有数据所有属性都由父组件传入是一个纯展示组件二次开发时想加角标、加折扣标签直接改这一处就行。3.2 购物车状态管理购物车是商城项目里最容易写乱的部分所以模板用 Vuex 单独管理。store/cart.js维护购物车列表、选中状态、总价、总数量所有页面都从 store 读取而不是每个页面自己维护一份数据。// store/cart.js const state { cartList: [], // [{ id, goodsId, skuId, name, price, count, checked }] checkedItems: [] // 当前选中的购物车项 } const getters { totalCount: (state) { return state.cartList.reduce((sum, item) { return sum (item.checked ? item.count : 0) }, 0) }, totalPrice: (state) { return state.cartList.reduce((sum, item) { return sum (item.checked ? item.price * item.count : 0) }, 0) } }totalCount和totalPrice都只统计checked的条目这样购物车底部的结算栏数据是实时计算的不用在增减数量、切换选中时手动去改 UI 上的数字。这是个很容易忽略的设计——很多人写购物车是在 setData 里手工更新总价逻辑一多就会出现数量改了价格没变的 bug。购物车条目的数据结构里有个skuId字段这是为了区分同一商品的不同规格颜色、尺码。模板的 SKU 弹窗sku-popup.vue会把选中的规格组合转换成后端接口需要的一个skuId加入购物车时带上结算时也靠它来确定具体买的是哪个规格。如果后端没有 SKU 体系可以直接忽略这个字段。3.3 微信支付与订单流程支付链路是商城里最复杂的场景模板的处理方式是前端只负责唤起支付结果以回调为准。下单接口返回支付参数后前端通过uni.requestPayment调起微信支付面板然后在success回调里跳转支付结果页同时启动一个定时器去轮询订单状态。// pages/pay/pay.js 关键逻辑 async function submitOrder(orderData) { const res await createOrder(orderData) // 返回 payParams uni.requestPayment({ provider: wxpay, timeStamp: res.timeStamp, nonceStr: res.nonceStr, package: res.package, signType: RSA2, paySign: res.paySign, success: () { // 支付成功的乐观处理跳转结果页后台异步确认 uni.redirectTo({ url: /pages/pay/success }) pollOrderStatus(res.orderId) }, fail: (err) { // 用户取消或支付失败统一走这里 uni.redirectTo({ url: /pages/pay/fail }) } }) } function pollOrderStatus(orderId) { // 每 2 秒查一次订单状态最多查 10 次 let count 0 const timer setInterval(async () { const order await getOrderDetail(orderId) if (order.status paid) { clearInterval(timer) // 更新本地订单列表状态 } if (count 10) clearInterval(timer) }, 2000) }这里有个重要的经验uni.requestPayment的success回调并不代表支付已经 100% 到账可能只是微信返回了一个用户已支付的中间态。模板里用pollOrderStatus轮询去确认订单的真实状态这是防止前端显示成功、后台没收到回调这类问题的手段。传入requestPayment的这些参数全部来自后端下单接口前端不能自己拼。timeStamp是后端生成的支付时间戳paySign是后端用商户私钥做的签名前端只是透传。如果签名报错或支付参数不合法先看后端拿到的prepay_id是否有效十有八九是商户号配置或签名算法有问题。订单列表页面抽了OrderStatus常量把待付款、待发货、待收货、已完成映射成数字状态码并提供了对应的操作按钮待付款显示去支付、待收货显示确认收货。这个状态机放在common/order.js里后端返回数字状态前端映射成文案和行为改的时候只看一个文件。3.4 登录鉴权与用户信息模板的登录体系是微信授权 后端换 token的经典模式。用户点击登录时调用wx.login拿code把code发给后端后端再向微信接口换取openid并签发自定义 token。// store/user.js 登录逻辑 async function login() { const { code } await uni.login({ provider: weixin }) const res await request({ url: /auth/login, method: POST, data: { code } }) uni.setStorageSync(token, res.token) uni.setStorageSync(userInfo, res.userInfo) return res.userInfo }模板里把 token 存在本地缓存后续所有请求通过common/request.js自动带上。这里涉及一个取舍wx.login拿到的code有效期只有 5 分钟所以登录动作必须在用户点击登录或进入需要登录的页面时实时执行而不是拿一个旧 code 去换 token。很多开发者在用户进入小程序时就提前登录一次等真正需要请求接口时 code 已经过期这就是偶尔能登录、偶尔要重试的原因。如果只做微信一键登录模板是用默认逻辑但如果你是二次开发接自己的后端需要和后端约定code换 token 的接口路径是否一致、token 的失效策略是什么。模板默认 token 永久有效后端不做过期校验正式上线前建议加上过期时间和服务端校验。4. 环境配置与运行指南从零到跑通4.1 环境准备与工具版本跑这个模板不需要很重的环境主要就三个工具HBuilderX、微信开发者工具、一个可用的后端接口地址。HBuilderX 用来打开项目并编译到微信小程序微信开发者工具用来预览调试和查看控制台。版本方面建议HBuilderX 用最新稳定版3.x 以上微信开发者工具用最新版这两个工具对新版微信基础库兼容性更好。模板本身没有高版本的独有 API 依赖所以不用刻意追新。4.2 关键配置项修改拿到的模板不能直接编先把三个地方改成你自己的manifest.json的微信小程序 appid、common/config.js的后端接口域名、pages.json的页面路径是否要调整。// manifest.json 中需要修改的配置 { mp-weixin: { appid: 你的微信小程序appid, setting: { urlCheck: false }, usingComponents: true } }urlCheck在开发阶段建议关掉否则微信开发者工具会拦截非白名单域名的请求导致真机预览时所有接口都报域名不合法。这个只在开发环境关上线前要去微信公众平台配置 request 合法域名否则正式版小程序同样会请求失败。common/config.js里改接口地址// common/config.js module.exports { // 开发环境接口地址 baseUrl: https://dev-api.example.com, // 正式环境接口地址 prodUrl: https://api.example.com, // 当前环境标识dev 或 prod env: dev, // 图片资源域名前缀 imgBaseUrl: https://cdn.example.com/images }imgBaseUrl很关键。商城项目里商品图、轮播图基本都是后台返回的完整 URL但偶尔会有后端只返回相对路径的情况。模板里所有图片渲染都拼了这个前缀实际对接时看后端返回的是完整地址还是相对路径如果是完整的就直接用别拼重了。4.3 编译运行与真机调试HBuilderX 打开项目后点击菜单栏运行-运行到小程序模拟器-微信开发者工具会自动唤起开发者工具并加载编译产物。首次运行会要求关联 appid使用测试号也可以。# 编译产物在项目根目录的 unpackage/dist/dev/mp-weixin 下 # 微信开发者工具导入时要选这个目录不是项目根目录很多新手在微信开发者工具里打开整个项目根目录而不是编译产物目录结果看到的是 .vue 文件而不是编译后的代码还问为什么全是 vue 文件。记住一点uniapp 项目本身不是微信原生小程序微信开发者工具里能跑、能断点调试的是编译后的mp-weixin目录。真机预览直接在微信开发者工具里点预览会生成一个二维码用微信扫了就能在真机上跑。真机调试时注意urlCheck关了但手机仍然请求失败基本是开发者工具里的不校验合法域名选项没勾上或者手机和电脑不在同一网络环境。5. 踩坑记录我在这套模板上翻过的车5.1 tabBar 图标不显示页面白了一块现象编译到微信开发者工具后底部 tabBar 上的图标区域一片空白文字能正常显示但图标加载不出来。原因我把图片放到了static/tabbar/目录下但pages.json里iconPath写成了相对路径../static/tabbar/home.pnguniapp 编译到微信小程序后静态资源路径解析规则不一样相对路径会错乱。解决pages.json里 tabBar 图标的iconPath直接写static/tabbar/home.png不带../。另外 tabBar 图标大小不能超过 40kb太大的图片在真机上可能显示异常这是微信的硬性限制。5.2 真机预览白屏控制台报wx is not defined现象在 HBuilderX 里模拟器跑得好好的一真机预览整个页面白屏打开 Debug 模式看控制台报wx is not defined。原因我在某个组件的script里直接调用了wx.login但该组件被用在了非微信端编译的场景下。HBuilderX 模拟器默认走微信环境所以没暴露真机走了微信开发者工具的预览模式运行环境差异导致全局对象没挂载。解决所有wx开头的 API 调用都改成uni.开头uniapp 已经做了跨端封装不需要直接操作wx对象。检查一遍项目凡是wx.开头的代码统一替换。5.3 支付时报支付签名验证失败现象下单接口返回的支付参数看起来很正常但uni.requestPayment一直报支付签名验证失败。原因后端同学给的signType是MD5但微信支付新商户号大多要求RSA2签名算法不匹配导致验签失败。另一个常见原因是他用测试密钥生成的签名而paySign是放在header里参与计算的前端没原样传递完整参数。解决先跟后端确认商户号的签名类型把signType改成对应的值。再把requestPayment里传入的参数和后端返回的参数一一比对——多一个空格、少一个字段都会导致验签失败。这个对坑字段比对用JSON.stringify打到控制台看最直观。5.4 分包加载失败提示超出大小限制现象模板加了pages/index/agent这个分销页后微信开发者工具报采用分包时主包大小不超过 2M。原因首页把分销页要用的几张背景图放在了static/里这些图会被打包进主包几张 100kb 的图就把主包撑大了。而且分销页和首页共用同一个goods-card组件主包体积自然就上去了。解决把分销页相关的图片移到分包目录下pages/agent/static/如果分销页要复用组件把公共组件也放到分包下的components/里。分包的管理方式后面会细讲核心思路是谁使用谁承载。6. 二次开发指南把通用模板改成你自己的商城6.1 主题配置与全局视觉替换商城模板的视觉风格集中在几个地方uni.scss里的主题色变量、App.vue里的全局样式、各页面的style块。换肤最省事的做法是改主题色变量。// uni.scss 里的主题配置改动后会全局生效 $primary-color: #e93b3b; // 主色调改成你的品牌色 $price-color: #e4393c; // 价格文字颜色通常配合主色 $bg-color: #f5f5f5; // 页面背景色 $border-color: #e0e0e0; // 分割线颜色改完之后全局的按钮、价格、选中态都会跟着变。注意不要直接在页面 style 里写死颜色值否则全局改色后单个页面不会同步。如果一个页面有特殊的视觉要求新建一个局部变量覆盖是更干净的做法。6.2 新增一个我的优惠券模块的完整流程以新增我的优惠券页面为例跑一遍模板的扩展流程。第一步在pages.json的pages数组里注册路由{ path: pages/user/coupon, style: { navigationBarTitleText: 我的优惠券 } }第二步创建页面文件pages/user/coupon.vue页面里用request()调接口。第三步如果优惠券要在个人中心展示入口去pages/user/user.vue里加一行列表项。这套模板的页面结构是扁平的加页面不会牵一发动全身。模板的通用不是体现在业务代码的完备性上而是它的网络层、组件层、状态层从第一天就为增加新模块做好了接口预留——你写新页面不会和现有代码产生耦合冲突。6.3 后端接口对接的联调要点和你的后端对接时建议先拉一个接口列表清单把路径、请求方法、请求参数、返回结构列清楚再逐项对齐模板里的common/request.js约定。重点对齐状态码字段、数据字段、错误信息字段、token 传递方式、分页参数命名。这几项对齐了业务开发就能回归到纯粹的新页面开发。我一般会在联调阶段把request.js里的uni.showToast错误提示改成console.error打印完整报错等联调完成再改回来。这样排查问题直接看控制台不用频繁被打断。这是血泪经验——联调时一半的时间都是浪费在找报错代码上。6.4 上线前必查的安全清单一是检查common/config.js里的env是否为prod避免把开发环境接口发上线。二是确认manifest.json里的 appid 是正式小程序的开发者工具和真机预览如果用的是测试号朋友圈分享、支付这些能力会受影响。三是微信公众平台后台的服务器域名白名单要和common/config.js一致漏一个域名整站接口就全挂了。四是main.js里如果有Vue.config.devtools true改成false。最后说一个我的习惯每次改完模板里的公共模块我都会重新跑一遍首页、分类、详情、购物车、支付这条链路确认没有一处运行时报错再把unpackage/dist目录清掉重新编译一次。第二次编译前我会删掉manifest.json里微信小程序的appid测试号改成真正要上线的正式 appid。从那以后凡是经过我手发布出去的商城小程序都会强制走一遍清缓存、重置 appid、真机全链路回归的流程这个习惯帮我挡掉了至少三次线上事故。希望这篇拆解能帮你在自己的业务里少踩几个坑。本文还有配套的精品资源点击获取
简介基于 uni-app 开发的微信商城小程序通用模板适合小程序入门者、前端学习者及需要快速搭建商城原型的学生或开发者。压缩包共 490 个文件体积仅 2.04MB以 275 个 JS 逻辑文件、117 个 Vue 页面组件为核心辅以 JSON 配置、SCSS 样式、PNG 图标及 WXML/WXSS 等小程序文件覆盖商品展示、购物车、订单等常见商城模块并带有 u-charts 图表库与 goeasy 实时通信脚本便于扩展数据可视化与消息推送能力。当前已有 382 人学习下载。模板内全部源码经过测试可直接运行目录结构清晰还包含说明文档、字体图标与许可信息既可作为课程设计、毕业设计或工程实训的项目基底也适合有基础的开发者在此基础上修改页面、接入接口快速实现个性化商城功能。1. 引言一份直接能上手的 uniapp 微信商城模板如果你接手过小程序项目大概都有过这种经历从零搭一个商城光是轮播图、分类、购物车、订单、支付这套基础结构写两周都觉得不够稳。这份基于 uniapp 开发的微信商城小程序通用模板把商城最常用的一套完整流程全部封装好了——商品列表、分类筛选、购物车、结算下单、微信支付、个人中心代码按模块分得清清楚楚原生支持 HBuilderX 一键编译到微信小程序连分包、隐私协议、登录态都处理好了。如果你是中小团队、外包开发或者想找个架子做二次开发的开发者拿到手改配置、换接口就能跑省掉的不只是重复造轮子还有你自己踩坑的时间。这套模板不是那种只摆了个界面的空壳里面订单状态机、支付回调、token 刷新这些配送环节都有实现能当正式项目的地基。2. 技术选型与整体架构从 HBuilderX 到微信开发者工具的完整链路2.1 技术栈与选型理由模板的技术栈很集中uni-app 框架 Vue 2 语法 Vuex 状态管理 uni.request 封装网络请求。整套东西都是围绕一套代码、多端编译这个核心目标来组织的。为什么用 Vue 2 而不是 Vue 3因为 uniapp 对 Vue 2 的生态支持最成熟第三方插件、原生插件、社区示例基本都是 Vue 2 版本对于做商城这类需要大量购物车、订单交互的业务系统稳定性优先级比新语法特性高。网络层没有引 axios 之类的库而是直接在common/request.js里用uni.request做了一层 Promise 封装。这个决策很务实小程序里uni.request本身就是跨端的再套 axios 反而要处理适配层多一份依赖多一份风险。请求封装里做了 token 自动附加、401 统一跳转登录、错误提示统一处理这些是商城这类业务最需要的通用能力。2.2 目录结构拆解├── pages/ # 页面目录 │ ├── index/ # 首页轮播图、分类入口、商品瀑布流 │ ├── category/ # 分类页左侧分类列表 右侧商品列表 │ ├── cart/ # 购物车数量增减、选中状态、结算入口 │ ├── order/ # 订单列表待付款/待发货/待收货/已完成 │ ├── goods/ # 商品详情SKU 选择、加入购物车、立即购买 │ ├── pay/ # 支付结果页 │ └── user/ # 个人中心登录状态、订单入口、地址管理 ├── components/ # 公共组件 │ ├── goods-card/ # 商品卡片组件 │ ├── sku-popup/ # SKU 选择弹窗 │ └── number-box/ # 数字输入框 ├── common/ │ ├── request.js # 请求封装 │ └── config.js # 全局配置接口域名、secret 等 ├── store/ │ ├── index.js # Vuex 入口 │ ├── cart.js # 购物车 module │ └── user.js # 用户与登录状态 module ├── static/ # 静态资源 ├── App.vue # 应用入口文件 ├── main.js # Vue 实例挂载 └── manifest.json # uniapp 配置appid、小程序配置这个结构是典型的页面 组件 状态 工具四层划分。pages.json里已经配好了底部 tabBar、页面路由和分包结构manifest.json里要改的主要是微信小程序的 appid。对二次开发最友好的部分是store/目录购物车和用户状态单独拆了 module改业务逻辑不需要在整个项目里翻找。2.3 请求封装与拦截器设计common/request.js是整个模板网络层的核心几乎所有页面都走这一个入口。它的设计思路是外部调用只管传 url、method、data封装内部处理 token、loading、错误码。// common/request.js const config require(./config.js) function request(options) { return new Promise((resolve, reject) { uni.request({ url: config.baseUrl options.url, method: options.method || GET, data: options.data || {}, header: { Content-Type: application/json, token: uni.getStorageSync(token) || }, success: (res) { // 业务状态码约定0 表示成功非 0 按业务错误处理 if (res.data.code 0) { resolve(res.data.data) } else if (res.data.code 401) { // token 失效清理本地登录态并跳转登录页 uni.removeStorageSync(token) uni.navigateTo({ url: /pages/login/login }) reject(res.data) } else { uni.showToast({ title: res.data.msg, icon: none }) reject(res.data) } }, fail: (err) { uni.showToast({ title: 网络异常请稍后重试, icon: none }) reject(err) } }) }) }这段封装里几个细节值得说明。header里的 token 每次请求都自动附加业务代码里不用每个接口单独传省了很多重复劳动。code 401时统一处理登录失效避免每个页面各自判断、各自跳转造成逻辑分散。success里先解包res.data.data让页面拿到的直接是业务数据而不是一层层嵌套的响应体这是很常见的接口约定。实际对接后端时你得和后端确认两件事业务状态码字段名是code还是status成功值是0还是200。模板默认是code 0如果后端用的status 200那只需改一个判断条件比在几十个页面里找请求代码要省事得多。3. 核心模块拆解商品、购物车、订单与支付的完整链路3.1 商品列表与分类筛选首页和分类页共同依赖商品列表接口。分类页用了左侧一级分类 右侧二级分类商品的经典布局左侧滚动时右侧联动切换。这个页面的核心逻辑不是界面渲染而是如何在切换分类时既不丢失滚动位置、又能按需加载数据。// pages/category/category.vue 核心逻辑 data() { return { categories: [], // 一级分类列表 currentCategory: 0, // 当前选中的一级分类下标 goodsList: [], // 右侧商品列表 page: 1, loading: false, finished: false } }, methods: { switchCategory(index) { this.currentCategory index this.page 1 this.goodsList [] this.finished false this.loadGoods() }, async loadGoods() { if (this.loading || this.finished) return this.loading true const data await getGoodsByCategory({ categoryId: this.categories[this.currentCategory].id, page: this.page }) this.goodsList this.page 1 ? data.list : this.goodsList.concat(data.list) this.finished data.list.length 10 this.page this.loading false } }switchCategory里先把数据源重置再拉新数据避免旧分类的数据残留导致界面闪现错乱。loadGoods里的concat而不是push是为了生成全新数组触发 Vue 的响应式更新这一点在 Vue 2 里尤其重要——直接push虽然也能渲染但配合上拉加载更多时容易出现渲染不及时。finished标志位用来阻止重复请求滚动到底部时如果已经没有更多数据就不会再发请求。商品卡片组件goods-card.vue被首页、分类页、搜索结果页复用封装了图片懒加载、价格格式化、库存状态、点击跳转详情这几件事。这个组件不持有数据所有属性都由父组件传入是一个纯展示组件二次开发时想加角标、加折扣标签直接改这一处就行。3.2 购物车状态管理购物车是商城项目里最容易写乱的部分所以模板用 Vuex 单独管理。store/cart.js维护购物车列表、选中状态、总价、总数量所有页面都从 store 读取而不是每个页面自己维护一份数据。// store/cart.js const state { cartList: [], // [{ id, goodsId, skuId, name, price, count, checked }] checkedItems: [] // 当前选中的购物车项 } const getters { totalCount: (state) { return state.cartList.reduce((sum, item) { return sum (item.checked ? item.count : 0) }, 0) }, totalPrice: (state) { return state.cartList.reduce((sum, item) { return sum (item.checked ? item.price * item.count : 0) }, 0) } }totalCount和totalPrice都只统计checked的条目这样购物车底部的结算栏数据是实时计算的不用在增减数量、切换选中时手动去改 UI 上的数字。这是个很容易忽略的设计——很多人写购物车是在 setData 里手工更新总价逻辑一多就会出现数量改了价格没变的 bug。购物车条目的数据结构里有个skuId字段这是为了区分同一商品的不同规格颜色、尺码。模板的 SKU 弹窗sku-popup.vue会把选中的规格组合转换成后端接口需要的一个skuId加入购物车时带上结算时也靠它来确定具体买的是哪个规格。如果后端没有 SKU 体系可以直接忽略这个字段。3.3 微信支付与订单流程支付链路是商城里最复杂的场景模板的处理方式是前端只负责唤起支付结果以回调为准。下单接口返回支付参数后前端通过uni.requestPayment调起微信支付面板然后在success回调里跳转支付结果页同时启动一个定时器去轮询订单状态。// pages/pay/pay.js 关键逻辑 async function submitOrder(orderData) { const res await createOrder(orderData) // 返回 payParams uni.requestPayment({ provider: wxpay, timeStamp: res.timeStamp, nonceStr: res.nonceStr, package: res.package, signType: RSA2, paySign: res.paySign, success: () { // 支付成功的乐观处理跳转结果页后台异步确认 uni.redirectTo({ url: /pages/pay/success }) pollOrderStatus(res.orderId) }, fail: (err) { // 用户取消或支付失败统一走这里 uni.redirectTo({ url: /pages/pay/fail }) } }) } function pollOrderStatus(orderId) { // 每 2 秒查一次订单状态最多查 10 次 let count 0 const timer setInterval(async () { const order await getOrderDetail(orderId) if (order.status paid) { clearInterval(timer) // 更新本地订单列表状态 } if (count 10) clearInterval(timer) }, 2000) }这里有个重要的经验uni.requestPayment的success回调并不代表支付已经 100% 到账可能只是微信返回了一个用户已支付的中间态。模板里用pollOrderStatus轮询去确认订单的真实状态这是防止前端显示成功、后台没收到回调这类问题的手段。传入requestPayment的这些参数全部来自后端下单接口前端不能自己拼。timeStamp是后端生成的支付时间戳paySign是后端用商户私钥做的签名前端只是透传。如果签名报错或支付参数不合法先看后端拿到的prepay_id是否有效十有八九是商户号配置或签名算法有问题。订单列表页面抽了OrderStatus常量把待付款、待发货、待收货、已完成映射成数字状态码并提供了对应的操作按钮待付款显示去支付、待收货显示确认收货。这个状态机放在common/order.js里后端返回数字状态前端映射成文案和行为改的时候只看一个文件。3.4 登录鉴权与用户信息模板的登录体系是微信授权 后端换 token的经典模式。用户点击登录时调用wx.login拿code把code发给后端后端再向微信接口换取openid并签发自定义 token。// store/user.js 登录逻辑 async function login() { const { code } await uni.login({ provider: weixin }) const res await request({ url: /auth/login, method: POST, data: { code } }) uni.setStorageSync(token, res.token) uni.setStorageSync(userInfo, res.userInfo) return res.userInfo }模板里把 token 存在本地缓存后续所有请求通过common/request.js自动带上。这里涉及一个取舍wx.login拿到的code有效期只有 5 分钟所以登录动作必须在用户点击登录或进入需要登录的页面时实时执行而不是拿一个旧 code 去换 token。很多开发者在用户进入小程序时就提前登录一次等真正需要请求接口时 code 已经过期这就是偶尔能登录、偶尔要重试的原因。如果只做微信一键登录模板是用默认逻辑但如果你是二次开发接自己的后端需要和后端约定code换 token 的接口路径是否一致、token 的失效策略是什么。模板默认 token 永久有效后端不做过期校验正式上线前建议加上过期时间和服务端校验。4. 环境配置与运行指南从零到跑通4.1 环境准备与工具版本跑这个模板不需要很重的环境主要就三个工具HBuilderX、微信开发者工具、一个可用的后端接口地址。HBuilderX 用来打开项目并编译到微信小程序微信开发者工具用来预览调试和查看控制台。版本方面建议HBuilderX 用最新稳定版3.x 以上微信开发者工具用最新版这两个工具对新版微信基础库兼容性更好。模板本身没有高版本的独有 API 依赖所以不用刻意追新。4.2 关键配置项修改拿到的模板不能直接编先把三个地方改成你自己的manifest.json的微信小程序 appid、common/config.js的后端接口域名、pages.json的页面路径是否要调整。// manifest.json 中需要修改的配置 { mp-weixin: { appid: 你的微信小程序appid, setting: { urlCheck: false }, usingComponents: true } }urlCheck在开发阶段建议关掉否则微信开发者工具会拦截非白名单域名的请求导致真机预览时所有接口都报域名不合法。这个只在开发环境关上线前要去微信公众平台配置 request 合法域名否则正式版小程序同样会请求失败。common/config.js里改接口地址// common/config.js module.exports { // 开发环境接口地址 baseUrl: https://dev-api.example.com, // 正式环境接口地址 prodUrl: https://api.example.com, // 当前环境标识dev 或 prod env: dev, // 图片资源域名前缀 imgBaseUrl: https://cdn.example.com/images }imgBaseUrl很关键。商城项目里商品图、轮播图基本都是后台返回的完整 URL但偶尔会有后端只返回相对路径的情况。模板里所有图片渲染都拼了这个前缀实际对接时看后端返回的是完整地址还是相对路径如果是完整的就直接用别拼重了。4.3 编译运行与真机调试HBuilderX 打开项目后点击菜单栏运行-运行到小程序模拟器-微信开发者工具会自动唤起开发者工具并加载编译产物。首次运行会要求关联 appid使用测试号也可以。# 编译产物在项目根目录的 unpackage/dist/dev/mp-weixin 下 # 微信开发者工具导入时要选这个目录不是项目根目录很多新手在微信开发者工具里打开整个项目根目录而不是编译产物目录结果看到的是 .vue 文件而不是编译后的代码还问为什么全是 vue 文件。记住一点uniapp 项目本身不是微信原生小程序微信开发者工具里能跑、能断点调试的是编译后的mp-weixin目录。真机预览直接在微信开发者工具里点预览会生成一个二维码用微信扫了就能在真机上跑。真机调试时注意urlCheck关了但手机仍然请求失败基本是开发者工具里的不校验合法域名选项没勾上或者手机和电脑不在同一网络环境。5. 踩坑记录我在这套模板上翻过的车5.1 tabBar 图标不显示页面白了一块现象编译到微信开发者工具后底部 tabBar 上的图标区域一片空白文字能正常显示但图标加载不出来。原因我把图片放到了static/tabbar/目录下但pages.json里iconPath写成了相对路径../static/tabbar/home.pnguniapp 编译到微信小程序后静态资源路径解析规则不一样相对路径会错乱。解决pages.json里 tabBar 图标的iconPath直接写static/tabbar/home.png不带../。另外 tabBar 图标大小不能超过 40kb太大的图片在真机上可能显示异常这是微信的硬性限制。5.2 真机预览白屏控制台报wx is not defined现象在 HBuilderX 里模拟器跑得好好的一真机预览整个页面白屏打开 Debug 模式看控制台报wx is not defined。原因我在某个组件的script里直接调用了wx.login但该组件被用在了非微信端编译的场景下。HBuilderX 模拟器默认走微信环境所以没暴露真机走了微信开发者工具的预览模式运行环境差异导致全局对象没挂载。解决所有wx开头的 API 调用都改成uni.开头uniapp 已经做了跨端封装不需要直接操作wx对象。检查一遍项目凡是wx.开头的代码统一替换。5.3 支付时报支付签名验证失败现象下单接口返回的支付参数看起来很正常但uni.requestPayment一直报支付签名验证失败。原因后端同学给的signType是MD5但微信支付新商户号大多要求RSA2签名算法不匹配导致验签失败。另一个常见原因是他用测试密钥生成的签名而paySign是放在header里参与计算的前端没原样传递完整参数。解决先跟后端确认商户号的签名类型把signType改成对应的值。再把requestPayment里传入的参数和后端返回的参数一一比对——多一个空格、少一个字段都会导致验签失败。这个对坑字段比对用JSON.stringify打到控制台看最直观。5.4 分包加载失败提示超出大小限制现象模板加了pages/index/agent这个分销页后微信开发者工具报采用分包时主包大小不超过 2M。原因首页把分销页要用的几张背景图放在了static/里这些图会被打包进主包几张 100kb 的图就把主包撑大了。而且分销页和首页共用同一个goods-card组件主包体积自然就上去了。解决把分销页相关的图片移到分包目录下pages/agent/static/如果分销页要复用组件把公共组件也放到分包下的components/里。分包的管理方式后面会细讲核心思路是谁使用谁承载。6. 二次开发指南把通用模板改成你自己的商城6.1 主题配置与全局视觉替换商城模板的视觉风格集中在几个地方uni.scss里的主题色变量、App.vue里的全局样式、各页面的style块。换肤最省事的做法是改主题色变量。// uni.scss 里的主题配置改动后会全局生效 $primary-color: #e93b3b; // 主色调改成你的品牌色 $price-color: #e4393c; // 价格文字颜色通常配合主色 $bg-color: #f5f5f5; // 页面背景色 $border-color: #e0e0e0; // 分割线颜色改完之后全局的按钮、价格、选中态都会跟着变。注意不要直接在页面 style 里写死颜色值否则全局改色后单个页面不会同步。如果一个页面有特殊的视觉要求新建一个局部变量覆盖是更干净的做法。6.2 新增一个我的优惠券模块的完整流程以新增我的优惠券页面为例跑一遍模板的扩展流程。第一步在pages.json的pages数组里注册路由{ path: pages/user/coupon, style: { navigationBarTitleText: 我的优惠券 } }第二步创建页面文件pages/user/coupon.vue页面里用request()调接口。第三步如果优惠券要在个人中心展示入口去pages/user/user.vue里加一行列表项。这套模板的页面结构是扁平的加页面不会牵一发动全身。模板的通用不是体现在业务代码的完备性上而是它的网络层、组件层、状态层从第一天就为增加新模块做好了接口预留——你写新页面不会和现有代码产生耦合冲突。6.3 后端接口对接的联调要点和你的后端对接时建议先拉一个接口列表清单把路径、请求方法、请求参数、返回结构列清楚再逐项对齐模板里的common/request.js约定。重点对齐状态码字段、数据字段、错误信息字段、token 传递方式、分页参数命名。这几项对齐了业务开发就能回归到纯粹的新页面开发。我一般会在联调阶段把request.js里的uni.showToast错误提示改成console.error打印完整报错等联调完成再改回来。这样排查问题直接看控制台不用频繁被打断。这是血泪经验——联调时一半的时间都是浪费在找报错代码上。6.4 上线前必查的安全清单一是检查common/config.js里的env是否为prod避免把开发环境接口发上线。二是确认manifest.json里的 appid 是正式小程序的开发者工具和真机预览如果用的是测试号朋友圈分享、支付这些能力会受影响。三是微信公众平台后台的服务器域名白名单要和common/config.js一致漏一个域名整站接口就全挂了。四是main.js里如果有Vue.config.devtools true改成false。最后说一个我的习惯每次改完模板里的公共模块我都会重新跑一遍首页、分类、详情、购物车、支付这条链路确认没有一处运行时报错再把unpackage/dist目录清掉重新编译一次。第二次编译前我会删掉manifest.json里微信小程序的appid测试号改成真正要上线的正式 appid。从那以后凡是经过我手发布出去的商城小程序都会强制走一遍清缓存、重置 appid、真机全链路回归的流程这个习惯帮我挡掉了至少三次线上事故。希望这篇拆解能帮你在自己的业务里少踩几个坑。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
