更新记录

1.0.0（2026-08-15）

• 首次提交

平台兼容性

云端兼容性

uni-app(4.45)

云函数类插件通用教程

使用云函数类插件的前提是：使用HBuilderX 2.9+

鲜集 Market

基于 uni-app (Vue 3) + uniCloud 的多店铺生鲜电商项目模板，前后端一体，支持三端：App (APP-PLUS) / H5 / 微信小程序 (MP-WEIXIN)。

内置买家端（首页推荐 / 分类 / 购物车 / 订单 / 优惠券 / 秒杀 / 团购 / 客服 IM 等）与管理端分包（商品 / 订单 / 活动 / 优惠券 / 广告 / 提现 / 统计等），后端基于 uniCloud 云函数与云数据库，无需自建服务器。

技术栈

系统架构

整体架构

┌─────────────────────────────────────────────┐
│                 前端（三端同构）               │
│   App (iOS/Android)  /  H5  /  微信小程序     │
│                                             │
│   pages/        买家端页面（tabBar + 二级页）  │
│   pages/admin/  管理端分包（商家/运营后台）     │
│   uni_modules/uni-pay/  收银台分包            │
└───────────────────┬─────────────────────────┘
                    │ uniCloud.callFunction
                    ▼
┌─────────────────────────────────────────────┐
│              uniCloud 云函数层                │
│                                             │
│   cloud-mall           业务统一入口（核心）    │
│   uni-upgrade-center   App 升级中心           │
│   common/              公共模块（uni-id 等）   │
│   uni-config-center    集中配置（密钥/凭证）   │
└───────────────────┬─────────────────────────┘
                    ▼
┌─────────────────────────────────────────────┐
│              uniCloud 云数据库                │
│   cloud-*    业务自建表（店铺/订单/优惠券…）    │
│   opendb-*   DCloud 开源表（商品/分类/SKU…）   │
│   uni-id-*   用户体系表                       │
└─────────────────────────────────────────────┘

云函数：cloud-mall

cloud-mall 是用户侧所有业务的统一入口，基于 uni-cloud-router 按 action（如 mall/shop/match）路由，内部分层：

cloud-mall/
├── controller/   # 路由入口层：admin / im / mall / order / payment / system / user
├── service/      # 业务与数据层：数据库读写、业务聚合（controller 不直接访问 DB）
├── middleware/   # 中间件链：init → config → permission → auth → cache
├── plugin/       # 可选扩展点（config.js 中按开关加载）
├── config/       # 业务配置资源（配合 uni-config-center）
├── utils/        # 纯工具函数
└── index.js      # 云函数入口

中间件职责：init 初始化 uni-config-center 与 uni-id → config 挂载配置解析 → permission 角色权限检查 → auth token 校验 → cache 缓存能力（Redis / opendb-tempdata / memory）。

前后端通信约定

前端统一通过 utils/cloud-mall.js 的 callMall(action, params) 调用云函数，自动携带 uni_id_token。云端统一返回 { code, message, data }：code === 0 时取 data，否则由 showMallError 统一提示（MODAL: 前缀错误码弹模态窗，其余弹 toast）。

import { callMall, unwrapMall, showMallError } from '@/utils/cloud-mall.js';

callMall('mall/goods/detail', { id })
  .then(unwrapMall)
  .then((data) => { /* ... */ })
  .catch((err) => showMallError(err));

数据库

表结构定义在 uniCloud-aliyun/database/，每张表最多包含三个文件：

• *.schema.json — 表结构与权限
• *.index.json — 索引定义
• *.init_data.json — 初始化种子数据（分类、示例商品、店铺等）

业务自建表以 cloud- 为前缀（店铺、企业、订单退款、优惠券、余额流水、提现、收藏、客服会话等）；商品、分类、SKU、购物车、评论等复用 DCloud opendb-* 开源表结构；用户体系使用 uni-id 标准表。

安装步骤

环境要求

• HBuilderX ≥ 4.23（自带 uni-app 编译器）
• 一个 uniCloud 阿里云服务空间（免费版即可体验）
• 运行微信小程序需 微信开发者工具 与小程序 AppID
• 运行 App 需 Android/iOS 真机或模拟器

