简介：本资源是一个开源的微信小程序实战项目——「我厨」，面向小程序初学者与前端开发者，聚焦餐饮类服务场景的界面实现与基础交互逻辑，适合用于学习小程序组件化开发、API调用及多页面路由管理。压缩包共50个文件，包含14个WXML页面结构文件、9个JS逻辑脚本（含api.js、util.js等核心模块）、7个WXSS样式文件、7个JSON配置文件（如app.json、pages配置）以及11张PNG图标资源，整体仅125KB，轻量易读，目录结构清晰体现标准小程序分层设计（pages/、utils/、api/、images/、tabBar/等）。已有135人学习下载，可直接导入开发者工具运行调试，完整呈现首页、分类页、购物车、商品详情等典型模块，附带.ds_store占位文件说明其源自Mac系统开发环境，便于理解真实项目上下文。

1. 这不是个“点餐小程序”，而是一套可复用的生鲜履约中台前端骨架：从商品浏览、库存锁单、地址智能补全到订单状态机驱动的完整闭环

你打开一个叫“我厨”的微信小程序，加购三盒有机菠菜、两份冷鲜牛腩、一包海盐——页面没卡顿，库存实时变灰，地址栏自动弹出小区名，下单后状态立刻变成“已接单”，30秒后跳转到“骑手已取货”。你以为这是后台在狂刷接口？其实90%的业务逻辑和状态流转，都压在这个前端项目里。weixin_wochu-微信小程序我厨.zip就是当年某生鲜平台早期MVP阶段沉淀下来的微信小程序源码包，它没用云开发、没上Taro或uni-app，纯原生小程序架构，但把「生鲜场景下高并发读写+弱网容错+状态强一致性」这些黑匣子问题，用一套轻量却扎实的前端状态管理+服务层抽象+本地缓存策略给兜住了。它适合两类人：一是想快速搭建同城生鲜/社区团购类小程序的开发者，直接拿核心模块（比如库存预占组件、多级地址选择器、订单状态图谱）改接口就能嵌入；二是想搞懂“小程序怎么扛住每秒200+并发加购请求”的中高级前端，它的store/order.js和utils/lock.js是教科书级的实战注释。别被名字骗了——这不是教学Demo，是跑过真实日均5万单的生产级代码。

2. 项目结构与技术栈解剖：为什么选原生小程序而非跨端框架？

这个项目诞生于2020年Q3，当时团队要4周内上线最小可行版，技术选型非常务实：不碰新框架、不造轮子、不依赖云函数做核心逻辑。所有决策都指向一个目标——让加购、锁库存、提交订单这三步，在3G网络下也能稳定完成。我们先看目录结构，再拆技术选型背后的血泪经验。

2.1 目录结构：6个核心目录撑起整个履约链路

项目解压后共127个文件，主目录结构如下（删减了无关静态资源）：

├── app.js # 全局App实例，初始化用户登录态、全局配置、错误监控 ├── app.json # 页面路由、窗口样式、tabBar配置（含“首页”“分类”“购物车”“我的”4个tab） ├── project.config.json # 开发者工具配置（基础库版本2.24.2，强制要求） ├── utils/ │ ├── api.js # 封装wx.request，统一处理token刷新、错误重试（3次）、loading遮罩 │ ├── lock.js # 核心！库存预占锁逻辑：本地内存锁 + 服务端乐观锁双校验 │ ├── storage.js # 增强版wx.setStorageSync：支持过期时间、JSON自动序列化、异常降级为内存缓存 │ └── validate.js # 地址/手机号/支付密码等表单校验规则集合 ├── store/ │ ├── index.js # 全局Store入口，基于发布订阅实现，非Redux式复杂度 │ ├── cart.js # 购物车状态管理：add/remove/update，含本地持久化同步逻辑 │ ├── order.js # 订单状态机核心：定义INIT→LOCKED→PAID→DELIVERING→COMPLETED等8个状态及合法转移 │ └── user.js # 用户信息缓存与更新，含头像裁剪后上传逻辑 ├── pages/ │ ├── index/ # 首页：商品瀑布流 + 搜索框 + 分类导航（含滚动吸顶） │ ├── category/ # 分类页：左滑菜单 + 右侧商品列表（虚拟滚动优化长列表） │ ├── cart/ # 购物车页：多选结算 + 库存实时校验 + “去结算”按钮防抖 │ ├── order/ # 订单页：地址选择器（三级联动+模糊搜索）、优惠券选择、支付方式 │ └── my/ # 我的页：订单状态卡片（按status分组）、收货地址管理、客服入口 ├── components/ │ ├── goods-item/ # 商品卡片组件：含“加入购物车”按钮、库存状态提示、售罄浮层 │ ├── address-picker/ # 地址选择器：调用腾讯地图SDK逆地理编码 + 本地缓存常用地址 │ └── status-badge/ # 订单状态徽章组件：根据order.status动态渲染颜色和文案 └── project.config.json

