做开源商城系统这个选题其实挺有意思的。我前前后后用Uniapp搭过三套商城应用从最早的自用练手到后来给客户做的正式项目踩坑无数也沉淀了不少经验。这两天整理工作笔记索性把商城首页小程序源码、购物商场小程序系统这套基于Uniapp开发的开源商城系统从头到尾理一遍从技术选型、项目结构到登录、购物车、订单这些核心环节的实现细节再到分端打包和审核遇到的坑一起写清楚。这篇东西适合已经在学Uniapp想找一个完整实战项目的人也适合手里有商城需求打算自己从开源方案改起的团队。我会尽量说人话把技术选型背后的为什么、实操里的怎么调讲透。1. 开源商城系统的价值与设计思路1.1 为什么坚持用Uniapp做商城底层框架先说结论我见过太多团队做商城一上来就奔着原生小程序去写。原生小程序语法确实简单但等你需要同时上微信小程序、支付宝小程序、H5网页、安卓App、iOS App的时候五套代码五个维护周期谁维护谁知道。Uniapp的核心思路是一套代码多端运行基于Vue语法编写业务逻辑编译器负责把代码转换成各端能运行的形式。对于商城这种业务逻辑高度统一、只是展示载体不同的项目这个性价比非常高。有人会问Flutter和React Native行不行这两个确实能出App但有一个硬伤对国内小程序生态几乎无能为力。小程序在国内的流量地位不用多说你不可能放弃这条线。另外Uniapp的社区积累已经相当厚实商城类项目的插件、组件、常见问题方案到处都是拿来即用的程度很高。所以我的判断是预算有限、上线时间紧、需要覆盖多端的团队Uniapp是当前最合理的选择。这种跨端方案带来的直接收益是同一套商品模型、同一个购物车逻辑、同一份订单状态机在微信小程序和H5上表现一致。作为开源商城系统别人拿到源码后不需要做伤筋动骨的改动只需要替换UI、调整主题色、绑定后端接口就可以快速产出自己的商用版本。1.2 开源商城系统的核心链路设计一个购物商场小程序系统核心链路拆开其实就四段用户逛、用户选、用户买、商家履约。用技术术语说就是商品展示 - 购物车/下单 - 支付 - 订单管理。围绕这个主链路衍生出用户登录、地址管理、优惠券、售后等支线。我在设计这个开源系统时刻意遵循最小可用闭环原则就是先把主链路走通再去谈各种复杂的营销玩法。因为商城系统最怕的是主链路没走稳先加了一堆秒杀、拼团、分销逻辑最后出了问题连基本的下单都报错。这版项目里前端主链路涉及的页面和模块大致如下首页轮播图、金刚区图标、商品楼层推荐、秒杀倒计时入口分类页左侧一级分类、右侧二级商品列表购物车加购、勾选、数量修改、批量删除、价格合计个人中心登录状态展示、订单入口、地址管理、设置订单流程确认订单页、支付页、订单列表、订单详情、订单状态切换每个模块都在pages目录下独立文件夹维护。后端的角色我在这里给的是一个标准RESTful API服务前端通过封装好的request对象统一请求。开源项目的好处就是这一层后端实现你可以换掉用Java、Go、Node或者PHP都行前端封装好了之后基本不受影响。2. 环境搭建与项目结构解析2.1 从零搭建Uniapp开发环境拿到开源商城源码之后第一步是先把开发环境跑通。我用的是HBuilderX搭配微信开发者工具的组合。HBuilderX是DCloud出品的IDE内置了对Uniapp项目的编译、运行、调试支持操作路径非常顺手。安装顺序建议下载安装HBuilderX官方版本即可不用额外配置环境变量安装微信开发者工具这一步是调试小程序端的必要条件在HBuilderX里配置微信开发者工具路径这样点击运行到小程序模拟器代码编译后会自动唤起微信开发者工具配置路径的方法是菜单栏运行 - 运行到小程序模拟器 - 微信开发者工具第一次运行时会提示设置工具路径找到微信开发者工具的安装目录选择里面的cli文件或者主程序根据不同系统选择。这个配置只会做一次后面调试就很顺了。还有一点容易被忽略微信开发者工具需要开启服务端口。在微信开发者工具的设置 - 安全设置里把服务端口打开否则HBuilderX调用的时候会报错。2.2 项目目录结构与文件职责拿到源码以后先不要急着运行把目录结构看懂很重要。Uniapp脚手架的目录约定比较固定这个开源商城项目的结构如下├── pages/ # 页面目录unoapp按实际路径存储页面 │ ├── index/ # 首页 │ ├── category/ # 分类页 │ ├── cart/ # 购物车 │ ├── user/ # 个人中心 │ ├── goods/ # 商品详情 │ ├── order/ # 订单相关 │ └── login/ # 登录页 ├── components/ # 自定义组件 ├── static/ # 图片、图标等静态资源 ├── api/ # 接口请求统一封装 ├── utils/ # 工具函数 ├── store/ # 状态管理Vuex/Pinia ├── App.vue # 应用生命周期入口 ├── main.js # 入口文件 ├── manifest.json # 应用配置AppID、权限、打包配置 ├── pages.json # 页面路由、导航栏、tabBar配置 └── uni.scss # 全局SCSS变量pages.json是全局配置的核心它对标的是原生小程序里的app.json。页面路由、底部tabBar、导航栏颜色、页面窗口样式都在这里配置。开源商城项目里底部tabBar一般是首页、分类、购物车、我的这四个固定入口每个tab对应一个页面路径。manifest.json是另一个关键文件。微信小程序的AppID、H5端的标题、App端的包名和图标都在这里配置。很多新手把代码跑起来发现小程序白屏一查原因就是manifest.json里的小程序AppID还是测试号换成自己注册的AppID就正常了。2.3 关键依赖与组件库的选择商城项目里有一个绕不开的问题UI组件库用什么。开源方案常用的有uview-plus、uni-ui等。我自己在实际项目里更倾向用uview-plus这种相对完整的组件库因为商城场景里需要大量的表单、弹窗、列表、标签组件如果全手写工作量非常大。uview-plus基于Uniapp做了全端适配日历、商品规格弹窗这类组件在微信小程序和H5上表现基本一致能省下不少适配精力。装上以后项目里的很多页面可以直接用它提供的栅格和通用组件来排版。状态管理方面这版项目用的是Vue3版本所以我推荐用Pinia来管理全局状态比如用户登录态、购物车数量、用户地址等。Pinia的语法比Vuex简洁很多而且对TypeScript支持更好上手成本低。另外还有一个容易被忽略的封装request请求对象。商城系统几乎所有页面都要和后台交互所以网络请求封装必须统一。我习惯在utils目录下维护一个request.js内部封装uni.request统一做接口地址前缀拼接、token注入、返回码拦截、错误提示。这样一来业务页面里只需要调用request.get(/api/goods, params)这样的方法逻辑清爽得多。3. 商城核心功能模块实现拆解3.1 商城首页的布局与数据联动先拿首页开刀。商城首页小程序源码里首页是用户的第一个触点也是转化率最关键的一环。它的结构基本是顶部搜索栏、轮播图、金刚区图标导航、活动入口区、商品楼层。首页的布局我强烈建议用骨架屏策略。要搞清楚首页不是打开就有数据的网络请求有延迟。如果空白页面等数据回来再渲染用户大概率直接就退出了。所以在数据加载完成前先渲染出页面结构的骨架占位等数据回来再平滑替换成真实内容。首页的数据加载逻辑我在项目里是放在onLoad和onShow生命周期里处理的。onShow尤其重要因为小程序从别的页面返回首页时可能没有重新加载数据但购物车数量、登录状态可能有变化所以onShow里我一般会检查一下是否需要刷新。轮播图和金刚区这两个模块属于强配置属性。为了开源项目便于二次开发我在后端数据模型里为它们设计了配置表或者接口字段运营人员可以在后台配置轮播图片、跳转链接和图标入口。前端这边只需要渲染后端下发的数组然后做统一的跳转分发处理。跳转分发的核心是维护一个type字段比如type为1跳转商品详情、type为2跳转页面路由、type为3跳转H5链接这样灵活性会高很多。商品楼层是首页转化率最高的部分。楼层通常按分类或推荐位来切分比如热卖单品、新品首发。每个楼层内部我建议用双列瀑布流布局因为商城场景里图片高度不一致瀑布流在视觉上比普通双列更舒适。Uniapp里做瀑布流可以直接用CSS flex布局配column-count来实现也可以用css的gap搭配height自适应不需要额外引入复杂组件。3.2 登录授权与用户体系的实现细节登录模块是商城系统的真正入口也是新坑最密集的地方。先说微信小程序的登录流程。用户点击登录按钮 - 前端调用uni.login()获取临时code - 前端把code传给自己的后端 - 后端拿着code去微信接口换openid和session_key - 后端生成自己的业务token返回前端 - 前端存储token并更新登录态。这个流程里有一个关键点很容易踩坑企业主体的小程序openid需要在后端获取不能在前端直接暴露。而且session_key绝不能下发到前端否则会留下安全隐患。开源项目里后端收到的每一个请求都应该先校验token有效性而token与本地的用户信息绑定后续接口才能识别出是谁在操作。再来说一个热词里反复出现的报错小程序获取登录后的微信用户失败:wx1cb4398e1413dce7。这个报错在旧版本里很常见原因是调用了wx.getUserInfo接口但权限已经收紧。微信从2021年开始逐步调整用户授权策略头像和昵称需要用户主动点击头像昵称填写能力来获取开发者不能再用getUserInfo悄悄拿信息。正确的做法是用户授权登录后头像用button的open-type为chooseAvatar来收集昵称用input typenickname来收集。这是一个关键适配点如果不处理上架审核也会被卡。H5端和多端的登录差异也要提一下。H5里不需要走微信的code换openid流程一般用手机号验证码登录或者账号密码登录。Uniapp可以让同一套前端代码在编译时根据平台做差异处理用条件编译指令比如#ifdef MP-WEIXIN表示这段代码只在微信小程序端编译#ifdef H5则只在H5端编译。登录流程在不同端差异很大这个方案能把两套代码干净地隔离在同一份源码里。3.3 商品列表、搜索与筛选的设计商品列表页要处理的用户动作比较多查看商品、搜索、筛选、排序。开源商城项目里商品列表一般有两种展示形态网格双列或列表单列。双列适合图片为主的商品单列适合需要更多文字描述的。建议在列表页顶部提供视图切换按钮用户按需切换。搜索功能我在这里想特别说一个防抖技巧。用户输入关键字时如果每输入一个字符就向后端发请求控制台会塞满无效请求服务端压力也大。我在工具函数里封装了一个防抖方法通过定时器延迟触发用户停止输入300毫秒后才真正发起搜索请求。这是一个很小的细节但对性能体验提升非常明显。筛选部分字段一般是分类、价格区间、品牌、销量、上架时间。前端把筛选条件封装成对象统一拼到请求参数里后端做动态查询。排序逻辑我习惯把排序选项做成组件每次点击重新请求列表并重置分页。有一点要注意列表页的分页请求和筛选参数的组合要处理好否则切到第二页以后筛选条件就丢了用户翻页看到的是全量商品这种体验很劝退。详情页是商品信息的核心载体。商品主图轮播、价格、库存、规格选择、详情富文本这几个模块是标配。规格选择是一个交互复杂度较高的组件SKU库存量单位的联动判断选中规格后计算价格和库存必须保证库存不足的规格是置灰状态。很多商城系统卡在这里就是没有对SKU数据做处理。我建议用规格矩阵的方式通过多维数组组合出所有合法的SKU组合然后通过前端状态来实时计算当前选中规格是否有效这样交互流畅度和准确性都有保障。3.4 购物车、下单与订单状态流转购物车模块首先要决定是本地购物车还是服务端购物车。我的建议是未登录用户把购物车数据存在本地存储uni.setStorageSync中登录后切换成服务端购物车。这样既能保证游客可以加购又能让用户换设备不丢数据。两种方案的数据结构可以复用同一套模型只是在切换时做一次数据迁移合并。购物车页的UI逻辑比较固定商品复选框、商品缩略图、名称、规格、单价、数量增减按钮、左下角全选、右下角合计和结算按钮。关键点是勾选状态的全局联动。如果有一个子项取消勾选全选按钮要自动取消反过来全选时所有子项都要勾选。这个联动逻辑我用Vue的computed计算属性来做基于购物车列表和选中的id列表实时推导全选状态不需要手动维护更新方法简洁且不容易出bug。下单流程里确认订单页要展示收货地址、商品明细、运费、优惠金额、应付金额。前端拿到这些数据之后用户点击提交订单后端会创建订单记录并返回订单号。支付环节在小程序端是uni.requestPayment传入支付参数调起微信支付H5端则需要根据支付场景选择H5支付或扫码支付。开源项目里支付回调涉及异步通知所以订单状态不能在前端直接改成已支付要等后端收到微信支付异步通知后修改状态前端通过轮询或WebSocket来刷新订单状态这一点是很多自研商城容易埋雷的地方。订单状态流转我设计为待付款 - 待发货 - 待收货 - 已完成外加已取消和退款中状态。每个状态对应前端订单列表的不同操作按钮比如待付款显示取消订单和去支付待发货显示提醒发货待收货显示确认收货。这个状态机在后端要严格控制不能允许状态胡乱跳转比如待收货的订单不能直接变成已取消。4. 多端适配、打包与上线全流程4.1 H5端的部署与跨域处理Uniapp项目运行到H5端其实挺快但H5上线面对的坑比小程序多。最常见的是跨域问题前端页面跑在一个域名后端接口在另一个域名浏览器默认会拦截跨域请求。开发环境可以在manifest.json里配置h5.devServer.proxy把接口请求代理到后端解决开发期的跨域。生产环境更建议在后端网关层统一配置CORS允许指定域名跨域访问或者用Nginx反向代理同域转发。H5的打包配置在manifest.json - H5配置里需要设置路由模式。如果项目要部署到Nginx子目录路由模式建议用hash模式否则刷新页面会404。如果项目有独立域名且能配置Nginx的try_files规则可以用history模式URL更优雅。router base这两个参数要和实际部署路径一致否则打包后资源加载会找不到路径白屏。部署这块我遇到很多团队习惯把前端文件打包完直接扔到一个目录然后后端接口也在同一台服务器上做Nginx代理转发。这是可以的关键是Nginx配置要处理好静态资源的缓存和持久化确保商城图片更新后用户能看到新版本。推荐在静态资源文件名上加上版本号或hash值Nginx配置缓存策略时排除带有hash的文件让它们可以长缓存同时保证更新后能拉到新文件。4.2 微信小程序端的打包与审核注意事项小程序端打包比较简单HBuilderX里点击发行 - 小程序-微信编译完成后会生成一个dist/dev/mp-weixin目录用微信开发者工具导入这个目录然后上传代码。上传前需要确保manifest.json里已经填好了自己小程序平台的AppID不是测试号。小程序审核遇到的高频问题我列几个实际经验类目选择要匹配。商场类小程序需要选择电商平台类目提交时需要提供对应资质如果没有资质至少要先用商家自营类目顶上。支付方式不能是个人收款码必须走微信支付商户号否则审核会被打回。如果有用户隐私相关的接口比如获取用户位置需要在后台隐私保护指引中声明用途。小程序里不能出现诱导分享的话术分享按钮文案要合规。内容审核通过后上线版本需要发布在版本管理页操作。还有一个容易踩坑的点自定义分享好友。我在页面里用onShareAppMessage定义了分享标题、图片和路径但是预览时候分享卡片不显示或者提示fail。后来排查发现是因为分享路径里的参数没有encodeURIComponent导致特殊字符截断了。分包情况下还要保证分享路径是在已加载的分包里否则也报错。4.3 App端云打包与安卓应用市场适配Uniapp项目打包成App主要走HBuilderX的云打包能力。云打包不需要在本地安装Android SDK和Xcode而是把代码上传到DCloud的云端服务器由云端完成原生打包。这是对前端开发者非常友好的方式尤其适合没有原生开发经验的小团队。打包前manifest.json要重点配置App模块权限相机、定位、文件存储等、App图标、启动图、包名应用唯一标识。包名建议用反域名格式比如com.yourcompany.mall一旦确定后面尽量不要再改因为安卓应用市场上架后包名变更会视为新应用。安卓应用市场上架是另一个话题。国内主流市场包括华为、小米、OPPO、vivo、应用宝等每个市场需要的资质不太一样但基本都需要软件著作权证书。上架前建议用加固工具对APK做加固防止反编译。还有一点很多市场的审核会检测App内是否有强制升级模块纯后台强制升级API容易被判定为违规所以开源项目里我一般把强制升级做成可配置项默认关闭。iOS上架就更敏感一些需要Apple开发者账号且App Store审核对虚拟支付比如商城里的虚拟商品有严格限制实物商城反而问题不大。打测试包可以用云打包的自定义基座方便开发真机调试但正式上架一定用正式打包。5. 实战问题排查与经验分享5.1 微信登录拿不到用户信息怎么办这个问题的出现频率非常高很多人在群里问小程序获取登录后的微信用户失败。直接原因基本是旧接口失效加上新接口适配没到位。验证方案可以参考下面这个排查流程问题现象可能原因排查方向授权弹窗不出现未使用chooseAvatar和nickname input换成官方推荐的头像昵称填写能力code2Session返回40029小程序AppID和密钥不匹配检查manifest配置和后端微信配置获取不到openidcode换openid流程未走通后端日志查看微信接口返回用户头像昵称为空用户未主动填写把头像昵称填写按钮做成必选项新的适配交互其实更尊重用户用户点击头像组件微信弹出选择头像的界面用户点击昵称输入框输入法会弹出微信昵称快捷填充的按钮。开发者只需要把这两个组件放进个人信息编辑页用户保存后提交给后端。注意这个流程只在微信小程序端有效H5端还是传统的表单输入方式需要分别适配。5.2 uniapp打包H5出现连接服务器超时的处理还有一个热词是uniapp打包H5 出现连接服务器超时,点击屏幕重试的页面。这个其实是Uniapp的H5请求失败兜底组件。它的出现说明前端请求后端接口失败而且没有进入统一的错误回调逻辑直接触发了默认的失败页。我遇到的原因主要有三类接口跨域被拦截。后端CORS没配置好或者前端代理配置缺失。后端服务没启动或者网络不通。最常见的是本地联调前端跑在8080端口后端跑在9090防火墙拦截或者地址写错了。H5部署的静态文件在HTTPS环境但接口还走HTTP混合内容被浏览器拦截。处理方式排查的时候先把H5页面Network面板打开看请求失败的状态码。如果是CORS错误优先处理后端如果是404或者502检查接口地址和代理配置如果是混合内容拦截把接口升级到HTTPS。如果你是希望它不出现白屏可以自定义一个统一的错误页或者toast提示而不是用默认的超时页面。这种设计对用户体验很重要用户看不到控制台看到这个提示第一反应是网站挂了。5.3 小程序跳转公众号文章失败的配置小程序无法打开公众号文章,需要配置什么这个问题我答过很多次。小程序里如果要打开公众号的文章有两种方式第一种使用web-view组件嵌套公众号H5的文章链接。前提条件是mp.weixin.qq.com这个域名不能直接在web-view里使用。所有web-view打开的网址都要在小程序管理后台配置业务域名而且业务域名要求ICP备案并且需要在对应域名下放校验文件。第二种如果只是跳转到公众号的一个文章页其实也可以用客服消息或者订阅消息引导用户把文章链接发送给用户用户在微信环境里直接打开。这个方式绕开了web-view的域名限制也是一种实用方案。对于百度小程序嵌套h5类似场景机制基本一样只是嵌套的域名需要走对应平台的域名配置流程。商城系统里活动页、内容页、帮助中心这类页面如果以H5形式承载务必提前规划好域名把域名配置流程放到项目开发初期就搞定不然到上线前才发现域名还在备案流程里那就被动了。5.4 renderjs视频播放与自定义分享的细节坑热词里提到了uniapp renderjs 手机录得mp4无法播放。这个问题通常发生在H5端通过renderjs去处理视频播放的场景。renderjs可以把一部分逻辑运行在视图层解决跨端的一些渲染问题但视频播放对编码格式是有要求的。手机录制的视频常常是H.265编码或者带有特殊音轨浏览器默认播放支持并不好。解决方案有几个一是强制转码在上传视频的时候统一转成H.264编码加AAC音轨的MP4这是兼容性最稳的方案二是后端做视频切片用HLS或者DASH流媒体格式播放移动端的兼容性会更好三是前端播放器用video组件时设置好playsinline和x5-playsinline等属性避免浏览器调用原生播放器带来的兼容差异。商城商品详情里嵌入视频最好统一走视频转码服务不要让用户直传原始文件。另一个细节是自定义分享好友的参数。分享不只是分享一个页面链接它需要带上分享者信息比如分销场景里要带分享者的userId这样被分享的人通过链接进入商城系统才能把关系链记录下来。实现细节是onShareAppMessage返回的path里拼接参数参数值一定要encodeURIComponent编码拿到参数的目标页面在onLoad的options里解码然后处理好特殊字符。这个坑很小但影响很大因为分销关系链一旦对不上推广体系就废了。再提一下微信小程序的页面栈问题商城小程序从首页进详情页再跳转H5专题页然后H5里又要跳App下载页面这个流程里页面栈的层数会不断加深。小程序原生页面栈最多支持10层超过之后跳转会被忽略或报错。常规处理是在需要深跳的地方用uni.reLaunch或uni.redirectTo替换当前页面不要一直uni.navigateTo叠加。像首页到详情页这种高频跳转尽量合理控制页面栈的生命周期避免not found:page奇怪的报错。6. 给正在做开源商城项目的团队一点建议最后聊点实在的。一个开源商城项目的成功上线技术只占一半另一半是梳理清楚业务边界。如果你打算拿这套Uniapp商城系统做二次开发我的建议是先稳住主链路再去加花活。先把登录、商品浏览、加购、下单、支付、订单查询这一条线调通在这条线没有稳定之前不要往系统里塞分销、直播、秒杀这类重型功能。我见过太多项目毁在需求一直膨胀代码结构越来越乱最后连最基础的下单都出了bug用户购物车清空、订单支付回调迟迟不到账这种体验简直是自杀。另一个经验是接口层的设计一定要稳定。前端和后端约定好统一的数据返回格式比如{ code: 0, data: {}, message: success }这样前端错误拦截器才能统一处理。如果每个接口返回数据结构都不一样前端就要到处写分支判断后期维护成本直线上升。后端接口的异常处理也要细致。商城场景里库存不足、价格变动、优惠券过期这些都需要后端校验后给出明确提示前端把错误信息清楚展示给用户。不要只在控制台打日志用户不知道发生了什么只会觉得你的商城系统不靠谱。关于开源项目的部署和上线团队在开发初期就应该把上线路径定下来。小程序端的AppID注册、业务域名备案、支付商户号申请这些前置条件周期都不短有的甚至要一两周。不要等代码写完才发现商户号还没下来。还有一个容易被忽视的点日志与监控。商城系统一旦有真实用户接入线上问题排查就必须靠日志。建议在后端接口层统一记录请求参数和返回结果前端也要有对应的错误上报机制。这样用户在哪个页面、哪个接口出了问题排查起来才能有的放矢。这套开源商城系统作为学习项目它的代码量适中模块边界清楚适合完整读一遍。作为商用项目它的骨架足够稳定可以按要求改造UI和业务。我实际跑过之后最大的感受是Uniapp的开发效率确实在线尤其是多端覆盖的场景省下的工程量不是一点半点。但框架只是工具商城的核心还是你对业务的理解对用户购物体验的把控。技术细节可以慢慢磨业务方向不能偏。如果你正准备基于这套源码做自己的商城先动手把开发环境跑起来把首页和登录两个模块读透剩下的事情就会顺利很多。遇到具体的问题也欢迎带着报错信息来交流我把遇到过的问题都整理在这篇里了希望你少走一些弯路。
做开源商城系统这个选题其实挺有意思的。我前前后后用Uniapp搭过三套商城应用从最早的自用练手到后来给客户做的正式项目踩坑无数也沉淀了不少经验。这两天整理工作笔记索性把商城首页小程序源码、购物商场小程序系统这套基于Uniapp开发的开源商城系统从头到尾理一遍从技术选型、项目结构到登录、购物车、订单这些核心环节的实现细节再到分端打包和审核遇到的坑一起写清楚。这篇东西适合已经在学Uniapp想找一个完整实战项目的人也适合手里有商城需求打算自己从开源方案改起的团队。我会尽量说人话把技术选型背后的为什么、实操里的怎么调讲透。1. 开源商城系统的价值与设计思路1.1 为什么坚持用Uniapp做商城底层框架先说结论我见过太多团队做商城一上来就奔着原生小程序去写。原生小程序语法确实简单但等你需要同时上微信小程序、支付宝小程序、H5网页、安卓App、iOS App的时候五套代码五个维护周期谁维护谁知道。Uniapp的核心思路是一套代码多端运行基于Vue语法编写业务逻辑编译器负责把代码转换成各端能运行的形式。对于商城这种业务逻辑高度统一、只是展示载体不同的项目这个性价比非常高。有人会问Flutter和React Native行不行这两个确实能出App但有一个硬伤对国内小程序生态几乎无能为力。小程序在国内的流量地位不用多说你不可能放弃这条线。另外Uniapp的社区积累已经相当厚实商城类项目的插件、组件、常见问题方案到处都是拿来即用的程度很高。所以我的判断是预算有限、上线时间紧、需要覆盖多端的团队Uniapp是当前最合理的选择。这种跨端方案带来的直接收益是同一套商品模型、同一个购物车逻辑、同一份订单状态机在微信小程序和H5上表现一致。作为开源商城系统别人拿到源码后不需要做伤筋动骨的改动只需要替换UI、调整主题色、绑定后端接口就可以快速产出自己的商用版本。1.2 开源商城系统的核心链路设计一个购物商场小程序系统核心链路拆开其实就四段用户逛、用户选、用户买、商家履约。用技术术语说就是商品展示 - 购物车/下单 - 支付 - 订单管理。围绕这个主链路衍生出用户登录、地址管理、优惠券、售后等支线。我在设计这个开源系统时刻意遵循最小可用闭环原则就是先把主链路走通再去谈各种复杂的营销玩法。因为商城系统最怕的是主链路没走稳先加了一堆秒杀、拼团、分销逻辑最后出了问题连基本的下单都报错。这版项目里前端主链路涉及的页面和模块大致如下首页轮播图、金刚区图标、商品楼层推荐、秒杀倒计时入口分类页左侧一级分类、右侧二级商品列表购物车加购、勾选、数量修改、批量删除、价格合计个人中心登录状态展示、订单入口、地址管理、设置订单流程确认订单页、支付页、订单列表、订单详情、订单状态切换每个模块都在pages目录下独立文件夹维护。后端的角色我在这里给的是一个标准RESTful API服务前端通过封装好的request对象统一请求。开源项目的好处就是这一层后端实现你可以换掉用Java、Go、Node或者PHP都行前端封装好了之后基本不受影响。2. 环境搭建与项目结构解析2.1 从零搭建Uniapp开发环境拿到开源商城源码之后第一步是先把开发环境跑通。我用的是HBuilderX搭配微信开发者工具的组合。HBuilderX是DCloud出品的IDE内置了对Uniapp项目的编译、运行、调试支持操作路径非常顺手。安装顺序建议下载安装HBuilderX官方版本即可不用额外配置环境变量安装微信开发者工具这一步是调试小程序端的必要条件在HBuilderX里配置微信开发者工具路径这样点击运行到小程序模拟器代码编译后会自动唤起微信开发者工具配置路径的方法是菜单栏运行 - 运行到小程序模拟器 - 微信开发者工具第一次运行时会提示设置工具路径找到微信开发者工具的安装目录选择里面的cli文件或者主程序根据不同系统选择。这个配置只会做一次后面调试就很顺了。还有一点容易被忽略微信开发者工具需要开启服务端口。在微信开发者工具的设置 - 安全设置里把服务端口打开否则HBuilderX调用的时候会报错。2.2 项目目录结构与文件职责拿到源码以后先不要急着运行把目录结构看懂很重要。Uniapp脚手架的目录约定比较固定这个开源商城项目的结构如下├── pages/ # 页面目录unoapp按实际路径存储页面 │ ├── index/ # 首页 │ ├── category/ # 分类页 │ ├── cart/ # 购物车 │ ├── user/ # 个人中心 │ ├── goods/ # 商品详情 │ ├── order/ # 订单相关 │ └── login/ # 登录页 ├── components/ # 自定义组件 ├── static/ # 图片、图标等静态资源 ├── api/ # 接口请求统一封装 ├── utils/ # 工具函数 ├── store/ # 状态管理Vuex/Pinia ├── App.vue # 应用生命周期入口 ├── main.js # 入口文件 ├── manifest.json # 应用配置AppID、权限、打包配置 ├── pages.json # 页面路由、导航栏、tabBar配置 └── uni.scss # 全局SCSS变量pages.json是全局配置的核心它对标的是原生小程序里的app.json。页面路由、底部tabBar、导航栏颜色、页面窗口样式都在这里配置。开源商城项目里底部tabBar一般是首页、分类、购物车、我的这四个固定入口每个tab对应一个页面路径。manifest.json是另一个关键文件。微信小程序的AppID、H5端的标题、App端的包名和图标都在这里配置。很多新手把代码跑起来发现小程序白屏一查原因就是manifest.json里的小程序AppID还是测试号换成自己注册的AppID就正常了。2.3 关键依赖与组件库的选择商城项目里有一个绕不开的问题UI组件库用什么。开源方案常用的有uview-plus、uni-ui等。我自己在实际项目里更倾向用uview-plus这种相对完整的组件库因为商城场景里需要大量的表单、弹窗、列表、标签组件如果全手写工作量非常大。uview-plus基于Uniapp做了全端适配日历、商品规格弹窗这类组件在微信小程序和H5上表现基本一致能省下不少适配精力。装上以后项目里的很多页面可以直接用它提供的栅格和通用组件来排版。状态管理方面这版项目用的是Vue3版本所以我推荐用Pinia来管理全局状态比如用户登录态、购物车数量、用户地址等。Pinia的语法比Vuex简洁很多而且对TypeScript支持更好上手成本低。另外还有一个容易被忽略的封装request请求对象。商城系统几乎所有页面都要和后台交互所以网络请求封装必须统一。我习惯在utils目录下维护一个request.js内部封装uni.request统一做接口地址前缀拼接、token注入、返回码拦截、错误提示。这样一来业务页面里只需要调用request.get(/api/goods, params)这样的方法逻辑清爽得多。3. 商城核心功能模块实现拆解3.1 商城首页的布局与数据联动先拿首页开刀。商城首页小程序源码里首页是用户的第一个触点也是转化率最关键的一环。它的结构基本是顶部搜索栏、轮播图、金刚区图标导航、活动入口区、商品楼层。首页的布局我强烈建议用骨架屏策略。要搞清楚首页不是打开就有数据的网络请求有延迟。如果空白页面等数据回来再渲染用户大概率直接就退出了。所以在数据加载完成前先渲染出页面结构的骨架占位等数据回来再平滑替换成真实内容。首页的数据加载逻辑我在项目里是放在onLoad和onShow生命周期里处理的。onShow尤其重要因为小程序从别的页面返回首页时可能没有重新加载数据但购物车数量、登录状态可能有变化所以onShow里我一般会检查一下是否需要刷新。轮播图和金刚区这两个模块属于强配置属性。为了开源项目便于二次开发我在后端数据模型里为它们设计了配置表或者接口字段运营人员可以在后台配置轮播图片、跳转链接和图标入口。前端这边只需要渲染后端下发的数组然后做统一的跳转分发处理。跳转分发的核心是维护一个type字段比如type为1跳转商品详情、type为2跳转页面路由、type为3跳转H5链接这样灵活性会高很多。商品楼层是首页转化率最高的部分。楼层通常按分类或推荐位来切分比如热卖单品、新品首发。每个楼层内部我建议用双列瀑布流布局因为商城场景里图片高度不一致瀑布流在视觉上比普通双列更舒适。Uniapp里做瀑布流可以直接用CSS flex布局配column-count来实现也可以用css的gap搭配height自适应不需要额外引入复杂组件。3.2 登录授权与用户体系的实现细节登录模块是商城系统的真正入口也是新坑最密集的地方。先说微信小程序的登录流程。用户点击登录按钮 - 前端调用uni.login()获取临时code - 前端把code传给自己的后端 - 后端拿着code去微信接口换openid和session_key - 后端生成自己的业务token返回前端 - 前端存储token并更新登录态。这个流程里有一个关键点很容易踩坑企业主体的小程序openid需要在后端获取不能在前端直接暴露。而且session_key绝不能下发到前端否则会留下安全隐患。开源项目里后端收到的每一个请求都应该先校验token有效性而token与本地的用户信息绑定后续接口才能识别出是谁在操作。再来说一个热词里反复出现的报错小程序获取登录后的微信用户失败:wx1cb4398e1413dce7。这个报错在旧版本里很常见原因是调用了wx.getUserInfo接口但权限已经收紧。微信从2021年开始逐步调整用户授权策略头像和昵称需要用户主动点击头像昵称填写能力来获取开发者不能再用getUserInfo悄悄拿信息。正确的做法是用户授权登录后头像用button的open-type为chooseAvatar来收集昵称用input typenickname来收集。这是一个关键适配点如果不处理上架审核也会被卡。H5端和多端的登录差异也要提一下。H5里不需要走微信的code换openid流程一般用手机号验证码登录或者账号密码登录。Uniapp可以让同一套前端代码在编译时根据平台做差异处理用条件编译指令比如#ifdef MP-WEIXIN表示这段代码只在微信小程序端编译#ifdef H5则只在H5端编译。登录流程在不同端差异很大这个方案能把两套代码干净地隔离在同一份源码里。3.3 商品列表、搜索与筛选的设计商品列表页要处理的用户动作比较多查看商品、搜索、筛选、排序。开源商城项目里商品列表一般有两种展示形态网格双列或列表单列。双列适合图片为主的商品单列适合需要更多文字描述的。建议在列表页顶部提供视图切换按钮用户按需切换。搜索功能我在这里想特别说一个防抖技巧。用户输入关键字时如果每输入一个字符就向后端发请求控制台会塞满无效请求服务端压力也大。我在工具函数里封装了一个防抖方法通过定时器延迟触发用户停止输入300毫秒后才真正发起搜索请求。这是一个很小的细节但对性能体验提升非常明显。筛选部分字段一般是分类、价格区间、品牌、销量、上架时间。前端把筛选条件封装成对象统一拼到请求参数里后端做动态查询。排序逻辑我习惯把排序选项做成组件每次点击重新请求列表并重置分页。有一点要注意列表页的分页请求和筛选参数的组合要处理好否则切到第二页以后筛选条件就丢了用户翻页看到的是全量商品这种体验很劝退。详情页是商品信息的核心载体。商品主图轮播、价格、库存、规格选择、详情富文本这几个模块是标配。规格选择是一个交互复杂度较高的组件SKU库存量单位的联动判断选中规格后计算价格和库存必须保证库存不足的规格是置灰状态。很多商城系统卡在这里就是没有对SKU数据做处理。我建议用规格矩阵的方式通过多维数组组合出所有合法的SKU组合然后通过前端状态来实时计算当前选中规格是否有效这样交互流畅度和准确性都有保障。3.4 购物车、下单与订单状态流转购物车模块首先要决定是本地购物车还是服务端购物车。我的建议是未登录用户把购物车数据存在本地存储uni.setStorageSync中登录后切换成服务端购物车。这样既能保证游客可以加购又能让用户换设备不丢数据。两种方案的数据结构可以复用同一套模型只是在切换时做一次数据迁移合并。购物车页的UI逻辑比较固定商品复选框、商品缩略图、名称、规格、单价、数量增减按钮、左下角全选、右下角合计和结算按钮。关键点是勾选状态的全局联动。如果有一个子项取消勾选全选按钮要自动取消反过来全选时所有子项都要勾选。这个联动逻辑我用Vue的computed计算属性来做基于购物车列表和选中的id列表实时推导全选状态不需要手动维护更新方法简洁且不容易出bug。下单流程里确认订单页要展示收货地址、商品明细、运费、优惠金额、应付金额。前端拿到这些数据之后用户点击提交订单后端会创建订单记录并返回订单号。支付环节在小程序端是uni.requestPayment传入支付参数调起微信支付H5端则需要根据支付场景选择H5支付或扫码支付。开源项目里支付回调涉及异步通知所以订单状态不能在前端直接改成已支付要等后端收到微信支付异步通知后修改状态前端通过轮询或WebSocket来刷新订单状态这一点是很多自研商城容易埋雷的地方。订单状态流转我设计为待付款 - 待发货 - 待收货 - 已完成外加已取消和退款中状态。每个状态对应前端订单列表的不同操作按钮比如待付款显示取消订单和去支付待发货显示提醒发货待收货显示确认收货。这个状态机在后端要严格控制不能允许状态胡乱跳转比如待收货的订单不能直接变成已取消。4. 多端适配、打包与上线全流程4.1 H5端的部署与跨域处理Uniapp项目运行到H5端其实挺快但H5上线面对的坑比小程序多。最常见的是跨域问题前端页面跑在一个域名后端接口在另一个域名浏览器默认会拦截跨域请求。开发环境可以在manifest.json里配置h5.devServer.proxy把接口请求代理到后端解决开发期的跨域。生产环境更建议在后端网关层统一配置CORS允许指定域名跨域访问或者用Nginx反向代理同域转发。H5的打包配置在manifest.json - H5配置里需要设置路由模式。如果项目要部署到Nginx子目录路由模式建议用hash模式否则刷新页面会404。如果项目有独立域名且能配置Nginx的try_files规则可以用history模式URL更优雅。router base这两个参数要和实际部署路径一致否则打包后资源加载会找不到路径白屏。部署这块我遇到很多团队习惯把前端文件打包完直接扔到一个目录然后后端接口也在同一台服务器上做Nginx代理转发。这是可以的关键是Nginx配置要处理好静态资源的缓存和持久化确保商城图片更新后用户能看到新版本。推荐在静态资源文件名上加上版本号或hash值Nginx配置缓存策略时排除带有hash的文件让它们可以长缓存同时保证更新后能拉到新文件。4.2 微信小程序端的打包与审核注意事项小程序端打包比较简单HBuilderX里点击发行 - 小程序-微信编译完成后会生成一个dist/dev/mp-weixin目录用微信开发者工具导入这个目录然后上传代码。上传前需要确保manifest.json里已经填好了自己小程序平台的AppID不是测试号。小程序审核遇到的高频问题我列几个实际经验类目选择要匹配。商场类小程序需要选择电商平台类目提交时需要提供对应资质如果没有资质至少要先用商家自营类目顶上。支付方式不能是个人收款码必须走微信支付商户号否则审核会被打回。如果有用户隐私相关的接口比如获取用户位置需要在后台隐私保护指引中声明用途。小程序里不能出现诱导分享的话术分享按钮文案要合规。内容审核通过后上线版本需要发布在版本管理页操作。还有一个容易踩坑的点自定义分享好友。我在页面里用onShareAppMessage定义了分享标题、图片和路径但是预览时候分享卡片不显示或者提示fail。后来排查发现是因为分享路径里的参数没有encodeURIComponent导致特殊字符截断了。分包情况下还要保证分享路径是在已加载的分包里否则也报错。4.3 App端云打包与安卓应用市场适配Uniapp项目打包成App主要走HBuilderX的云打包能力。云打包不需要在本地安装Android SDK和Xcode而是把代码上传到DCloud的云端服务器由云端完成原生打包。这是对前端开发者非常友好的方式尤其适合没有原生开发经验的小团队。打包前manifest.json要重点配置App模块权限相机、定位、文件存储等、App图标、启动图、包名应用唯一标识。包名建议用反域名格式比如com.yourcompany.mall一旦确定后面尽量不要再改因为安卓应用市场上架后包名变更会视为新应用。安卓应用市场上架是另一个话题。国内主流市场包括华为、小米、OPPO、vivo、应用宝等每个市场需要的资质不太一样但基本都需要软件著作权证书。上架前建议用加固工具对APK做加固防止反编译。还有一点很多市场的审核会检测App内是否有强制升级模块纯后台强制升级API容易被判定为违规所以开源项目里我一般把强制升级做成可配置项默认关闭。iOS上架就更敏感一些需要Apple开发者账号且App Store审核对虚拟支付比如商城里的虚拟商品有严格限制实物商城反而问题不大。打测试包可以用云打包的自定义基座方便开发真机调试但正式上架一定用正式打包。5. 实战问题排查与经验分享5.1 微信登录拿不到用户信息怎么办这个问题的出现频率非常高很多人在群里问小程序获取登录后的微信用户失败。直接原因基本是旧接口失效加上新接口适配没到位。验证方案可以参考下面这个排查流程问题现象可能原因排查方向授权弹窗不出现未使用chooseAvatar和nickname input换成官方推荐的头像昵称填写能力code2Session返回40029小程序AppID和密钥不匹配检查manifest配置和后端微信配置获取不到openidcode换openid流程未走通后端日志查看微信接口返回用户头像昵称为空用户未主动填写把头像昵称填写按钮做成必选项新的适配交互其实更尊重用户用户点击头像组件微信弹出选择头像的界面用户点击昵称输入框输入法会弹出微信昵称快捷填充的按钮。开发者只需要把这两个组件放进个人信息编辑页用户保存后提交给后端。注意这个流程只在微信小程序端有效H5端还是传统的表单输入方式需要分别适配。5.2 uniapp打包H5出现连接服务器超时的处理还有一个热词是uniapp打包H5 出现连接服务器超时,点击屏幕重试的页面。这个其实是Uniapp的H5请求失败兜底组件。它的出现说明前端请求后端接口失败而且没有进入统一的错误回调逻辑直接触发了默认的失败页。我遇到的原因主要有三类接口跨域被拦截。后端CORS没配置好或者前端代理配置缺失。后端服务没启动或者网络不通。最常见的是本地联调前端跑在8080端口后端跑在9090防火墙拦截或者地址写错了。H5部署的静态文件在HTTPS环境但接口还走HTTP混合内容被浏览器拦截。处理方式排查的时候先把H5页面Network面板打开看请求失败的状态码。如果是CORS错误优先处理后端如果是404或者502检查接口地址和代理配置如果是混合内容拦截把接口升级到HTTPS。如果你是希望它不出现白屏可以自定义一个统一的错误页或者toast提示而不是用默认的超时页面。这种设计对用户体验很重要用户看不到控制台看到这个提示第一反应是网站挂了。5.3 小程序跳转公众号文章失败的配置小程序无法打开公众号文章,需要配置什么这个问题我答过很多次。小程序里如果要打开公众号的文章有两种方式第一种使用web-view组件嵌套公众号H5的文章链接。前提条件是mp.weixin.qq.com这个域名不能直接在web-view里使用。所有web-view打开的网址都要在小程序管理后台配置业务域名而且业务域名要求ICP备案并且需要在对应域名下放校验文件。第二种如果只是跳转到公众号的一个文章页其实也可以用客服消息或者订阅消息引导用户把文章链接发送给用户用户在微信环境里直接打开。这个方式绕开了web-view的域名限制也是一种实用方案。对于百度小程序嵌套h5类似场景机制基本一样只是嵌套的域名需要走对应平台的域名配置流程。商城系统里活动页、内容页、帮助中心这类页面如果以H5形式承载务必提前规划好域名把域名配置流程放到项目开发初期就搞定不然到上线前才发现域名还在备案流程里那就被动了。5.4 renderjs视频播放与自定义分享的细节坑热词里提到了uniapp renderjs 手机录得mp4无法播放。这个问题通常发生在H5端通过renderjs去处理视频播放的场景。renderjs可以把一部分逻辑运行在视图层解决跨端的一些渲染问题但视频播放对编码格式是有要求的。手机录制的视频常常是H.265编码或者带有特殊音轨浏览器默认播放支持并不好。解决方案有几个一是强制转码在上传视频的时候统一转成H.264编码加AAC音轨的MP4这是兼容性最稳的方案二是后端做视频切片用HLS或者DASH流媒体格式播放移动端的兼容性会更好三是前端播放器用video组件时设置好playsinline和x5-playsinline等属性避免浏览器调用原生播放器带来的兼容差异。商城商品详情里嵌入视频最好统一走视频转码服务不要让用户直传原始文件。另一个细节是自定义分享好友的参数。分享不只是分享一个页面链接它需要带上分享者信息比如分销场景里要带分享者的userId这样被分享的人通过链接进入商城系统才能把关系链记录下来。实现细节是onShareAppMessage返回的path里拼接参数参数值一定要encodeURIComponent编码拿到参数的目标页面在onLoad的options里解码然后处理好特殊字符。这个坑很小但影响很大因为分销关系链一旦对不上推广体系就废了。再提一下微信小程序的页面栈问题商城小程序从首页进详情页再跳转H5专题页然后H5里又要跳App下载页面这个流程里页面栈的层数会不断加深。小程序原生页面栈最多支持10层超过之后跳转会被忽略或报错。常规处理是在需要深跳的地方用uni.reLaunch或uni.redirectTo替换当前页面不要一直uni.navigateTo叠加。像首页到详情页这种高频跳转尽量合理控制页面栈的生命周期避免not found:page奇怪的报错。6. 给正在做开源商城项目的团队一点建议最后聊点实在的。一个开源商城项目的成功上线技术只占一半另一半是梳理清楚业务边界。如果你打算拿这套Uniapp商城系统做二次开发我的建议是先稳住主链路再去加花活。先把登录、商品浏览、加购、下单、支付、订单查询这一条线调通在这条线没有稳定之前不要往系统里塞分销、直播、秒杀这类重型功能。我见过太多项目毁在需求一直膨胀代码结构越来越乱最后连最基础的下单都出了bug用户购物车清空、订单支付回调迟迟不到账这种体验简直是自杀。另一个经验是接口层的设计一定要稳定。前端和后端约定好统一的数据返回格式比如{ code: 0, data: {}, message: success }这样前端错误拦截器才能统一处理。如果每个接口返回数据结构都不一样前端就要到处写分支判断后期维护成本直线上升。后端接口的异常处理也要细致。商城场景里库存不足、价格变动、优惠券过期这些都需要后端校验后给出明确提示前端把错误信息清楚展示给用户。不要只在控制台打日志用户不知道发生了什么只会觉得你的商城系统不靠谱。关于开源项目的部署和上线团队在开发初期就应该把上线路径定下来。小程序端的AppID注册、业务域名备案、支付商户号申请这些前置条件周期都不短有的甚至要一两周。不要等代码写完才发现商户号还没下来。还有一个容易被忽视的点日志与监控。商城系统一旦有真实用户接入线上问题排查就必须靠日志。建议在后端接口层统一记录请求参数和返回结果前端也要有对应的错误上报机制。这样用户在哪个页面、哪个接口出了问题排查起来才能有的放矢。这套开源商城系统作为学习项目它的代码量适中模块边界清楚适合完整读一遍。作为商用项目它的骨架足够稳定可以按要求改造UI和业务。我实际跑过之后最大的感受是Uniapp的开发效率确实在线尤其是多端覆盖的场景省下的工程量不是一点半点。但框架只是工具商城的核心还是你对业务的理解对用户购物体验的把控。技术细节可以慢慢磨业务方向不能偏。如果你正准备基于这套源码做自己的商城先动手把开发环境跑起来把首页和登录两个模块读透剩下的事情就会顺利很多。遇到具体的问题也欢迎带着报错信息来交流我把遇到过的问题都整理在这篇里了希望你少走一些弯路。