第一步：获取项目

方式 A — 插件市场导入（推荐）：在 HBuilderX 插件市场导入本项目模板。导入后 HBuilderX 会自动执行 scripts/init.js，完成部分配置自动回填并在控制台输出剩余初始化清单（见下文「配置方法」）。

第二步：关联 uniCloud 服务空间

1. 在 HBuilderX 项目管理器中右键 uniCloud-aliyun 目录 → 关联云服务空间或项目，选择你的阿里云服务空间
2. 右键 uniCloud-aliyun/cloudfunctions → 上传所有云函数、公共模块及 actions（首次会同时上传 common/ 公共模块与 uni_modules 内的云端配置）
3. 右键 uniCloud-aliyun/database → 上传所有 DB Schema 及扩展校验函数，再选择 初始化云数据库（导入各表 init_data.json 种子数据，包含示例分类、商品与店铺）

第三步：完成配置

按下文「配置方法」填写 AppID 与各项凭证。只想先本地跑 H5 体验的话，最少只需完成 uniCloud 关联；支付、微信登录等能力可以后续按需补齐。

第四步：运行

配置方法

配置总览

所有云端密钥与业务配置集中在 uni-config-center（uni_modules/uni-config-center/uniCloud/cloudfunctions/common/uni-config-center/），前端 AppID 类配置在 manifest.json：

修改 uni-config-center 下的配置后，需重新上传 common 公共模块（或整个云函数目录）才会生效。

占位符约定

模板发布时已对敏感配置脱敏，两类占位符含义不同：

• __UNI_APP_ID__ — 安装时由 scripts/init.js 自动回填为当前项目的 DCloud AppID，无需手动处理
• <FILL_ME> — 无法自动推断，必须手工填写（未填写的能力对应功能不可用）

init.js 还会自动为 uni-id 生成随机的 passwordSecret / tokenSecret，并在检测到剩余占位配置时在控制台打印待办清单。

1. manifest.json

• mp-weixin.appid：替换为你自己的微信小程序 AppID（默认占位 wx00000000000000）
• app-plus.distribute.sdkConfigs.payment.weixin.appid：App 端微信支付 AppID
• app-plus.distribute.sdkConfigs.share.weixin.appid：App 端微信分享 AppID

2. uni-id（登录与用户体系）

编辑 uni-config-center/uni-id/config.json：

• dcloudAppid：安装时自动回填
• passwordSecret / tokenSecret：安装时自动生成，也可自行替换
• 微信登录：填写 mp-weixin.oauth.weixin 的 appid / appsecret
• 其余登录方式（短信验证码等）按 uni-id 官方文档 按需配置

3. uni-pay（支付渠道）

编辑 uni-config-center/uni-pay/config.js，按实际启用的渠道填写凭证：

• 微信支付：appid / mchid / API v3 密钥 / 证书
• 支付宝：appid / 应用私钥 / 支付宝公钥
• 苹果内购 / 华为支付：按需填写

未启用的渠道保留模板值即可，收银台会隐藏对应支付方式。详见 uni-pay 官方文档。

4. cloud-mall（商城业务）

编辑 uni-config-center/cloud-mall/config.json，按需填写：

• 支付结果回调相关配置
• 消息推送（uni-push）
• 小票打印机接入
• 物流查询
• 邮件通知

所有含 <FILL_ME> 的字段均为可选能力开关——不填只影响对应功能，不影响商城主流程。

项目结构