提示：store/order.js是整个项目最值得细读的文件——它用纯对象描述状态转移规则，没有引入任何状态机库，却实现了比xstate更轻量的状态合法性校验。后面会逐行拆解。

2.2 技术栈选择：为什么坚持原生？三个硬约束逼出来的决定

常见做法是：当团队有3人以上且长期维护时，才考虑Taro；而本项目是单人主导+2周上线，原生就是最优解。我一般会先跑通pages/cart/index.js里的加购流程，确认cart.add()能正确触发storage.set和store.cart.notify()，再扩展其他页面——这是验证架构是否落地的第一块试金石。

2.3 关键依赖与版本锁定：基础库2.24.2是玄学安全线

项目project.config.json中明确指定：

{ "miniprogramRoot": "./", "compileType": "miniprogram", "libVersion": "2.24.2", "appid": "wx1234567890abcdef", "projectname": "我厨小程序" }

为什么是2.24.2？因为这是微信官方修复wx.getStorageInfoSync在iOS 15.4上返回空对象的最后一个稳定版本（后续2.25.x又引入了新的wx.chooseAddress兼容性问题）。如果你强行升级到2.28.0，components/address-picker/index.js中的地址缓存将失效——用户每次进订单页都要重新选小区。我在某次灰度发布中翻过这个车：把libVersion改成2.27.0后，30%的iOS用户地址栏空白，回滚后立刻恢复。所以现在我的习惯是：project.config.json里的libVersion必须和miniprogram_npm/@wechat-miniprogram/下实际安装的npm包版本严格一致，CI流程里加了一行校验脚本：

# CI校验脚本片段 MINI_LIB_VERSION=$(jq -r '.libVersion' project.config.json) NPM_LIB_VERSION=$(jq -r '."@wechat-miniprogram/core".version' miniprogram_npm/package.json 2>/dev/null || echo "") if [ "$MINI_LIB_VERSION" != "$NPM_LIB_VERSION" ]; then echo "❌ 基础库版本不一致：config=$MINI_LIB_VERSION, npm=$NPM_LIB_VERSION" exit 1 fi

3. 核心模块代码逐行解析：从库存预占到订单状态机

现在我们进入最硬核的部分——把utils/lock.js和store/order.js这两块“心脏代码”掰开揉碎。它们不是炫技，而是解决生鲜电商最痛的两个点：“别人抢光了我才点加购”和“付款成功但状态卡在‘待支付’”。代码不多，但每行都有明确意图。

3.1 库存预占锁：utils/lock.js—— 本地内存锁 + 服务端乐观锁的双重保险

// utils/lock.js const LOCK_MAP = new Map(); // 内存锁：key为goods_id，value为{timestamp, lockedBy} /** * 尝试获取商品锁 * @param {string} goodsId - 商品ID * @param {number} quantity - 请求数量 * @returns {Promise<{success: boolean, message: string}>} */ export function tryLock(goodsId, quantity) { return new Promise((resolve) => { const now = Date.now(); // Step 1: 检查本地内存锁（防重复点击） if (LOCK_MAP.has(goodsId)) { const lock = LOCK_MAP.get(goodsId); if (now - lock.timestamp < 5000) { // 5秒内只允许一次锁请求 return resolve({ success: false, message: '操作太频繁，请稍后再试' }); } } // Step 2: 调用服务端锁接口（带版本号校验） wx.request({ url: 'https://api.wochu.com/v1/goods/lock', method: 'POST', data: { goods_id: goodsId, quantity }, header: { 'Authorization': getApp().globalData.token }, success: (res) => { if (res.data.code === 0) { // Step 3: 服务端锁成功，写入本地内存锁 LOCK_MAP.set(goodsId, { timestamp: now, lockedBy: res.data.lock_id }); resolve({ success: true, message: '库存已锁定' }); } else if (res.data.code === 1001) { // 库存不足 resolve({ success: false, message: '库存不足，请减少数量' }); } else { resolve({ success: false, message: '锁定失败，请重试' }); } }, fail: () => { // Step 4: 网络失败，降级为本地锁（仅限本次会话） LOCK_MAP.set(goodsId, { timestamp: now, lockedBy: 'local_fallback' }); resolve({ success: true, message: '网络不稳定，已为您临时锁定' }); } }); }); } /** * 释放商品锁（下单成功或取消时调用） * @param {string} goodsId */ export function releaseLock(goodsId) { LOCK_MAP.delete(goodsId); }

