一句话定位：这不是一套能独立跑起来的商城，而是芋道商城的移动端前端——uni-app + Vue3 写的 H5 / 微信小程序 / 公众号壳子，后端必须配芋道的 Java 开发平台（ruoyi-vue-pro 或 yudao-cloud）才有商品、订单和支付。拿来改 UI 很快，想「下载即开店」会失望。
| 项 | 值 |
|---|---|
| 仓库地址 | https://gitee.com/yudaocode/yudao-mall-uniapp （GitHub 镜像：github.com/yudaocode/yudao-mall-uniapp） |
| 项目定位 | 芋道商城「用户端」前端（移动端），不含后端与管理后台 |
| 官方文档 | https://doc.iocoder.cn （商城手册：doc.iocoder.cn/mall/build/） |
| 在线演示 | https://doc.iocoder.cn/mall-preview/ |
| 开源协议 | MIT（仓库 LICENSE 与 Gitee 项目信息一致） |
| 技术栈 | uni-app + Vue 3（vue ^3.5.11）+ Vite + Pinia + luch-request + SCSS |
| 当前版本 | 2026.10（package.json version 与 manifest versionName 一致，versionCode 183） |
| 支持端 | 微信小程序、微信公众号（H5）、H5 移动端；README 称后续支持支付宝/抖音小程序 |
| 社区热度 | Gitee 21.7K Star / 3.4K Fork / 220 Watch / 2 个开放 Issue（2026-11-10 查询） |
| 维护方 | 芋道源码（作者艿艿 / YunaiV），仓库创建于 2023-04-24 |
| 文档日期 | 2026-11-10 |
1. 项目是什么
它是芋道商城的「前台」，不是商城本身。 一套代码编译出微信小程序、公众号内嵌 H5 和普通手机浏览器页面，负责商品浏览、下单、支付、售后、分销、拼团秒杀这些用户可见的流程；真正的业务逻辑、库存扣减、订单状态机、支付回调全在 Java 后端里。
官方文档把商城拆成三块，说得非常直白：
| 组成 | 仓库 | 说明 |
|---|---|---|
| 后端 | ruoyi-vue-pro（单体）/ yudao-cloud（微服务） | 商城功能在 yudao-module-mall 模块，默认关闭，要手动开 |
| 管理后台 | yudao-ui-admin-vue3 | 商品、订单、装修、营销活动的运营界面 |
| 用户前台 | 本仓库 | 手机端页面，接口走 /app-api 前缀 |
所以选型时第一个要回答的问题不是「这个前端好不好看」，而是「我有没有、或愿不愿意跑一套芋道后端」。答案是否，这个仓库对你的价值就只剩「抄页面结构和交互」。
它解决的问题很具体：
- 一套 Vue3 代码覆盖三端：小程序、公众号 H5、手机浏览器，不用为每端重写业务。
- 商城前台该有的页面都齐了：商品、购物车、下单、支付、售后、物流、优惠券、分销、拼团秒杀积分，分包结构清晰，省掉从零搭骨架的两三周。
- 和芋道后端的接口约定是现成的：请求封装、租户头、登录态、支付拉起都对着
yudao-module-mall调通了，换后端要重写这一层。
不适用：想找一个开箱即用的完整商城系统（去看 CRMEB、ShopXO、mall4j 这类前后端一体的）；团队不写 Java 也不想维护 Spring Boot；只想拿 H5 模板去接自己的 PHP 接口（接口协议、字段、错误码全要改）。
2. 核心特性
| 特性 | 说明 | 对使用者的价值 |
|---|---|---|
| 纯前端单仓库 | 只有 pages/ 和 sheep/ 两套代码，没有后端、没有 SQL | 交接成本低，读一遍目录就知道边界在哪 |
| 一套代码多端 | uni-app 条件编译 + 平台适配层，同一份页面出 H5 与微信小程序 | 改一次样式，三端同步 |
| 首页/我的可装修 | 首页与个人中心由后端「店铺装修」数据驱动，官方内置全品类、垂直品类、节日活动 3 套模板 | 换行业不用改代码，运营在后台拼页面 |
| 组件体系自带 | easycom 规则把 s-* 映射到 sheep/components、su-* 映射到 sheep/ui | 新增页面直接写 <s-goods-card>，不用逐个 import |
| 状态持久化 | Pinia + pinia-plugin-persist-uni，登录态、购物车、租户信息落地到本地存储 | 小程序冷启动不用重新拉一遍用户信息 |
| 请求层统一 | 基于 luch-request 封装，统一拼 SHOPRO_API_PATH、带 token、带租户号、统一错误提示 | 加接口只写 api 文件，不重复处理鉴权 |
| SaaS 多租户适配 | SHOPRO_TENANT_ID 兜底，sheep/store/app.js 的 #adaptTenant 按访问域名或小程序 appId 自动匹配租户 | 一套代码服务多个商户/品牌 |
| 营销能力齐全 | 优惠券、拼团、秒杀、积分商城、分销（佣金/团队/排行榜/提现）、签到、余额充值 | 中小电商常见玩法不用二次开发 |
| 客服与直播开关 | 内置 pages/chat 客服页；.env 的 SHOPRO_MPLIVE_ON 控制小程序直播 | 需要时打开，不需要不背包袱 |
| 提供 CLI 分支 | master-cli 是 vue-cli 工程结构，有完整 dev:* / build:* 脚本 | 想接 CI/CD、不想装 HBuilderX 时可用 |
3. 技术架构
整体结构：uni-app（Vue3 版本）单页应用，Vite 构建，pages.json 声明路由与分包，sheep/ 是自研的「框架层」，pages/ 是业务页面。没有 TypeScript、没有单元测试、没有 ESLint 流程，只有一个 Prettier 格式化脚本。
| 层 | 技术 | 说明 |
|---|---|---|
| 应用框架 | uni-app（Vue3） | manifest.json 中 vueVersion: "3"，main.js 走 createSSRApp |
| 构建 | Vite + HBuilderX | 仓库有 vite.config.js，但 master 的 package.json 没有 dev/build 脚本，日常靠 HBuilderX 运行 |
| 状态管理 | Pinia ^2.0.33 + pinia-plugin-persist-uni | sheep/store/ 下按模块拆分（app、user、cart、goods 等） |
| 网络 | luch-request ^3.0.8 | 封装在 sheep/request/，统一拦截器与错误码处理 |
| 路由 | uni-app 原生路由 + sheep/router/ | 支持 meta.auth 登录拦截、sync 标记 |
| UI | 自研组件 + SCSS 变量 | sheep/ui（基础控件）、sheep/components（业务组件）、sheep/scss |
| 工具 | dayjs、lodash / lodash-es | 时间格式化、数据处理 |
| 微信能力 | weixin-js-sdk ^1.6.0 | 公众号内 H5 的 JSSDK 能力（分享、支付等） |
| 后端接口 | 芋道 app-api | 开发默认 http://127.0.0.1:48080，接口前缀 /app-api，WebSocket 前缀 /infra/ws |
运行环境判定（sheep/config/index.js，逻辑值得一读）：
// 开发环境走 SHOPRO_DEV_BASE_URL
// 非开发环境再看微信环境版本：
// trial -> SHOPRO_TRIAL_BASE_URL
// release -> SHOPRO_BASE_URL
// 其他端 -> SHOPRO_BASE_URL也就是说，同一份代码在「开发版小程序 / 体验版 / 正式版」会自动切到不同后端地址，这是它比多数开源商城前端做得细的地方——但仍要你在 .env 里把三个地址都填对。
关键取舍：
- 选 uni-app 而不是原生小程序：多端成本最低，代价是要忍受 uni-app 的兼容坑和 HBuilderX 这层工具链。
- 前后端彻底分离：前端可以独立部署到 Nginx 或 CDN，但接口一改就要同步改
sheep/api，没有代码生成兜底。 - 组件层自己造（
sheep/ui），没有引入 uView/uni-ui 全量库：包体小、风格统一，但生态红利吃不到，新组件得自己写。
4. 目录结构
| 路径 | 用途 |
|---|---|
pages/ | 业务页面主体，按域分包：index、goods、order、user、commission、activity、coupon、pay、chat、app、public |
pages.json | 路由、分包、tabBar、全局样式、easycom 规则，加页面必须先改这里 |
sheep/api/ | 按后端模块划分的接口定义（商品、订单、支付、会员、促销等） |
sheep/components/ | 业务组件，s- 前缀 |
sheep/ui/ | 基础 UI 组件，su- 前缀 |
sheep/store/ | Pinia 状态模块，含多租户适配逻辑 |
sheep/request/ | 请求封装、拦截器、错误处理 |
sheep/platform/ | 各端差异封装（登录、支付、分享、位置） |
sheep/config/ | 环境配置出口，读 .env 与 package.json 版本号 |
sheep/router/ | 路由跳转封装与登录守卫 |
sheep/helper/、sheep/hooks/、sheep/libs/、sheep/url/、sheep/validate/ | 工具函数、组合式函数、第三方库封装、链接生成、校验规则 |
sheep/scss/ | 全局样式变量与 mixin |
static/ | 静态资源（logo、tabBar 图标、占位图） |
uni_modules/ | uni-app 插件目录，当前 package.json 声明为空依赖 |
.env | 环境配置核心：后端地址、静态资源地址、租户号、上传方式、H5 域名 |
manifest.json | 应用名称、appId、版本号、各端打包配置、Android 权限、微信 appId |
vite.config.js / main.js / App.vue / index.html | 构建入口与应用生命周期 |
androidPrivacy.json | Android 隐私政策弹窗配置，上架前必须按自己的隐私政策改 |
5. 快速上手
前置条件（顺序不能反）：先把后端跑起来，再跑前端。后端没起来，前端首页会是空的。
后端侧要做三件事（依据官方《商城手册 - 功能开启》）：
- 在
pom.xml与yudao-server/pom.xml里取消yudao-module-mall的注释，Reload Maven； - 导入商城的 SQL 脚本（官方文档给的下载地址有使用范围说明，见第 8 节）；
- 重启后端，确认管理后台出现商城菜单。支付、会员功能还需按《支付手册》《会员手册》单独开启。
前端侧（master 分支，HBuilderX 方式）：
# 1. 克隆
git clone https://gitee.com/yudaocode/yudao-mall-uniapp.git
cd yudao-mall-uniapp
# 2. 装依赖（官方文档给的就是这两条）
npm i
# 报错时再试
npm install --legacy-peer-deps- 打开 HBuilderX → 文件 → 导入 → 从本地项目导入，选中该目录；
- 改
.env，至少这三项：
# 后端接口（本地后端）
SHOPRO_DEV_BASE_URL=http://127.0.0.1:48080
# 静态资源（默认指向官方测试域名，必须换成自己的）
SHOPRO_STATIC_URL=https://你的静态资源域名
# H5 访问域名
SHOPRO_H5_URL=http://127.0.0.1:3000- HBuilderX → 运行 → 运行到浏览器 → Chrome。
跑微信小程序：在 manifest.json 的「微信小程序配置」里填自己的 AppID，HBuilderX → 运行 → 运行到小程序模拟器 → 微信开发者工具；并在微信开发者工具里勾选「不校验合法域名、web-view、TLS 版本以及 HTTPS 证书」，否则本地接口全是跨域报错。
想用命令行 / CI（master-cli 分支）：
git clone -b master-cli https://gitee.com/yudaocode/yudao-mall-uniapp.git
cd yudao-mall-uniapp
npm i
npm run dev:h5 # 启动 H5
npm run build:mp-weixin # 构建微信小程序注意 master-cli 的 package.json 版本是 2025.11，比 master 的 2026.10 旧一截，官方说法是「后续会合并到 master」。要用最新代码又想要 CLI，得自己把脚本和 @dcloudio/* 依赖搬过去。
H5 上线：HBuilderX 发行 → 网站-PC Web 或手机 H5，产物是纯静态文件，扔给 Nginx 即可。manifest.json 里 H5 路由是 history 模式，Nginx 必须配 fallback：
location / {
try_files $uri $uri/ /index.html;
}6. 功能模块清单
按 pages.json 的实际分包整理，这一节基本等于「这个前端到底做了哪些页面」：
| 分组 | 页面 | 说明 |
|---|---|---|
| 主包（tabBar） | 首页、商品分类、购物车、个人中心 | 首页与个人中心由店铺装修数据驱动 |
| 商品 | 商品详情、商品列表、拼团商品、秒杀商品、积分商品、商品评价、发表评价 | 详情页按营销类型分了三个入口 |
| 订单 | 确认订单、订单列表、订单详情、物流轨迹 | 常规交易链路 |
| 售后 | 申请售后、售后列表/详情/进度、退货物流 | 覆盖仅退款与退货退款 |
| 用户 | 我的信息、商品收藏、浏览足迹、收货地址、自提门店、我的余额、我的积分 | 自提门店单独成页，对应门店自提 |
| 分销 | 分销中心、我的佣金、推广商品、分销订单、我的团队、推广人排行榜、佣金排行榜、申请提现 | 分销体系相当完整 |
| 营销 | 营销商品、拼团活动/详情/我的拼团、秒杀活动、积分商城 | 活动页集中在 pages/activity |
| 优惠券 | 领券中心、优惠券详情 | — |
| 支付 | 收银台、支付结果、充值余额、充值记录 | 余额充值走独立流程 |
| 客服 | 客服会话 | 单页，接后端客服能力 |
| 应用 | 签到中心 | — |
| 公共 | 系统设置、富文本、常见问题、错误页、webview | 通用页，webview 用于外部链接 |
没看到的：README 的功能描述里有「砍价」，但 pages.json 里没有独立的砍价页面；移动端主流程的实际覆盖面以页面清单为准，砍价更多体现在管理端配置与后端能力上。
7. 版本与授权
| 项 | 值 |
|---|---|
| 协议 | MIT（可商用、可闭源二次开发，保留版权声明即可） |
| 当前版本 | 2026.10，versionCode 183 |
| 版本管理 | package.json 的 version 与 manifest.json 的 versionName 保持一致，sheep/config/index.js 直接读 package.json 打日志 |
| 主要分支 | master（Vue3 主线）、develop、master-cli（CLI 工程结构）、master-vue2（Vue2 老版本，已停更于 2023-12） |
| 迭代节奏 | 最近提交 2026-11-01（修复积分商城无效商品导致的分页异常），与后端版本同月对齐 |
| 发布物 | Gitee Releases 提供 zip / tar.gz 源码包，从 v1.8.2（2023-09）一路发到 2026.10 |
两个版本口径不一致，别混用：
.env里写着SHOPRO_VERSION=v2.4.1，这个值已经和package.json、manifest.json脱节，像是历史残留；- 判断版本请认
package.json/manifest.json/ Release tag，三处都是2026.10。
8. 商业模式说明
这个仓库本身没有商业版本。README 开头就是一句「现在、未来都不会有商业版本，所有代码全部开源」，代码也确实 MIT。
但「代码免费」不等于「配套资源全免费」。官方《商城手册》里，导入商城 SQL 的那一步写得很明确：脚本需从知识星球附件下载，并注明该 SQL 仅星球成员可使用和商用。也就是说：
- 前端页面、组件、接口封装：MIT，随便用；
- 商城数据库脚本、完整文档、视频教程：与知识星球会员绑定；
- 作者的变现路径是知识星球 + 企业定制/外包 + 课程，不是卖 License。
选型时把这条读清楚，能避免「代码是 MIT，为什么文档要付费」的预期落差；也提醒一句，数据库结构和初始化数据属于另一层授权，商用前建议自行确认。
9. 生态与周边
| 项目 | 作用 | 地址 |
|---|---|---|
ruoyi-vue-pro | Spring Boot 单体后端（master 为 JDK8，另有 master-jdk17、master-jdk25） | gitee.com/zhijiantianya/ruoyi-vue-pro |
yudao-cloud | Spring Cloud 微服务后端 | gitee.com/zhijiantianya/yudao-cloud |
yudao-ui-admin-vue3 | 管理后台（Vue3 + element-plus），商城运营都在这里 | gitee.com/yudaocode/yudao-ui-admin-vue3 |
yudao-ui-admin-uniapp | 移动端管理后台（另一套 uniapp，别和本仓库混淆） | gitee.com/yudaocode/yudao-ui-admin-uniapp |
yudao-demo | 演示站静态资源（商城图片素材在 yudao-static/mall/static） | gitee.com/yudaocode/yudao-demo |
| 官方文档 | 商城手册、支付手册、会员手册、部署手册（含宝塔部署一篇） | doc.iocoder.cn |
| 前身 | 页面与目录里的 sheep 前缀、shopro scheme 来自 SheepJS 的 shopro 模板 | — |
值得注意的传承关系：package.json 的 repository 仍指向 github.com/sheepjs/shop，homepage 指向 DCloud 的 hello-uniapp，manifest.json 里的 Universal Links 域名是 shopro.sheepjs.com。这套前端是在 SheepJS shopro 模板基础上重构而来，MIT 协议下这没问题，但这些元数据不能当作项目官网或主仓库。
10. 选型建议
适合你，如果：
- 已经（或计划）用芋道后端，需要一套现成的移动端前台，省掉三周搭架子；
- 团队是 Java 为主，前端只有 1–2 人，改改 UI 和活动页就能交付；
- 要做 SaaS 多租户电商，需要按域名/appId 自动切租户的能力；
- 需要一个「分包结构规范、组件分层清楚」的 uni-app 模板当起点。
不适合你，如果：
- 想要开箱即用的完整商城：没有后端、没有 SQL、没有运营后台，三样都得另配；
- 后端不是 Java 或不打算用芋道：
sheep/api全要重写，sheep/request的鉴权与租户逻辑也要改； - 需要 App 上架：仓库保留了 App 打包配置，但官方主推三端（小程序/公众号/H5），App 端缺少明确的维护承诺；
- 团队重度依赖 TypeScript 与自动化测试：这个仓库两样都没有。
和同类怎么比：CRMEB、ShopXO 是「前后端一体、装上就能卖货」；本项目是「前端零件 + 需要自己组装的后端」。前者省心但定制受限，后者灵活但要求你会 Java 那半边。如果只看移动端体验和组件规范，这个仓库的水平在同类的 uni-app 商城里属于上乘。
11. 风险与坑
- 把前端当成完整商城：最常见的误判。下载、
npm i、运行，看到的空首页不是 bug，是后端没起或没配装修数据。 - 商城 SQL 的使用范围：官方文档对脚本来源与商用范围有明确限制，别默认「MIT 就等于所有配套资源随便用」。
- 后端模块默认关闭：
yudao-module-mall在pom.xml里是注释状态，不开就是一堆 404；支付、会员还要各自开启。 SHOPRO_STATIC_URL不改必踩：默认值指向官方测试域名test.yudao.iocoder.cn，上线后商品图、banner、icon 全挂；素材要从yudao-demo仓库搬到自己的对象存储/CDN。manifest.json里的第三方标识要全换：appid是__UNI__460BC4C，公众号/App 支付用的是wxae7a0c156da9383b，小程序是wx66186af0759f47c9，Universal Links 是shopro.sheepjs.com。任何一项漏改，登录、支付、分享都会串到别人的应用上。- Android 权限清单偏宽：
manifest.json里声明了READ_SMS、READ_CONTACTS、ACCESS_MOCK_LOCATION、WRITE_SETTINGS等权限，国内应用商店和隐私合规检测会逐条问用途，上架前必须按实际功能裁剪，并同步改androidPrivacy.json。 master没有构建脚本：想进 CI/CD 只能走master-cli（版本落后一代），或自己补@dcloudio/vite-plugin-uni那套依赖。- H5 的 history 路由：Nginx 不做
try_files回退，刷新二级页面直接 404。 - 小程序的域名白名单：请求域名、上传/下载域名、业务域名都要在小程序后台配好，本地调试记得勾「不校验合法域名」。
- 首页/个人中心强依赖装修数据：数据库里没有装修配置时首屏可能大面积空白，先按《店铺装修》文档配一套模板再验收。
- 版本号有三处：
.env的SHOPRO_VERSION、package.json、manifest.json目前并不一致（.env是v2.4.1），自动化流程里别拿.env当版本源。
12. 参考链接
本文基于 2026-11-10 的 master 分支源码、Gitee 仓库信息与官方文档整理；版本号、Star 数与页面清单均以该日为准，后续迭代请以仓库实际内容为准。