uni-app小程序商城实战：从0到1

去年冬天，一位在北京做社区生鲜的客户找到知码客，想做一个覆盖周边三公里、支持自提和同城配送的小程序商城。我们用了三周时间，基于 uni-app 从零搭建了一套可复用的商城模板。这篇文章把从 0 到 1 的完整过程拆开讲，包括踩过的坑和最终沉淀下来的代码结构。

一、为什么选 uni-app 而不是原生

客户初期只要求微信小程序，但线下运营团队提到未来可能做 App 做会员沉淀。如果直接写原生小程序，后续做 App 等于重写一遍。uni-app 的编译能力让我们用一套代码同时输出微信小程序和 App，这对预算有限的本地商家非常关键。北京小程序开发市场里，很多团队为了省事只做单端，结果客户第二年想加 App 时成本翻倍。

二、项目初始化与目录设计

用 HBuilderX 创建项目后，我习惯先规划目录，而不是急着写页面。商城类项目页面多、状态杂，目录乱掉后期维护成本极高。

src/
  pages/          # 主包页面：首页、分类、购物车、我的
  pagesSub/       # 分包：订单详情、售后、地址管理
  components/     # 商品卡片、规格弹窗、数量步进器
  store/          # pinia 状态：购物车、用户、地址
  api/            # 请求封装与接口定义
  utils/          # 价格格式化、防抖、埋点
  static/         # 本地图片与图标

分包这一步很关键。微信小程序主包限制 2MB，商城首页加分类页很容易超标。把订单、售后、地址这类低频页面放进分包，首屏加载明显变快。

三、核心页面开发顺序

1. 商品列表与卡片组件

先做商品卡片，因为首页、分类、搜索、推荐位都会复用它。卡片组件只接收 goods 对象，内部处理图片懒加载、价格显示和售罄状态。

<template>
  <view class="goods-card" @click="goDetail">
    <image :src="goods.cover" mode="aspectFill" lazy-load />
    <view class="info">
      <text class="name">{{ goods.name }}</text>
      <text class="price">¥{{ formatPrice(goods.price) }}</text>
    </view>
  </view>
</template>

2. 购物车与规格弹窗

购物车是商城最容易出 bug 的地方。多规格商品（颜色、重量）需要把用户选择映射成唯一的 skuId，再和购物车条目做匹配。我用 pinia 存购物车，本地持久化用 uni.setStorageSync，保证退出小程序再进来数据还在。

3. 下单与支付

下单流程：确认订单页 → 创建订单接口 → 调起微信支付 → 支付结果页。注意微信支付的回调是异步的，不能只依赖前端 success，必须在后端做支付状态轮询或回调校验，否则会出现用户付了钱但订单显示未支付。

四、北京本地场景的两个细节

• 同城配送范围校验：客户只送周边三公里，下单时用收货地址经纬度和门店坐标算距离，超出范围直接拦截。北京城区跨度大，不做这个校验会出现五环外的订单没法送。
• 自提点选择：北京很多社区店面积小，自提点就是门店本身。我们在订单页加了自提时间选择，避开午晚高峰，减少门店压力。

五、上线前必须检查的清单

1. 主包体积是否低于 2MB，分包是否配置正确
2. 所有接口是否做了 loading 和失败兜底
3. 微信支付是否配置了合法域名和商户证书
4. 商品图片是否走了 CDN，避免小程序包体过大
5. 隐私协议和用户授权弹窗是否合规

六、从 0 到 1 之后

这个商城上线两个月，日均订单稳定在两百单左右。后来我们又基于同一套结构，给北京另一家做烘焙的客户快速改了一版，只替换了主题色、首页楼层和配送逻辑，两周就交付了。这也是知码客一直坚持的做法：把每个项目当成可沉淀的资产，而不是一次性交付。北京APP开发和小程序定制需求往往变化快，代码结构清晰，后续加功能才不会痛苦。

如果你也在北京做小程序开发，或者正打算从零搭一个商城，希望这篇实战记录能帮你少走一点弯路。知码识途，匠心铸客，每一行代码都是和用户沟通的语言。