逻辑说明与参数说明：

• LOCK_MAP是纯内存Map，不依赖wx.setStorageSync，避免IO阻塞主线程。它的生命周期=小程序进程存活期，关掉小程序自动清空。
• tryLock的quantity参数必须传入具体数字（如3），不能传字符串，否则服务端校验会失败——这是某次测试环境翻车原因：前端传了"3"，后端用===判断类型，直接返回code=1002。
• fail回调里的降级逻辑是关键：当网络超时，前端主动标记“已锁定”，但此时服务端并未真正锁库。所以pages/cart/index.js中必须配合cart.add()的幂等性设计——加购时检查本地锁状态，若存在则跳过服务端请求，直接更新UI。
• releaseLock必须在订单创建成功后调用，否则同一商品无法被再次加购。我在pages/order/submit.js的onSuccess回调里加了lock.releaseLock(goodsId)，但漏写了循环释放多个商品，导致用户第二次加购时卡在“操作太频繁”——这就是为什么代码后必须跟排查步骤。

3.2 订单状态机：store/order.js—— 用对象字面量定义状态转移规则

// store/order.js const ORDER_STATUS = { INIT: 'init', // 初始态：刚进入订单页 LOCKED: 'locked', // 库存已锁：调用tryLock成功后 PAID: 'paid', // 已支付：微信支付回调后 DELIVERING: 'delivering', // 配送中：后台发货后推送 COMPLETED: 'completed', // 已完成：用户确认收货 CANCELLED: 'cancelled', // 已取消：用户主动取消或超时 }; // 状态转移规则：key为当前状态，value为允许转移到的状态数组 const STATUS_TRANSITIONS = { [ORDER_STATUS.INIT]: [ORDER_STATUS.LOCKED, ORDER_STATUS.CANCELLED], [ORDER_STATUS.LOCKED]: [ORDER_STATUS.PAID, ORDER_STATUS.CANCELLED], [ORDER_STATUS.PAID]: [ORDER_STATUS.DELIVERING, ORDER_STATUS.CANCELLED], [ORDER_STATUS.DELIVERING]: [ORDER_STATUS.COMPLETED, ORDER_STATUS.CANCELLED], [ORDER_STATUS.COMPLETED]: [], [ORDER_STATUS.CANCELLED]: [], }; class OrderStore { constructor() { this.state = ORDER_STATUS.INIT; this.data = {}; // 存储订单详情、地址、商品列表等 } /** * 尝试切换状态 * @param {string} targetStatus - 目标状态 * @returns {boolean} 是否成功 */ transitionTo(targetStatus) { if (!STATUS_TRANSITIONS[this.state]) return false; const allowed = STATUS_TRANSITIONS[this.state]; if (!allowed.includes(targetStatus)) { console.warn(`非法状态转移：${this.state} → ${targetStatus}`); return false; } // 执行状态变更前的副作用（如埋点、通知UI） this._onStatusChange(this.state, targetStatus); this.state = targetStatus; return true; } _onStatusChange(from, to) { // 发送埋点事件 wx.reportAnalytics('order_status_change', { from, to }); // 通知所有监听者（如pages/order/index.js） this.listeners.forEach(cb => cb(to)); } // 省略addListener/removeListener等方法... } export default new OrderStore();

逻辑说明与参数说明：

