简介这是一套面向微信小程序开发者与Java全栈学习者的农产品电商实战项目源码适用于高校课程设计、毕业设计及中小型企业原型开发参考。项目采用前后端分离架构前端基于微信小程序原生框架含wxml/wxss/js/json等1195个文件后端整合SSMSpringSpringMVCMyBatis与MySQL配套231张静态资源图、166个业务逻辑JS、133个Vue组件及127个Java服务类完整覆盖用户端浏览下单与后台多角色管理全流程。压缩包体积14.86MB结构规范含build/run/install三类批处理脚本及.bak备份文件便于环境快速部署与代码比对。已有488人学习下载提供从注册登录、首页展示、商品分类到订单管理、特价运营、管理员权限控制等全部功能模块的可运行实现附带数据库SQL脚本与配置说明开箱即用适合进阶实践与二次开发。1. 农产品销售类微信小程序为什么总卡在“能跑通”和“能上线”之间你下载了一个标着「微信小程序开发项目实例-农产品销售平台(源码).zip」的压缩包解压后看到build.bat、run.bat、install.bat三个批处理文件还有一堆pages/、components/、utils/目录——这确实是典型微信小程序工程结构。但问题来了双击run.bat启动失败控制台报Cannot find module miniprogram-ciinstall.bat执行到一半卡在npm install小程序开发者工具导入项目后首页白屏、商品列表空、下单按钮点击无响应。这不是代码写得差而是农产品销售类小程序天然带着三重硬约束一是真实农户/合作社常需离线扫码下单要求本地缓存离线队列二是图片多、视频多微信对小程序包体积限制 2MB主包必须 ≤2MB但高清农产品图一张就 300KB三是支付链路必须兼容微信原生支付 苹果 IAP 补偿iOS 端虚拟商品强制走 IAP但农产品是实物必须绕过 IAP 走微信支付。这个源码包不是教学玩具它是为解决这些真实业务卡点而设计的最小可行闭环。适合正在接县域电商、助农平台外包项目的前端工程师或需要快速验证农产品上行模式的产品经理——它不教你wx:for怎么写而是直接给你一套能扛住日均 500 单、图片自动压缩、支付失败自动降级、离线订单暂存再同步的落地骨架。2. 从源码包解压到真机可测四步走通本地开发环境这个.zip包不是“开箱即用”而是“开箱即调”。它的install.bat和run.bat是为 Windows 开发者定制的快捷入口但默认配置会踩坑。我们必须先理解它依赖的三层技术栈最底层是微信小程序基础框架WXML/WXSS/JS中间层是miniprogram-ci提供的自动化构建能力用于上传、预检、生成体验版最上层是它自研的offline-order-manager模块处理离线下单。下面四步每一步都对应一个关键决策点。2.1 环境检查确认 Node.js 与微信开发者工具版本匹配该源码包基于微信小程序基础库2.28.2开发查看project.config.json中libVersion: 2.28.2要求 Node.js 版本 ≥ 14.18.0低于此版本miniprogram-ci会报ERR_REQUIRE_ESM。常见翻车点是你装了 Node.js 16但npm -v显示 8.x —— 这说明 npm 未随 Node 升级需手动执行npm install -g npm9.6.7提示不要用 nvm 切换 Node 版本后直接运行install.bat。该脚本默认调用系统 PATH 中第一个node.exe若你用 nvm 安装多个版本需先nvm use 16.20.2再以管理员身份运行 CMD否则npm install会因权限不足卡在node-gyp rebuild。验证命令node -v npm -v echo %PATH% | findstr wechatdevtools输出应类似v16.20.29.6.7C:\Program Files\WeChat Web DevTools\确保微信开发者工具安装路径已加入 PATH2.2 依赖安装绕过miniprogram-ci的网络墙与证书校验install.bat本质是执行npm install但该包package.json中指定了miniprogram-ci: ^1.12.0。国内网络下npm install常因miniprogram-ci依赖的wechat-miniprogram/miniapp-ci-core下载超时失败。正确做法是跳过install.bat手动分步安装# 1. 先装核心依赖不含 ci 工具 npm install --no-save # 2. 单独安装 miniprogram-ci并指定淘宝镜像源 npm install miniprogram-ci1.12.0 --registry https://registry.npmmirror.com # 3. 验证是否成功不报错即通过 npx miniprogram-ci --version若仍报certificate has expired说明系统根证书过期。临时方案仅开发环境set NODE_TLS_REJECT_UNAUTHORIZED0 npx miniprogram-ci login --login-qrcode注意NODE_TLS_REJECT_UNAUTHORIZED0仅用于本地调试上线前必须删除该环境变量否则存在 HTTPS 中间人风险。2.3 项目配置修改project.config.json中的 AppID 与云开发环境源码包中project.config.json的appid字段为占位符wx1234567890abcdef必须替换为你自己的小程序 AppID登录 微信公众平台 → 开发管理 → 开发设置获取。更关键的是云开发配置该农产品平台使用云开发数据库存储商品信息、订单、用户地址app.js中有如下初始化wx.cloud.init({ env: prod-abc123, // ← 必须替换成你创建的云开发环境 ID traceUser: true })操作路径微信开发者工具 → 云开发 → 新建环境 → 选择「基础版」→ 记下环境 ID如prod-abc123→ 替换app.js中的env值。切勿跳过此步否则wx.cloud.database().collection(products).get()将返回空数组首页商品列表永远为空。2.4 启动调试用run.bat的替代方案启动真机预览run.bat默认执行npm run dev但该脚本在package.json中定义为scripts: { dev: miniprogram-ci build --no-cache --upload-desc dev-build }这会直接打包上传不适合本地调试。正确做法是关闭run.bat改用开发者工具 GUI 启动微信开发者工具 → 导入项目 → 选择解压后的根目录工具栏点击「编译」CtrlB→ 观察控制台是否有VMxxxx:1 Uncaught TypeError: Cannot read property xxx of undefined若有打开app.js查找报错行大概率是wx.getStorageSync(user_info)返回 null未登录→ 此时需先在模拟器中点击「授权登录」按钮编译成功后点击「预览」→ 扫码 → 在真机上测试「添加购物车」「提交订单」流程血泪经验真机预览时iOS 用户常遇到「网络请求失败率很高」热词中提到的web分析6001错误。根本原因是app.json中networkTimeout配置过短。该源码包默认设为50005秒但农产品图片上传常需 8~12 秒。必须改为networkTimeout: { request: 15000, downloadFile: 30000, uploadFile: 30000, connectSocket: 10000 }3. 商品页性能攻坚2MB 主包限制下的图片与视频加载策略农产品销售小程序最大的性能瓶颈不是逻辑而是媒体资源。一筐苹果高清图 4 张 × 300KB 1.2MB再加首页轮播视频即使压缩到 1MB直接突破 2MB 主包上限。该源码包没用「把图片全扔 CDN」这种懒方案而是采用三级渐进加载主包内嵌低清占位图 → 首次进入时按需下载高清图 → 视频延迟加载并自动降级为 GIF。这是它能通过微信审核的关键。3.1 主包瘦身用gulp-imagemin自动压缩内嵌图片源码包static/images/下存放所有主包内图片logo、图标、占位图。build.bat的核心逻辑是调用gulpfile.js执行压缩// gulpfile.js 关键片段 const imagemin require(gulp-imagemin); const pngquant require(imagemin-pngquant); gulp.task(images, () { return gulp.src(static/images/**/*.{png,jpg,gif,svg}) .pipe(imagemin([ pngquant({ quality: [0.6, 0.8] }), // PNG 有损压缩质量 60%~80% imagemin.mozjpeg({ quality: 75 }), // JPG 压缩至 75 质量 imagemin.svgo() // SVG 移除注释和元数据 ])) .pipe(gulp.dest(miniprogram/static/images)); });执行npm run build:images后miniprogram/static/images/下的图片体积平均减少 62%。例如apple-banner.jpg原 286KB→apple-banner.jpg压缩后 108KB。参数说明quality: 75是平衡点——低于 70 会出现明显色块高于 80 体积节省不足 5%但加载时间增加 200ms。3.2 高清图按需加载wx.downloadFilewx.setStorage组合缓存商品详情页的高清图如product-detail-1.jpg不在主包中而是存于云存储。加载逻辑在pages/product-detail/product-detail.js// 商品详情页 onLoad 时触发 onLoad: function (options) { const imgKey product_${options.id}_detail; // 1. 先查本地缓存 const cachedPath wx.getStorageSync(imgKey); if (cachedPath) { this.setData({ detailImage: cachedPath }); return; } // 2. 未缓存则下载 wx.downloadFile({ url: https://xxx.file.myqcloud.com/${options.id}/detail.jpg, success: (res) { if (res.statusCode 200) { // 3. 保存到本地临时路径并写入缓存 wx.saveFile({ tempFilePath: res.tempFilePath, success: (saveRes) { wx.setStorageSync(imgKey, saveRes.savedFilePath); this.setData({ detailImage: saveRes.savedFilePath }); } }); } } }); }避坑点wx.downloadFile在 iOS 真机上可能因 ATSApp Transport Security策略拒绝 HTTP 请求。必须确保云存储 URL 是https且证书有效。若用腾讯云 COS需在 COS 控制台开启「HTTPS 强制跳转」。3.3 视频降级策略video标签的 fallback 机制首页轮播区嵌入农场实拍视频但微信小程序video在低端安卓机上常卡顿。该源码包采用「视频优先GIF 保底」方案!-- pages/index/index.wxml -- view classbanner-video video src{{videoUrl}} autoplay loop muted show-play-btn{{false}} binderroronVideoError stylewidth:100%; height:300rpx; / !-- 当 video 加载失败时显示 GIF -- image wx:if{{!videoLoaded}} src/static/images/banner-fallback.gif modeaspectFill stylewidth:100%; height:300rpx; / /view// pages/index/index.js data: { videoUrl: https://xxx.cos.ap-guangzhou.myqcloud.com/videos/farm.mp4, videoLoaded: false }, onVideoError: function(e) { console.log(video load failed:, e.detail.errMsg); this.setData({ videoLoaded: false }); }, onLoad: function() { // 2秒后若 video 仍未加载成功则切换到 GIF setTimeout(() { if (!this.data.videoLoaded) { this.setData({ videoLoaded: false }); } }, 2000); }玄学参数setTimeout设为 2000ms 是经验值。太短如 500ms会导致正常网络下也降级太长如 5000ms会让用户等待过久。实测 2000ms 覆盖 92% 的弱网场景。4. 支付与订单闭环绕过苹果 IAP 限制的实物商品支付方案这是该源码包最值得深挖的部分。热词中反复出现「微信小程序虚拟支付 苹果iap退款」、「uniapp接入天地图适配微信小程序、h5、app」说明跨端支付一致性是行业痛点。但农产品是实物商品iOS 端绝不能走 IAP苹果会拒审必须 100% 走微信支付。该源码包的解决方案是服务端统一下单 客户端条件渲染 支付失败自动降级为货到付款COD。4.1 服务端统一下单cloud-functions/pay/createOrder函数云函数pay/createOrder是支付中枢接收小程序端传来的orderItems、addressId返回prepay_id// cloud-functions/pay/createOrder/index.js exports.main async (event, context) { const { orderItems, addressId } event; // 1. 校验库存原子操作 const db cloud.database(); const transaction await db.startTransaction(); try { for (const item of orderItems) { const product await transaction.collection(products) .doc(item.productId) .field({ stock: true }) .get(); if (product.data.stock item.count) { throw new Error(库存不足${item.name}); } // 扣减库存 await transaction.collection(products) .doc(item.productId) .update({ data: { stock: _.inc(-item.count) } }); } // 2. 创建订单记录 const orderId ORD${Date.now()}${Math.floor(Math.random()*1000)}; await transaction.collection(orders).add({ data: { _id: orderId, items: orderItems, addressId, status: unpaid, createdAt: new Date() } }); // 3. 调用微信统一下单 API此处省略签名逻辑 const result await callWechatPayAPI({ out_trade_no: orderId, total_fee: calculateTotal(orderItems), body: 农产品订单 }); return { prepayId: result.prepay_id, timestamp: Date.now() }; } catch (e) { await transaction.rollback(); throw e; } };关键设计事务transaction保证「扣库存」和「建订单」原子性。若扣库存成功但建订单失败事务回滚库存恢复——避免出现「用户看到下单成功但后台没订单」的资损。4.2 客户端条件渲染iOS 与安卓支付按钮差异化pages/order-confirm/order-confirm.wxml中支付按钮根据系统动态切换!-- 判断是否 iOS -- view wx:if{{isIOS}} button bindtaponPay classbtn-pay disabled{{!canPay}} {{ canPay ? 微信支付 : 请填写完整收货信息 }} /button !-- iOS 端隐藏 IAP 提示 -- view wx:if{{false}}iOS 用户请注意本商品为实物无需 IAP/view /view view wx:else button bindtaponPay classbtn-pay disabled{{!canPay}} {{ canPay ? 微信支付 : 请填写完整收货信息 }} /button /vieworder-confirm.js中检测逻辑onLoad: function() { const systemInfo wx.getSystemInfoSync(); this.setData({ isIOS: /iPhone|iPad|iPod/.test(systemInfo.model) }); }注意不要用systemInfo.platform ios微信开发者工具中platform返回devtools真机才返回ios或android。正则匹配model更可靠。4.3 支付失败降级COD货到付款的本地化实现当用户点击支付后微信支付弹窗取消或超时wx.requestPayment的fail回调触发 COD 流程onPay: async function() { try { const res await cloud.callFunction({ name: pay/createOrder, data: { orderItems: this.data.orderItems, addressId: this.data.addressId } }); wx.requestPayment({ timeStamp: ${res.result.timestamp}, nonceStr: random-string, package: prepay_id${res.result.prepayId}, signType: RSA, paySign: sign-here, // 实际由服务端生成 success: () { wx.showToast({ title: 支付成功, icon: success }); this.updateOrderStatus(paid); }, fail: (err) { console.error(payment failed:, err); // 降级为 COD this.setData({ codMode: true }); wx.showModal({ title: 支付未完成, content: 您可选择货到付款收货时现金支付给快递员, confirmText: 确认货到付款, success: (modalRes) { if (modalRes.confirm) { this.submitCodOrder(); // 调用云函数创建 COD 订单 } } }); } }); } catch (e) { wx.showToast({ title: 下单失败, icon: none }); } }避坑 / 常见问题 / 排查现象 1iOS 真机点击支付按钮无反应控制台无报错原因wx.requestPayment的timeStamp必须是字符串类型且长度为 10 位 Unix 时间戳。若服务端返回timestamp: 1712345678数字iOS 会静默失败。解决服务端返回String(Date.now())客户端接收后直接使用不转换。现象 2COD 订单创建后用户收不到短信通知原因云函数cod/create中调用短信 API 时region参数写成ap-guangzhou但短信服务实际区域是ap-beijing。解决在云开发控制台 → 云函数 → 环境配置中将SMS_REGION设为ap-beijing代码中读取process.env.SMS_REGION。现象 3安卓机支付成功后订单状态仍为unpaid原因wx.requestPayment.success回调中调用this.updateOrderStatus(paid)但该方法未await云函数导致状态更新被丢弃。解决updateOrderStatus必须返回 Promise并在 success 中awaitsuccess: async () { await this.updateOrderStatus(paid); // ← 加 await wx.showToast({ title: 支付成功, icon: success }); }5. 离线能力实战农户无网络时扫码下单的本地队列与同步机制这才是该源码包区别于普通电商小程序的核心价值。热词中「微信小程序 ios 静音状态下播放音乐」、「微信小程序返回拦截」看似无关实则指向同一底层能力小程序的本地存储与生命周期控制。农产品销售常发生在信号弱的田间地头农户用手机扫合作社二维码下单此时若无网络订单不能丢——必须暂存本地等有网时自动同步。5.1 离线订单队列wx.setStorageSync存储序列化订单pages/scan-order/scan-order.js中扫码后立即生成订单对象并存入本地// 扫码成功回调 onScanCodeSuccess: function(res) { const orderData { id: OFFLINE_${Date.now()}_${Math.random().toString(36).substr(2, 9)}, productId: res.result.split(-)[1], count: 1, scanner: wx.getStorageSync(userInfo)?.openid || unknown, timestamp: Date.now(), synced: false // 标记是否已同步 }; // 存入本地队列key 固定避免覆盖 const queue wx.getStorageSync(offlineOrderQueue) || []; queue.push(orderData); wx.setStorageSync(offlineOrderQueue, queue); wx.showToast({ title: 已加入待同步订单, icon: success }); }参数说明offlineOrderQueue是字符串键名值为数组。微信wx.setStorageSync对单个 key 有 10MB 限制但单个订单对象约 2KB10MB 可存 5000 条足够覆盖 3 天离线量。5.2 同步触发时机onNetworkStatusChangeonShow双保险离线订单不能只靠「网络恢复时」同步因为小程序可能被系统杀死。该源码包采用双触发机制// app.js 中全局监听 onLaunch: function() { // 1. 应用启动时检查 this.checkAndSyncOfflineOrders(); // 2. 网络状态变化时检查 wx.onNetworkStatusChange((res) { if (res.isConnected) { this.checkAndSyncOfflineOrders(); } }); }, checkAndSyncOfflineOrders: async function() { const queue wx.getStorageSync(offlineOrderQueue) || []; const unsynced queue.filter(item !item.synced); if (unsynced.length 0) return; try { // 调用云函数批量同步 const res await cloud.callFunction({ name: offline/sync, data: { orders: unsynced } }); // 同步成功后从本地队列移除 const newQueue queue.filter(item item.synced); wx.setStorageSync(offlineOrderQueue, newQueue); wx.showToast({ title: 同步 ${res.result.successCount} 笔订单, icon: success }); } catch (e) { console.error(sync failed:, e); // 同步失败不清理队列下次继续尝试 } }关键设计offline/sync云函数内部对每笔订单做try...catch部分失败不影响整体。返回{ successCount: 3, failedIds: [OFFLINE_1712345678_xxx] }前端只清理成功的订单。5.3 离线 UI 可视化订单列表顶部的「待同步」横幅用户需要感知离线订单状态。pages/order-list/order-list.wxml中插入状态横幅view wx:if{{offlineCount 0}} classoffline-banner text⚠️ 检测到 {{offlineCount}} 笔待同步订单/text button bindtapsyncNow sizemini立即同步/button /view !-- 订单列表 -- view wx:for{{orders}} wx:keyid !-- ... -- /vieworder-list.js中计算逻辑onLoad: function() { const queue wx.getStorageSync(offlineOrderQueue) || []; const offlineCount queue.filter(item !item.synced).length; this.setData({ offlineCount }); }, syncNow: function() { getApp().checkAndSyncOfflineOrders(); }后悔药设计syncNow按钮提供手动触发入口。曾有农户反馈「等了一小时网络没自动同步」其实是他家 Wi-Fi 名字含中文微信小程序无法识别为「已连接」onNetworkStatusChange未触发。手动按钮就是他的后悔药。6. 交付前必做的五项验证从代码到上线的最后防线交付一个农产品小程序不是「能跑就行」而是要经得起三类人的检验农户操作是否傻瓜、县域运营人员后台是否好管、微信审核员是否合规。这五项验证我带过 7 个助农项目每次上线前都逐项打钩漏一项就可能被拒审或现场翻车。6.1 主包体积验证用miniprogram-ci精确测量微信要求主包 ≤2MB但开发者工具「详情」页显示的体积常比真实上传体积小 10%~15%因未计入miniprogram_npm编译产物。必须用miniprogram-ci真实构建后检查# 1. 构建生成 dist 目录 npx miniprogram-ci build --no-cache --no-upload # 2. 计算 dist 目录大小Windows Get-ChildItem -Path ./dist -Recurse | Measure-Object -Property Length -Sum | ForEach-Object {$_.Sum / 1MB} # 输出示例1.9234567890123457边界值若结果 2.0必须砍掉miniprogram_npm中非必要包。该源码包用lodash但只用了_.debounce可替换为 30 行手写 debounce 函数节省 86KB。6.2 支付链路全路径验证从下单到发货的七步断点用测试账号走一遍完整链路每步截图存档步骤操作预期结果检查点1商品页点击「立即购买」跳转至order-confirm地址列表可选wx.getStorageSync(addressList)不为空2选择地址点击「去支付」弹出微信支付确认框wx.requestPayment被调用3支付成功toast「支付成功」订单状态变「待发货」云数据库orders表中该订单status paid4运营后台发货订单状态变「已发货」小程序端onShow时拉取最新状态5用户点击「确认收货」状态变「已完成」积分到账cloud.callFunction(order/confirmReceive)成功6iOS 真机取消支付弹出 COD 确认弹窗wx.showModal显示「货到付款」文案7断网下单后连网「待同步」横幅消失订单出现在列表offlineOrderQueue为空血泪教训第 4 步「运营后台发货」常被忽略。该源码包的运营后台是独立 H5 系统需确保其调用云函数order/updateStatus时event.status传的是字符串shipped而非数字2——后者会导致小程序端switch(status)匹配失败状态卡死。6.3 离线场景压力测试模拟 3G 网络 强制杀进程用 Chrome DevTools 模拟弱网再手动杀进程验证队列可靠性微信开发者工具 → 调试器 → Network → 选Fast 3G扫码下单 3 笔 → 点击「立即同步」→ 观察控制台sync failed日志制造失败点击右上角「停止」→ 再点击「编译」重启小程序检查首页是否仍显示「待同步 3 笔」→ 点击同步 → 应全部成功关键指标从杀进程到重启后读取offlineOrderQueue耗时应 200ms。若超过说明wx.getStorageSync被阻塞——检查是否有其他地方在onLaunch中执行同步 IO 操作如读大文件。6.4 审核敏感词扫描用正则过滤所有 WXML/WXSS/JS 中的违禁词微信审核严禁「最优惠」「第一」「国家级」等绝对化用语。该源码包在utils/audit-check.js中内置扫描器const forbiddenWords [ /最.*?优惠/g, /第一.*?品牌/g, /国家级.*?认证/g, /稳赚.*?不赔/g, /微信.*?官方/g // 防止误导用户以为是微信自营 ]; function scanProject() { const files getAllWxssWxmlJsFiles(); let issues []; files.forEach(file { const content fs.readFileSync(file, utf8); forbiddenWords.forEach(regex { const matches content.match(regex); if (matches) { issues.push({ file, word: regex.toString(), matches: matches.length }); } }); }); return issues; }运行node utils/audit-check.js输出应为空数组。若发现pages/index/index.wxml中有全场最低价必须改为全场实惠价。6.5 iOS 静音兼容性验证验证「静音状态下播放提示音」是否生效热词中「微信小程序 ios 静音状态下播放音乐」直指一个坑iOS 静音开关关闭时wx.playVoice默认静音。但订单成功提示音必须响——农户在嘈杂环境需要听觉反馈。解决方案在utils/audio.js// 使用 createInnerAudioContext 替代 playVoice const innerAudioContext wx.createInnerAudioContext(); innerAudioContext.src /static/audio/order-success.mp3; innerAudioContext.volume 1; innerAudioContext.play(); // iOS 静音下仍可播放 // 关键设置 obeyMuteSwitch 为 false innerAudioContext.obeyMuteSwitch false;验证方法iPhone 设置 → 声音 → 关闭「铃声和提醒」→ 打开小程序 → 下单 → 听是否响起提示音。若无声检查obeyMuteSwitch是否设为false默认为true。我带的第一个县域项目上线当天接到合作社电话「下单没声音老张以为没点上连点 5 次生成 5 笔重复订单」。后来我们把obeyMuteSwitch false写进每个音频播放处还加了震动反馈wx.vibrateShort()作双重保险。希望帮到你。本文还有配套的精品资源点击获取