src/                                 # uni-app 项目根（HBuilderX 打开此目录）
├── App.vue                          # 应用入口
├── main.js                          # Vue 实例挂载（createSSRApp）
├── manifest.json                    # 打包配置（vueVersion: "3"，各端 AppID）
├── pages.json                       # 页面路由 + tabBar + 分包
├── index.html                       # Vite 入口（勿删，含编译器占位符）
├── uni.scss                         # 全局样式变量
├── pages/                           # 买家端页面
│   ├── index/                       # 4 个 tabBar 页：推荐/分类/购物车/我的
│   ├── goods/                       # 商品详情、评价
│   ├── order/                       # 下单、订单列表/详情、退款、评价
│   ├── activities/                  # 秒杀、团购、天天特价
│   ├── coupons/                     # 领券中心
│   ├── user/                        # 收藏、足迹、优惠券、余额、充值、提现
│   ├── im/                          # 在线客服（会话列表 + 聊天）
│   ├── login/ userinfo/ set/        # 登录、个人资料、设置
│   ├── shop/ company/               # 店铺详情、店铺/企业入驻申请
│   ├── selfraising/                 # 自提点选择/申请/管理
│   ├── search/ store-switch/        # 搜索、切换门店
│   └── admin/                       # 管理端分包：商品/订单/活动/优惠券/广告/提现/统计
├── components/                      # easycom 公共组件（hb-* 自动注册）
├── utils/                           # 前端工具（cloud-mall.js 云函数调用封装等）
├── mock/feed-data.js                # 首页降级 mock 数据
├── static/                          # 静态资源（tabBar 图标等）
├── uni_modules/                     # uni-app 插件（uni-pay、uni-ui、uni-config-center…）
├── uniCloud-aliyun/
│   ├── cloudfunctions/
│   │   ├── cloud-mall/              # 业务统一云函数（controller/service/middleware）
│   │   ├── uni-upgrade-center/      # App 升级中心
│   │   └── common/                  # 公共模块（uni-id 等）
│   └── database/                    # 表 schema / index / 种子数据
└── scripts/init.js                  # 安装后初始化脚本（配置回填与待办提示）

开发约定（二次开发必读）

easycom 组件自动注册

components/<name>/<name>.vue 由 uni-app 自动扫描注册，页面无需 import 或在 components: {} 中声明，直接使用短横线标签：

<template>
  <hb-header platform="APP-PLUS" :navBarHeight="44" />
</template>

三端条件编译

平台差异用条件编译处理，首页三端样式差异集中在 pages/index/index.vue 的 feedTop computed 中，不在子组件写平台分支：

<!-- #ifdef APP-PLUS -->
<view>仅 App 可见</view>
<!-- #endif -->
<!-- #ifdef MP-WEIXIN -->
<view>仅小程序可见</view>
<!-- #endif -->

底部 tabBar 与固定定位

tabBar 由 pages.json 配置接管（推荐/分类/购物车/我的），图标在 static/images/tabbar/。固定定位的悬浮层需用 bottom: calc(var(--window-bottom) + Nrpx) 避开 tabBar 与底部安全区。

兼容性红线

• 不要用 CSS inset 简写：微信小程序不支持，用 top/right/bottom/left 分别指定
• 不要用 flexbox gap：低版本 Android WebView（< Chromium 84）会静默忽略导致间距塌陷，统一用子元素 margin 实现间距
• 不要删除 index.html：其中 <!--preload-links--> 等占位符由 Vite 编译器填充

mock 数据

首页 mock 数据集中在 mock/feed-data.js（接口失败时的降级展示），不要在组件内硬编码列表数据；hb-feed-grid 通过 :items prop 接收数据集。

主题色

常见问题

Q：云函数调用报错 / 首页数据空白？ 确认已关联云服务空间并上传全部云函数、公共模块与 DB Schema，且已初始化云数据库导入种子数据。

Q：修改了 uni-config-center 配置不生效？ 配置随 common 公共模块部署在云端，修改后需重新上传公共模块（或上传所有云函数）。

Q：收银台没有支付方式？ uni-pay/config.js 中对应渠道仍是模板占位值，按「配置方法」第 3 节填写真实凭证。

Q：小程序真机预览白屏或样式错乱？ 检查 manifest.json 的 mp-weixin.appid 是否已替换为自己的 AppID，并用 发行 → 小程序-微信 的产物导入微信开发者工具。

测试账号

运行 e2e/seed 后以下账号可用（密码统一为 E2e@Test2026）正式上线后，请删除此云函数：

# 执行 seed（幂等，可重复跑）
curl -X POST 'https://fc-mp-{space_id}.next.bspapp.com/http/mall-test' \
  -H 'Content-Type: application/json' \
  -d '{"action":"e2e/seed"}'