• STATUS_TRANSITIONS是纯配置对象，不包含业务逻辑。所有“支付成功后必须进入DELIVERING态”这类规则，都在这里声明，而不是散落在onPaymentSuccess里——这是保证状态一致性的第一道防线。
• transitionTo方法返回布尔值，必须被调用方显式处理失败情况。例如在pages/order/submit.js中：

  // 支付成功回调 onPaymentSuccess() { if (!orderStore.transitionTo(ORDER_STATUS.PAID)) { // 失败则弹窗并跳转到错误页 wx.showToast({ title: '状态异常，请联系客服', icon: 'none' }); wx.navigateTo({ url: '/pages/error/status' }); return; } // 继续后续逻辑... }

• ORDER_STATUS.CANCELLED的转移路径被设计为“万能终点”：从任意状态都可取消。但注意，COMPLETED态不可逆——这是业务强约束，代码里[ORDER_STATUS.COMPLETED]: []直接禁止了所有转移，比if-else判断更可靠。

4. 运行与调试：从零启动到真机联调的完整链路

拿到zip包后，别急着npm install——这个项目没有npm依赖，所有逻辑都在miniprogram/目录下。真正的难点在于环境变量注入、接口代理和真机调试的弱网模拟。下面是我实测有效的四步走方案。

4.1 环境配置：用app.js动态注入API BaseURL

项目没有.env文件，所有环境配置藏在app.js的onLaunch里：

// app.js App({ onLaunch() { // 根据微信开发者工具的“自定义编译模式”切换域名 const env = wx.getSystemInfoSync().platform; let API_BASE_URL; if (env === 'devtools') { // 开发者工具：走本地代理 API_BASE_URL = 'http://localhost:3000'; } else if (env === 'ios') { // iOS真机：走测试环境 API_BASE_URL = 'https://test-api.wochu.com'; } else { // 安卓真机：走预发布环境 API_BASE_URL = 'https://pre-api.wochu.com'; } this.globalData = { API_BASE_URL }; } });

操作步骤：

1. 打开微信开发者工具，点击右上角“编译模式” → “新建编译模式”
2. 模式名称填local-dev，启动页面选pages/index/index，勾选“传递参数”并填?debug=true
3. 在app.js的onLaunch里加一行console.log('API_BASE_URL:', this.globalData.API_BASE_URL)，确保控制台输出http://localhost:3000
4. 启动本地代理服务（推荐用http-proxy-middleware）：

   // proxy.js const express = require('express'); const { createProxyMiddleware } = require('http-proxy-middleware'); const app = express(); app.use('/v1', createProxyMiddleware({ target: 'https://mock-api.wochu.com', // 替换为你的Mock服务 changeOrigin: true, logLevel: 'debug' })); app.listen(3000);

   运行node proxy.js，再启动小程序，所有/v1/xxx请求都会被代理到Mock服务。

4.2 接口Mock：用miniprogram_npm/mockjs生成真实感数据

项目已内置mockjs（位于miniprogram_npm/mockjs/），但需要手动启用。在app.js顶部加：

// app.js import Mock from 'mockjs'; // 仅在开发环境启用Mock if (wx.getSystemInfoSync().platform === 'devtools') { Mock.setup({ timeout: '200-600' }); // 模拟商品列表 Mock.mock('https://mock-api.wochu.com/v1/goods/list', 'get', { code: 0, data: Mock.mock({ 'list|20': [{ 'id|+1': 1, 'name': '@ctitle(8,15)', 'price|10-99.99': 1, 'stock|0-100': 1, 'image': 'https://via.placeholder.com/300x300?text=@natural' }] }) }); }

这样pages/index/index.js调用wx.request({url: '/v1/goods/list'})时，会自动返回20条随机商品数据，无需启动后端。

4.3 真机调试：三招搞定弱网与定位失败

真机调试时最常遇到两个问题：地图定位失败和加购超时。解决方案不是改代码，而是调用微信开发者工具的隐藏能力：

1. 模拟弱网：

   • 在开发者工具顶部菜单栏 → “项目” → “真机调试” → “网络” → 选择“Slow 3G”
   • 注意：此设置只对真机生效，开发者工具模拟器无效

