小程序商城 (shop-taro)
基于 Taro + React + TypeScript 的微信小程序商城系统，支持多门店、VIP 会员、拼团秒杀、积分商城、分销裂变等完整电商业务场景。
作者: 科技小王子
版本: 1.0.0
License: MIT
技术栈
| 分类 | 技术 | 版本 | 说明 |
|---|---|---|---|
| 跨端框架 | Taro | 4.1.11 | 支持微信/H5/支付宝等多端编译 |
| UI 框架 | React | 18.3.1 | 函数组件 + Hooks |
| 类型系统 | TypeScript | 5.7.2 | 严格模式 |
| 组件库 | NutUI React Taro | 2.7.4 | 京东风格组件库 |
| 原子化 CSS | TailwindCSS | 3.4.17 | 含 weapp-tailwindcss 适配 |
| CSS 预处理 | Sass | ^1.81.0 | |
| 日期处理 | Day.js | ^1.11.13 | |
| 加密 | Crypto-js | ^4.2.0 | AES / MD5 |
| 图表 | ECharts Taro3 React | ^1.0.13 | 数据可视化 |
| 二维码 | weapp-qrcode | ^1.0.0 | 小程序码生成 |
Node 版本要求: >= 18
核心业务功能
商城交易
- 商品浏览 / 搜索 / 分类筛选
- 商品详情 + 多规格 SKU 选择
- 购物车（合并加购、批量操作）
- 下单结算（普通订单 / 拼团 / 秒杀）
- 订单管理（待付款 / 待发货 / 待收货 / 已完成）
- 售后退款申请与进度跟踪
- 发票申请与抬头管理
会员体系
- 手机号授权登录（微信一键 + 短信验证码降级）
- VIP 会员申请与审核（门店店员审核）
- VIP 专享价（dealerPrice）
- 会员权益包兑换
- 积分系统（签到 / 积分商品兑换 / 积分明细）
- 用户余额（充值 / 消费 / 提现）
分销与裂变
- 邀请下级注册
- 分销佣金记录
- 分享海报（Canvas 绘制 + 小程序码）
- 朋友圈分享 / 复制链接
- 邀请归因追踪
门店管理（店员端）
- 门店中心（订单 / 商品 / 用户管理）
- VIP 审核（通过 / 驳回）
- 订单修改金额与备注
- 上传发货凭证
- 门店会员管理（搜索 / 筛选 / 禁用启用）
营销活动
- 拼团（单独成团 / 参团）
- 秒杀（限时抢购）
- 优惠券（领取中心 / 下单核销）
- 赛事报名
- 预约订单
- 礼品卡（购买 / 兑换 / 余额查询）
- 文章资讯 / 公告通知
其他
- 浏览历史记录（服务端去重累加）
- 商品收藏
- 客服会话
- 数据统计看板（销售 / 用户）
- 微信隐私协议授权弹窗
- 订阅消息推送（新订单提醒）
快速开始
安装依赖
pnpm install
开发模式
# 微信小程序（主要目标平台）
pnpm dev:weapp
# H5
pnpm dev:h5
生产构建
pnpm build:weapp
pnpm build:h5
代码检查
# ESLint 修复
pnpm lint
# TypeScript 类型检查
pnpm type-check
构建产物在
dist/目录，使用微信开发者工具打开该目录进行预览和调试。
项目结构
shop-taro/
├── config/ # Taro 编译配置
│ ├── index.ts # 主配置
│ ├── dev.ts # 开发环境
│ └── prod.ts # 生产环境
├── src/
│ ├── app.tsx # 应用入口
│ ├── app.config.ts # 路由 / tabBar / 全局配置
│ ├── app.scss # 全局样式
│ ├── pages/ # 页面目录
│ │ ├── index/ # 首页（tabBar）
│ │ ├── shop/ # 商城（分类/详情/购物车/结算/拼团/秒杀）
│ │ ├── user/ # 用户中心（tabBar）
│ │ ├── points/ # 积分商城
│ │ ├── order/ # 订单管理
│ │ ├── store/ # 门店管理（店员端）
│ │ ├── after-sale/ # 售后退款
│ │ ├── activity/ # 营销活动
│ │ ├── event/ # 赛事报名
│ │ ├── booking/ # 预约订单
│ │ ├── message/ # 消息通知
│ │ ├── gift-card/ # 礼品卡
│ │ ├── invoice/ # 发票
│ │ ├── share/ # 分享返利
│ │ ├── rebate/ # 返利记录
│ │ └── statistics/ # 数据统计
│ ├── passport/ # 登录/注册/短信登录/扫码登录
│ ├── components/ # 公共组件
│ │ ├── business/ # 业务组件
│ │ ├── common/ # 通用组件
│ │ ├── layout/ # 布局组件
│ │ ├── NavBar/ # 导航栏
│ │ ├── SharePoster/ # 分享海报
│ │ ├── PrivacyModal/ # 隐私协议弹窗
│ │ └── ErrorBoundary.tsx # 错误边界
│ ├── contexts/ # 全局状态 Context
│ │ ├── AppContext.tsx # 应用上下文
│ │ ├── UserContext.tsx # 用户信息
│ │ └── CartContext.tsx # 购物车
│ ├── hooks/ # 自定义 Hooks
│ │ ├── useUser.ts # 用户信息
│ │ ├── useVipStatus.ts # VIP 状态（响应式）
│ │ ├── useShare.ts # 分享/朋友圈/复制链接
│ │ ├── usePayment.ts # 支付
│ │ ├── useAddress.ts # 收货地址
│ │ ├── useNewOrderDetector.ts # 新订单轮询检测
│ │ ├── useCountDown.ts # 倒计时
│ │ ├── usePagination.ts # 分页
│ │ ├── useRequest.ts # 请求封装
│ │ └── ...
│ ├── api/ # 后端接口封装
│ │ ├── shop/ # 商城业务接口（50+ 模块）
│ │ ├── system/ # 系统接口（文件上传等）
│ │ ├── passport/ # 认证接口
│ │ ├── cms/ # 内容管理
│ │ └── share.ts # 分享相关
│ ├── utils/ # 工具函数
│ │ ├── request.ts # 网络请求封装
│ │ ├── auth.ts # 用户禁用拦截
│ │ ├── vip.ts # VIP 状态判断
│ │ ├── privacy.ts # 隐私授权管理
│ │ ├── invite.ts # 邀请参数解析
│ │ ├── server.ts # 服务器地址
│ │ ├── image.ts # 图片处理
│ │ ├── geofence.ts # 地理围栏
│ │ └── common.ts # 通用工具
│ ├── types/ # TypeScript 类型定义
│ ├── styles/ # 全局样式
│ └── assets/ # 静态资源（tabBar 图标等）
├── package.json
├── tsconfig.json
├── tailwind.config.js
├── postcss.config.js
├── project.config.json # 小程序项目配置
└── README.md
tabBar 配置
| Tab | 页面路径 | 图标 | 说明 |
|---|---|---|---|
| 首页 | pages/index/index |
home | 商城首页、Banner、快捷入口 |
| 分类 | pages/shop/index |
category | 商品分类与列表 |
| 购物车 | pages/shop/cart |
cart | 购物车管理 |
| 我的 | pages/user/user |
user | 个人中心 |
关键技术实现
VIP 会员价格体系
商品价格字段约定：
| 字段 | 含义 |
|---|---|
product.price |
到手价（主价格） |
product.salePrice |
市场价（划线价） |
product.dealerPrice |
VIP 会员专享价 |
product.memberStorePrice |
会员价 |
- 使用
useVipStatusHook 实现响应式 VIP 状态更新 - VIP 状态通过异步校验缓存，组件挂载时自动刷新
微信隐私协议（基础库 3.16.1+）
- 调用
chooseImage/getPhoneNumber等敏感 API 前预检授权 app.tsx注册onNeedPrivacyAuthorization回调PrivacyModal组件展示授权弹窗
手机号登录降级方案
- 微信
getPhoneNumber被拒绝后自动降级到短信验证码登录 - 统一错误处理弹窗，引导跳转短信登录页
分享裂变
useShareHook 一次注册useShareAppMessage+useShareTimeline- 分享链接自动追加
inviter参数做归因 SharePoster组件用 Canvas 2D 绘制海报 + 小程序码
用户禁用机制
User.status字段：0正常 /1禁用- 多层级拦截：UserContext 启动校验 + 登录检查 + 页面入口检查
代码示例
使用 NutUI 组件
import { Button, Cell, CellGroup } from '@nutui/nutui-react-taro'
export default function MyPage() {
return (
<CellGroup>
<Cell title="标题" description="描述" />
<Button type="primary" block>提交</Button>
</CellGroup>
)
}
使用 TailwindCSS
<View className="p-4 bg-white">
<Text className="text-lg font-bold text-gray-800">商品名称</Text>
</View>
使用 VIP 状态 Hook
import { useVipStatus } from '@/hooks/useVipStatus'
export default function ProductCard({ product }) {
const { isVip } = useVipStatus()
const displayPrice = isVip ? product.dealerPrice : product.price
return <Text className="text-red-500">¥{displayPrice}</Text>
}
使用分享 Hook
import { useShare } from '@/hooks/useShare'
export default function ProductDetail({ product }) {
useShare({
title: product.name,
path: '/pages/shop/product-detail',
query: { id: product.id },
enableTimeline: true,
enableCopyUrl: true,
})
// ...
}
网络请求
import { getShopOrderList } from '@/api/shop/shopOrder'
const { data } = await getShopOrderList({ status: 'pending', page: 1 })
开发规范
文件命名
- 页面目录：
kebab-case（如product-detail/） - 组件文件：
PascalCase（如ProductCard.tsx） - 工具文件：
camelCase（如formatDate.ts）
代码风格
- 2 空格缩进
- 单引号优先
- 分号结尾
- ESLint + @typescript-eslint 检查
提交规范
feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具配置
常见问题
TailwindCSS 样式在小程序中不生效？
检查 postcss.config.js 和 tailwind.config.js 配置，确保已安装 weapp-tailwindcss 并正确配置 content 路径。
NutUI 组件样式丢失？
确保在 app.scss 中引入了 NutUI 样式文件。
TypeScript 路径别名 @/* 报错？
检查 tsconfig.json 的 paths 配置，并确保 IDE（VS Code）正确识别。
隐私协议报错 errno:112？
小程序后台需配置用户隐私保护指引，声明相册/摄像头/手机号等权限。