简介一份基于 .Net 5.0 与 Uni-App 的可视化布局小程序商城系统源码定位为电商系统开发者的完整可运行参考项目。它采用前后端分离架构支持分布式部署一套代码可编译发布微信小程序、H5、Android、iOS、支付宝小程序、字节跳动小程序、QQ小程序等10个平台内置分销、代理、团购、拼团、秒杀、直播、优惠券、自定义表单等营销模块并覆盖SKU、下单、售后、物流等完整交易流程。资源包共1983个文件以C#源码、Vue页面、HTML模板、JS逻辑及SQL数据库脚本为主另有少量设计图与配置文件压缩包大小33.38MB目录按商品、订单、会员、财务、促销、分销、代理等模块划分便于按业务检索。目前已有675人学习下载适合希望快速理解电商中台与多端商城实现思路的中高级开发人员也可作为二次开发或毕业设计的基础框架。1. 基于 .Net 5.0 与 Uni-App 的小程序商城这套源码到底解决什么问题这个标题里的 zip 包是一套基于 .Net 5.0 和 Uni-App 开发的小程序商城系统源码最大卖点是支持可视化布局。很多团队第一次拿到它都以为装好就能卖货真打开才发现值钱的不是页面文件而是“后端接口 前端框架 可视化布局配置”三者之间的契约。用 .Net 5.0 做稳定的 API 服务用 Uni-App 一套代码交付微信小程序、App 和 H5再让运营在后台拖拽改首页这套组合适合刚起步的电商项目、传统企业私域商城以及想快速上线小程序又不想从零搭架构的团队。它能帮你省掉搭骨架的时间前提是你愿意把它拆开、跑通、再改造成自己的。2. 读懂这套商城的架构.Net 5.0 后端 Uni-App 前端的边界与选型理由真正动手改代码之前得先清楚这套源码把职责画在哪。我见过不少人在前端页面里找“商品去哪了”结果发现商品数据全在后端 API 里前端只是展示。这个分区如果搞反了后面所有二次开发都会绕远路。2.1 为什么是 .Net 5.0从 .NET Framework 迁移过来的现实理由选 .Net 5.0 不是因为它新而是因为它解决了一个很实际的痛点同一套业务代码既能跑在 Windows 服务器也能跑在 Linux 容器里。早期 .NET Framework 时代商城系统基本绑定 IIS部署一台新服务器要先装 Windows、开 IIS、配应用程序池。.NET 5.0 开始微软把 .NET Framework 和 .NET Core 统一成一套东西你用 C# 写的接口可以像 Node 服务一样dotnet run直接跑起来也可以打成 Docker 镜像扔到云服务器上。对做小程序的团队来说这意味着后端不一定要买 Windows 虚拟机用便宜的 Linux 机器就行。实际开发里这套源码通常会把项目拆成 Api提供接口、Model实体、Service业务、Repository数据访问几层。你可以看到控制器的写法很传统用属性路由和依赖注入。比如一个典型的商品接口控制器[Route(api/[controller])] [ApiController] public class ProductController : ControllerBase { private readonly IProductService _productService; public ProductController(IProductService productService) { _productService productService; } [HttpGet(list)] public async TaskIActionResult GetList(int page 1, int pageSize 10) { var data await _productService.GetPagedListAsync(page, pageSize); return Ok(ResultModel.Ok(data)); } }这个例子想说明的是你拿到手后的改造点基本集中在 Service 层而不是 Controller 层。Controller 只是把 HTTP 请求翻译成业务调用真正的规则在 Service 里。如果你要加一个“限时秒杀”字段正确做法是先改实体和数据库再改 Service 的查询逻辑最后才去看小程序端怎么展示。选型理由上.Net 5.0 还占了 C# 生态的便宜。商城系统要处理的订单状态机、支付回调验签、库存扣减用 C# 写起来很顺官方库文档也全。相比之下Node 或 PHP 的商城开源项目虽然多但遇到高并发库存扣减时往往得自己补不少东西。.Net 5.0 的多线程和异步模型成熟列表接口、订单流水场景能直接降低内存占用。当然这个版本现在已经过了微软的主动支持期我一般会建议拿到源码后先把目标框架升级到 .Net 6 或 .Net 8但业务代码不用大改。这一步放到第 5 章避坑部分细说。2.2 Uni-App 一套代码三端输出小程序、App、H5 的取舍Uni-App 在这套方案里的角色是让前端代码尽量只写一遍。它用 Vue 语法编译成微信小程序、支付宝小程序、App 和 H5 页面。你在源码里看到的pages目录和 Vue 单文件组件发布时由 HBuilderX 翻译成小程序需要的Page或Component所以你不要试图在源码里直接改微信小程序的原生 wxss 或 wxml而是改.vue文件再重新编译。取舍点在于三端共用代码能覆盖 80% 的页面但涉及登录、支付、地图、分享这些能力时还是要用条件编译分开。源码里常见的写法是// #ifdef MP-WEIXIN const loginCode await uni.login() // #endif // #ifdef H5 const loginCode // #endif这段代码背后的意思是微信小程序端需要调uni.login()拿 codeH5 端根本没有这个 API只能用手机号验证码或账号密码登录。如果不做条件编译H5 打包时就会直接报错。另一个常见差异是页面标题栏高度。微信小程序里自定义导航栏时状态栏高度和胶囊按钮位置需要动态计算uni.getSystemInfoSync()里拿到的值在不同机型上不一样。很多新手把写好的 header 在小程序模拟器里调好一上真机就偏了原因就是没做这项适配。可视化布局功能也是依靠 Uni-App 的组件化能力实现的。前端只要有一个“容器组件”能根据后台返回的 JSON 动态渲染不同子组件就能做到首页轮播图、商品列表、优惠券入口随心换。这套机制和第 3 章的部署是绑在一起的前端不编译就无法看到后台的改动。2.3 可视化布局到底指什么后台装修与前端渲染的配合可视化布局是这套商城系统最吸引人的地方也是容易被误解的地方。它不是像做网页那样拖拽一个 div而是把“首页长什么样”定义成一份 JSON 配置文件由后台管理界面生成并保存小程序端在进入首页时请求这份配置再对照组件字典逐个渲染。一个简单的布局配置长这样{ version: 12, page: pages/index/index, components: [ { type: banner, props: { images: [/uploads/banner1.jpg] } }, { type: notice, props: { text: 新人立减 10 元 } }, { type: product-grid, props: { categoryId: 3, columns: 2 } } ] }前端渲染时v-for遍历components数组再用条件渲染判断 type 去加载对应组件。改首页的时候运营人员不需要碰代码只要在后台把“通知栏文案”或“第二行展示哪个分类”改掉点发布新版本号就会随着配置一起下发。前端启动时如果发现版本号变了就主动拉新配置。这套设计的关键在于版本号和缓存。如果配置没有版本号就会出现“后台改了、小程序不更新”的诡异现象。所以你在做二次开发时一定不要把布局配置当普通数据表直接 update要保留历史版本至少留一个当前生效版本。这也是第 6 章说“版本化布局配置”时最容易踩深的地方。至此架构边界已经清楚.Net 5.0 只管数据和交易规则Uni-App 只管界面表现可视化布局是两者之间的配置通道。下一章我们把这套东西真正跑起来。3. 把源码跑起来从数据库初始化到微信开发者工具预览的最小步骤我拿到一个 zip 时不会先急着改代码而是按“数据库 → 后端 API → 管理后台 → 小程序端”的顺序跑通。顺序反了会很难查错先跑前端会因为没有后端数据而白屏先跑后端会因为数据库连不上而报 500。下面这条路径能让你在半小时内看到商品列表。3.1 环境准备与目录结构先认清后端、前端、数据库三块打开压缩包后你会看到至少几个顶层目录后端工程通常以.sln结尾、前端 Uni-App 目录里面一定有manifest.json和pages.json、管理后台目录一个独立的 Vue 或 React 项目以及数据库脚本。常见做法是数据库脚本放在db或sql文件夹里直接导入到你的数据库实例。用这套东西需要准备四样工具.NET 5.0 SDK或更高版本、Visual Studio 2019/2022 或 Rider、HBuilderX、微信开发者工具。管理后台如果也是 Vue 项目还需要 Node.js 和 npm。我一般会先看数据库脚本。商城系统至少要保证这几张基础表存在sys_user管理员、wx_user微信用户、product、product_sku、order、order_item、cart、page_layout。如果压缩包里没有建库脚本只有一个.bak或.sqlite文件也别慌先找appsettings.json里的连接字符串它会告诉你这套源码默认用什么数据库。看到ProviderSqlClient就是 SQL Server看到MySqlConnector就是 MySQL别把两者搞混。3.2 后端 .Net 5.0 API 的启动与配置连接字符串、JWT、跨域后端是整套系统的地基。先用 Visual Studio 打开.sln在appsettings.json里改数据库连接。以 MySQL 为例{ ConnectionStrings: { Default: Server127.0.0.1;Port3306;Databasemall;Uidroot;Pwd123456;CharSetutf8mb4; }, Jwt: { Key: your-secret-key-change-me, Issuer: mall-api, Audience: mall-client } }改完之后右键 Api 项目设为启动项直接按 F5或者用命令行dotnet run --project src/Api。正常启动后控制台会吐出 Kestrel 的监听地址比如http://localhost:5000。先用浏览器访问http://localhost:5000/api/product/list能看到 JSON 数据就说明数据库和 API 通了。如果接口返回 500去日志或控制台看堆栈多半是表名对不上或字段缺失这时回数据库核对脚本有没有完整执行。跨域和 JWT 也是两个绕不开的配置。.Net 5.0 的Startup.cs里通常已经写好了AddCors和AddAuthentication你要确认前端请求时带的是Authorization: Bearer token。如果管理后台跑在另一个端口比如localhost:8080而 API 跑在5000跨域配置必须允许8080来源否则后台登录后请求失败报错却是“Unknown CORS error”非常迷惑。这里有个小习惯我会先把跨域策略里的AllowAnyOrigin用在本地开发上线前再收紧成具体域名免得把接口裸奔到公网。3.3 前端 Uni-App 运行到微信小程序HBuilderX 打包与开发者工具对接后端跑通后处理前端。用 HBuilderX 导入 Uni-App 目录注意不是导入整个 zip而是包含pages.json的那一层。打开manifest.json在“微信小程序配置”里填一个测试用的 AppID没有就去微信公众平台注册个人开发者账号或者用测试号。然后找到前端的请求工具文件常见在utils/request.js或common/api.js把baseURL改成后端地址const BASE_URL http://127.0.0.1:5000 export const request (options) { return new Promise((resolve, reject) { uni.request({ url: BASE_URL options.url, method: options.method || GET, data: options.data || {}, header: { Authorization: uni.getStorageSync(token), Content-Type: application/json }, success: (res) { if (res.statusCode 200) { resolve(res.data) } else { uni.showToast({ title: 请求失败, icon: none }) reject(res) } }, fail: (err) reject(err) }) }) }之后在 HBuilderX 里选择“运行 → 运行到小程序模拟器 → 微信开发者工具”。第一次运行会让你指定微信开发者工具的安装路径HBuilderX 会自动拉起开发者工具并打开项目。如果开发者工具加载后空白最常见原因是项目里manifest.json的mp-weixin配置里 appid 为空或者开发者工具的安全设置没有开启服务端口。到开发者工具的“设置 → 安全设置”里打开服务端口再回 HBuilderX 点重新运行即可。这一步最容易踩的坑是127.0.0.1的地址。微信开发者工具在电脑上可以访问本机回环地址但真机预览时127.0.0.1指手机自己不是你的电脑。所以真机调试前要把BASE_URL改成电脑在局域网里的 IP比如http://192.168.1.20:5000并且确认后端项目监听的是0.0.0.0而不是localhost。这个细节能救回你一整个下午。提示如果你用的是 Windows 防火墙后端启动后局域网设备访问不到多半是防火墙拦截了 Kestrel 端口。在“高级安全 Windows Defender 防火墙”里给该端口加一条入站允许规则比反复改代码靠谱。3.4 管理后台可视化布局拖拽装修与发布流程管理后台是运营人员每天要打开的界面它的任务是把第 2 章说的 JSON 配置可视化地编辑出来。把管理后台项目也用 npm 跑起来常见命令是npm install npm run serve启动后登录找到“页面装修”或“首页配置”菜单。你会看到一个类似简易建站工具的界面左边是组件库轮播图、公告、商品分组、图片魔方中间是手机模拟器右边是当前选中组件的属性面板。拖一个组件到模拟器右边改图片、改文字、改跳转链接点“保存”后它不会立刻上小程序要再点“发布”才会生成一个新版本号并写到page_layout表。这是可视化布局里最容易搞混的一环保存只写草稿发布才切换生效版本。发布后回到小程序端下拉刷新首页正常情况下首页会变成你刚拖出来的样子。如果没变大概率是前端有版本缓存后面第 5 章会专门讲。跑通这一条链路后你已经摸清这套系统的地基可以开始按业务需求二次开发了。4. 二次开发最常用的改动点商品、订单、登录与支付跑通只是开始。接下来这些改动是商城上线前几乎一定会碰到的换登录方式、调整商品字段、改订单状态流转、接入真实支付。把这几处吃透后续加需求就不慌。4.1 微信小程序登录换取手机号现在推荐用手机号快捷验证老版本商城喜欢在用户点击“授权手机号”时直接拿到明文手机号但微信现在把手机号获取改成了加密数据。Uni-App 前端不再直接拿到手机号而是先调uni.login()拿 code再用 code 到后端code2Session换取openid和session_key最后把动态令牌phoneCode传给后端。2023 年后微信推荐用“手机号快速验证”组件前端写法是button open-typegetPhoneNumber getphonenumberonGetPhoneNumber微信登录/buttonmethods: { async onGetPhoneNumber(e) { if (e.detail.errMsg ! getPhoneNumber:ok) return const res await uni.login() const { data } await request({ url: /api/login/phone, method: POST, data: { code: res.code, phoneCode: e.detail.code } }) uni.setStorageSync(token, data.token) } }后端拿到phoneCode后调用微信接口获取用户手机号并绑定openid生成自己的登录 token。这里有一句提醒不要在客户端传明文手机号做登录也不要把session_key存到自己的数据库微信官方对密钥存储有要求一旦泄露用户数据安全责任在开发者身上。我见过有源码把session_key打到日志里上线后被安全扫描抓了个正着那是真的翻车。4.2 商品列表与详情页的渲染字段前后端字段对照商城系统的页面看起来花哨核心其实是一张商品表和一张 SKU 表。前端列表页要展示的无非是缩略图、标题、价格、销量详情页要展示多图、价格区间、规格、库存、详情富文本。常见字段映射如下前端字段后端实体说明productNameProduct.Name标题imageProduct.MainImage列表主图priceProductSale.MinPrice最低价originalPriceProductSale.MaxPrice划线价salesProduct.Sales销量展示specsProductSku子表规格组合与库存改前端展示时先到管理后台“商品编辑”里确认数据能录进去再去找接口返回的 JSON 字段名。很多时候页面不显示价格不是前端代码错了而是管理后台创建商品时没有填销售价。还有一种情况是商品多规格时价格不是单个字段需要后端按MIN(price)汇总成“起价”前端看到的是区间。如果你要加“会员价”“拼团价”一定要在 SKU 层级加字段而不是在商品主表上硬塞一个价格否则下单时算价格会乱掉。4.3 订单流程与支付回调从下单到发货的状态机订单是商城系统里最需要稳的部分。常见状态枚举是0 待付款、1 待发货、2 待收货、3 已完成、4 已关闭。下单接口要做的事有三件校验 SKU 库存、生成订单和订单明细、扣减库存。扣减库存一定要放在事务里并且最好用条件更新防止超卖。一个最简的库存扣减 SQL 是UPDATE product_sku SET stock stock - 1 WHERE id skuId AND stock 1;如果AffectedRows为 0说明库存不足直接回滚。等到用户支付成功后微信支付会回调你配置的通知地址后端收到回调后要先验证签名再更新订单状态。这里必须注意幂等同一个回调可能发两次更新订单时要加条件WHERE order_no orderNo AND status 0避免把已发货订单又拉回“待发货”。发货操作一般在管理后台完成前端不过是把“待收货”状态显示出来并允许确认收货。很多新手在支付成功后马上把订单改成“已完成”这是错的。支付成功只是“待发货”等商家发货后才变成“待收货”用户确认收货或系统超时自动确认后才“已完成”。这个状态机如果乱了售后和退款都会跟着出问题。4.4 可视化组件的动态渲染JSON 配置怎么转成页面组件这一节是这个标题里的“可视化布局”落到代码上的核心。Uni-App 里最常见的做法是v-for 条件渲染。首页布局解析类似这样view v-for(item, index) in pageLayout.components :keyindex block v-ifitem.type banner custom-banner :propsitem.props / /block block v-else-ifitem.type notice custom-notice :propsitem.props / /block block v-else-ifitem.type product-grid custom-product-grid :propsitem.props / /block /view每一个custom-*组件接收props自己做数据请求和渲染。这样后台只要往 JSON 里加一组{ type: product-grid, props: { categoryId: 3 } }前端就能多显示一个商品分组不需要打包发布新版本。你后续加组件其实就是三件事写一个 Vue 组件、在布局解析里加一个v-else-if、在管理后台组件库里加一个可拖拽条目。这个模式吃透之后可视化布局就不再是黑匣子而是一张可以自己扩展的地图。5. 避坑与常见问题新手部署这套商城最容易翻车的五个位置这里挑我见过频率最高的五类问题每一条都按“现象 → 原因 → 解决”的顺序写。你踩坑时对照着看能省不少时间。5.1 编译报错目标框架不存在与 NuGet 包恢复失败现象用 Visual Studio 打开.sln后所有项目都提示“无法找到 .NETCoreApp, Versionv5.0”编译直接失败有时候还会看到 NuGet 还原错误的黄条。原因机器上只装了 .NET 6 或 .NET 8 SDK没装 .NET 5.0 SDK。虽然高版本运行时能跑低版本程序但编译时项目还在找Microsoft.NET.Sdk里对应 5.0 的目标包。解决两个办法选一个。一是去微软官网下载 .NET 5.0 SDK 装上然后重开 VS二是直接右键项目“目标框架”改成net6.0大多数 NuGet 包可以自动兼容升级。我一般推荐第二种因为这等于提前把升级做了。改完后重新还原 NuGet再编译一次基本就过了。要注意的是如果代码里用了只在 5.0 里存在的 API升级到 6.0 后编译不会报错但运行时会抛NotSupportedException这种情况在测试环境多跑一遍完整流程就行。5.2 微信小程序白屏合法域名与不校验域名开关的关系现象HBuilderX 编译成功微信开发者工具打开后页面一片白Console 里全是request:fail url not in domain list但电脑浏览器里访问后端接口能通。原因微信小程序在开发者工具里默认校验 request 合法域名你的后端地址是http://127.0.0.1:5000根本不在白名单里。浏览器没这个限制所以“浏览器能开、小程序白屏”特别有迷惑性。解决开发阶段在微信开发者工具右上角“详情 → 本地设置”勾选“不校验合法域名、web-view业务域名、TLS 版本以及 HTTPS 证书”。预览阶段可以用测试号但真机预览时要换成局域网 IP上线前必须把后端域名配到小程序后台的“request 合法域名”里并且强制 HTTPS。这里再补一句管理后台的图片上传地址和接口域名如果不一样也要把这些图片域名加到“downloadFile 合法域名”里否则商品图片会全部加载不出来。5.3 可视化布局保存后不生效缓存与发布版本的坑现象在管理后台拖了组件、点了保存回小程序首页怎么刷新都不变。有时候同一个组件改了文案一会儿显示新文案一会儿又变回旧的。原因这套商城的布局接口大概率有两次缓存。后台“保存”只写了草稿没有“发布”前端拿到的仍是线上版本另外微信小程序本身会对 GET 请求做缓存开发者工具可以手动清除缓存但真机上缓存策略更严格。解决记住“保存是草稿发布才生效”。发布后在小程序端给布局请求加一个?_v时间戳参数或者让后端在响应头里返回Cache-Control: no-cache。更稳妥的做法是给page_layout表加version字段前端启动时先拉版本号版本号不一致再拉完整配置。如果你接手的是已经上线的项目最好查一下后端接口是不是用了ResponseCache特性它在本地测试时不明显一上真机就会让布局卡在旧版本上。5.4 支付沙箱与正式支付的切换配置项遗漏导致回调验签失败现象用微信支付沙箱或测试商户号测试时一切正常换成正式商户号后用户付款成功但订单一直停在“待付款”。后台查日志发现回调根本没走到更新订单那段代码。原因支付切换时漏改的地方太多了回调通知 URL 没改、商户证书没上传、APIv3 密钥不一致、AppID 和商户号没在微信商户平台完成绑定。沙箱环境允许一些宽松配置正式环境会严格校验签名和时间戳。解决按三步排查。一登录微信商户平台确认这个 AppID 已经关联当前商户号二把回调地址写成一个不带业务参数、可公开访问的固定路径比如https://api.example.com/api/pay/notify并在商户平台“支付回调配置”里填成一样的三在后端日志里先打印回调头部的Wechatpay-Signature和请求体原串用微信官方 SDK 验签能验过再走业务逻辑。记住千万别“先改订单再验签”那是安全漏洞。5.5 数据库中文乱码与时间时区问题现象管理后台录入的中文商品名小程序端显示成“???”或者订单创建时间比本地时间差了 8 个小时。原因MySQL 库或表字符集不是utf8mb4连接字符串里没指定字符集后端把DateTime.Now直接序列化到 JSON前端new Date(string)又按浏览器时区解析就出现了时区偏移。解决建库时用CREATE DATABASE mall DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;连接字符串加CharSetutf8mb4SQL Server 则把常用字符串列改成nvarchar。时间上后端统一存 UTC返给前端时用 ISO 8601 格式带Z后缀前端用dayjs转本地时间。如果不想大改也可以后端直接返回DateTime.Now但要在 JSON 序列化配置里关闭DateTimeZoneHandling.Local的隐式转换否则前端会解析出两个时间。这类问题最坑的地方是本地开发不出现部署到云服务器后立刻冒出来建议初始化项目时就按 UTC 方案做。6. 把可视化布局真正变成你的能力从改源码到做一套自己的装修协议6.1 用最少代码扩展一个自定义组件假设你要在首页加一个“领券组件”常见做法是三步走。前端新建components/custom-coupon.vue接收props渲染领券按钮并调领取接口。然后在首页布局解析里加一个v-else-if分支把item.type coupon映射到组件。最后到管理后台的可视化组件库里新增一条“领券”配置项让运营可以拖拽并设置领券入口 ID。完成之后运营就能在不发布小程序新版本的情况下把领券组件加到任意页面。这套流程练习一次后面加拍卖、秒杀、签到组件都是同样套路。6.2 验证布局渲染正确性的方法线上版本与预览版本对比可视化布局最容易出的问题不是组件写错而是配置版本对不上。我给自己的要求是每次发布前先记录当前 layout 的version发布后到小程序端看网络面板里布局请求返回的version是否 1。如果没有说明是缓存按第 5 章说的加时间戳去查。真机预览时我习惯先在微信开发者工具里清一次缓存再造一个仅自己可见的“测试分组”把新组件只配给这个分组等确认无误后再同步到全部用户。这种对比验证能让你在上线前发现大部分问题。6.3 我养成的三个好习惯版本化布局配置、接口超时提示、生产日志分级最后分享三个让我少踩坑的习惯。第一布局配置永远带版本号而且数据库里保留历史版本一旦线上出问题可以一键回滚这个“后悔药”比什么都值。第二前端所有请求都加超时提示首页依赖布局接口如果接口挂了页面不能白屏至少要吐一个“加载失败点击重试”的按钮。第三生产日志按级别分开写信息日志只记录接口名和耗时错误日志才记录堆栈和请求参数不要把用户手机号、登录 token 打进日志这既是规范也是保护自己。我从第一次把这套源码跑通到现在最大的教训就是别高估“可视化布局”这四个字它本质上是一份带版本的 JSON 协议。只要你愿意多花半天把这份协议读懂、扩展好它的价值会远超一个商城本身。希望这些落地的细节能帮到你。本文还有配套的精品资源点击获取