2. 强制定位到指定坐标（绕过腾讯地图SDK限制）：

   • 在components/address-picker/index.js的chooseLocation方法里，加一段调试开关：

     // 开发时注释掉真实调用，启用模拟 if (process.env.NODE_ENV === 'development') { this.setData({ address: { name: 'XX小区3栋', latitude: 31.2304, longitude: 121.4737 } }); return; } // 正常调用 wx.chooseLocation(...)

3. 查看真机Console日志：

   • 微信开发者工具 → “调试器” → “Console” → 勾选“显示远程设备日志”
   • 真机上操作，日志实时同步，比wx.showModal弹窗调试高效10倍

注意：utils/storage.js在真机上会因wx.getStorageInfoSync返回空对象而降级为内存缓存，这是iOS 15.4的已知Bug。解决方案已在2.3节说明——锁定基础库版本为2.24.2。

5. 常见问题排查：5条血泪经验总结，每条都踩过坑

开发过程中最耗时间的往往不是写代码，而是定位那些“看起来没问题”的诡异问题。以下是我在本地跑通、真机联调、灰度发布三个阶段踩过的5个典型坑，按“现象→原因→解决”结构整理，全是实打实的后悔药。

5.1 现象：首页商品列表滚动卡顿，FPS掉到10以下

原因：pages/index/index.wxml中<scroll-view>未设置enhanced属性，且内部<view wx:for>未使用wx:key，导致微信引擎频繁重建DOM节点。
解决：

• 在scroll-view标签上添加enhanced="{{true}}"（微信基础库2.24.2+支持）
• wx:for循环中必须指定wx:key="id"，且id字段需在数据中真实存在（不能是index）
• 额外优化：商品卡片components/goods-item/index.wxml中，图片<image>标签加上mode="aspectFill"和lazy-load="{{true}}"

5.2 现象：安卓真机上“去结算”按钮点击无响应，控制台无报错

原因：pages/cart/index.js中bindtap="onSubmit"事件绑定在<button>上，但该<button>的open-type属性被误设为"getUserInfo"（旧版授权遗留），导致微信拦截了点击事件。
解决：

• 检查pages/cart/index.wxml中所有<button>，删除open-type属性（结算按钮不需要开放能力）
• 或显式设为open-type="default"
• 补充防御：在onSubmit方法开头加console.log('onSubmit triggered')，确认事件是否触发

5.3 现象：iOS真机上地址选择器空白，控制台报fail system error

原因：腾讯地图SDK密钥未在project.config.json中配置，且components/address-picker/index.js未做密钥存在性校验。
解决：

• 登录腾讯位置服务控制台，创建小程序密钥，填入project.config.json的"mpmap": { "key": "YOUR_KEY" }字段
• 在address-picker组件onLoad中加校验：

  onLoad() { if (!wx.configMapKey) { console.error('腾讯地图密钥未配置'); this.setData({ addressList: [] }); // 降级为空列表 return; } }

5.4 现象：购物车数量修改后，wx.setStorageSync报错fail the data is too large to setStorage

原因：store/cart.js中cart.update()方法未对商品数据做精简，把完整的商品对象（含HTML描述、大图URL）存入了本地存储。
解决：

• 修改cart.update()，只存必要字段：

  const simplifiedItem = { id: item.id, name: item.name, price: item.price, quantity: item.quantity, image: item.image // 仅存缩略图URL };

• 在utils/storage.js的set方法中加大小校验：

  const size = JSON.stringify(value).length; if (size > 1024 * 100) { // 超过100KB console.warn('Storage value too large, truncated'); value = { warning: 'data_truncated', size }; }

5.5 现象：支付成功后订单状态卡在PAID，不自动跳转到DELIVERING

原因：store/order.js的transitionTo方法被调用，但_onStatusChange中的listeners为空，因为pages/order/index.js未正确注册监听器。
解决：

• 检查pages/order/index.js的onLoad：

  onLoad() { // ✅ 正确：在setData前注册 orderStore.addListener(this.onOrderStatusChange); this.setData({ /* ... */ }); } // ❌ 错误：在setData后注册，导致首次状态变更丢失

• 补充：在onUnload中必须removeListener，否则内存泄漏

6. 二次开发改造指南：如何把“我厨”变成你的社区团购小程序

现在你已经跑通了项目，也踩过了坑。下一步不是“接着写”，而是“有策略地改”——把这套经过验证的履约骨架，适配到你的业务场景。我以“某社区团购小程序”为例，给出三条可立即落地的改造路径，每条都附带验证方法和避坑点。

6.1 改造路径一：替换商品域模型，接入自有SKU体系

“我厨”的商品结构是生鲜专用（含shelf_life保质期、packing_type包装方式），而社区团购更关注group_id拼团ID、limit_per_user限购数。你需要修改三个地方：

1. 数据层：在utils/api.js中新增/v1/group/goods/list接口，返回带拼团信息的商品列表
2. 视图层：修改components/goods-item/index.wxml，增加拼团徽章：

   <view wx:if="{{item.group_id}}" class="badge-group"> {{item.limit_per_user}}人成团 </view>

3. 状态层：在store/cart.js的add()方法中，校验item.group_id是否存在，若存在则检查用户是否已参团（调用/v1/group/user/joined）

验证方法：

• 启动Mock服务，返回group_id: "g123"的商品
• 在首页点击该商品，进入详情页，确认显示“2人成团”徽章
• 加购2件，观察购物车中该商品quantity是否被限制为2（limit_per_user值）

注意：limit_per_user是服务端校验，前端只是展示和初步拦截。真正的限购逻辑必须在/v1/cart/add接口中实现，否则恶意用户可绕过。

6.2 改造路径二：订单状态机扩展，增加“拼团中”和“拼团失败”态

社区团购的核心状态是“拼团中”，它必须能从LOCKED态转入，且超时后自动转为CANCELLED。修改store/order.js：

// 新增状态 const ORDER_STATUS = { // ...原有状态 GROUPING: 'grouping', // 拼团中：用户已支付，等待其他人参团 GROUP_FAILED: 'group_failed', // 拼团失败：超时无人参团 }; // 更新状态转移规则 const STATUS_TRANSITIONS = { // ...原有规则 [ORDER_STATUS.PAID]: [ORDER_STATUS.GROUPING, ORDER_STATUS.CANCELLED], [ORDER_STATUS.GROUPING]: [ORDER_STATUS.COMPLETED, ORDER_STATUS.GROUP_FAILED, ORDER_STATUS.CANCELLED], [ORDER_STATUS.GROUP_FAILED]: [ORDER_STATUS.CANCELLED], };

关键动作：

• 在onPaymentSuccess中，若商品含group_id，则调用orderStore.transitionTo(ORDER_STATUS.GROUPING)
• 后端需提供/v1/group/status?order_id=xxx接口，前端轮询（间隔5秒，最多12次）
• GROUP_FAILED态需触发退款逻辑，调用/v1/refund?order_id=xxx

验证方法：

• Mock接口返回status: 'grouping'，观察订单页徽章变为“拼团中”
• 手动修改Mock返回status: 'group_failed'，确认状态变为“拼团失败”并弹窗提示退款

6.3 改造路径三：地址选择器升级，支持“自提点”模式

社区团购用户常选“小区自提点”而非家庭地址。你需要改造components/address-picker/：

1. UI层：在地址列表上方增加Tab切换：

   <view class="tabs"> <view bindtap="switchMode">switchMode(e) { const mode = e.currentTarget.dataset.mode; if (mode === 'pickup') { this.loadPickupPoints(); // 调用 /v1/pickup/list } else { this.loadUserAddresses(); // 调用 /v1/address/list } }

2. 存储层：utils/storage.js中，为自提点数据单独命名空间：

   setPickupPoints(points) { wx.setStorageSync('pickup_points', { data: points, timestamp: Date.now() }); }

验证方法：

• 点击“自提点”Tab，确认列表加载出Mock的5个自提点
• 选择一个自提点，提交订单，检查pages/order/submit.js中this.data.address是否包含pickup_id字段

从那以后我每次接手类似项目，都强制走一遍“状态机校验→锁逻辑压测→真机弱网测试”三步流程。不是为了炫技，而是因为weixin_wochu-微信小程序我厨.zip教会我：生鲜电商的前端，从来不是UI的堆砌，而是对“确定性”的偏执追求——每一行代码，都在对抗网络的不确定性、用户的不确定性、库存的不确定性。希望帮到你。

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