Claude Code 实战一从零开发电商小程序全流程提到 AI 编程很多人第一反应还是拿它补几行函数、改个样式、写点注释。但我这次想做点更硬的验证完全用 Claude Code 这个命令行 AI 编程工具在不提前写一行业务代码的前提下从零开发一个电商小程序。不是玩具 Demo而是包含用户登录、商品展示、购物车、下单、订单管理、后台数据统计的完整闭环。最后的结果超出了我的预期——整个项目从初始化到拿到可体验版本用了不到两天而且代码质量让我这个有十年开发经验的人都觉得“这活儿干得确实可以”。这篇文章我会把完整的实战过程拆开来讲项目怎么初始化、Claude Code 的工作流怎么跑、核心模块商品、购物车、订单、用户是怎么一步步实现的、遇到了哪些坑、怎么排查。全程零基础也能跟着走有经验的开发者同样能从里面的技术选型和架构设计里拿到东西。1. 项目整体设计与 Claude Code 工作流1.1 为什么选 Claude Code 而不是其他 AI 编程工具先说结论Claude Code 在“复杂多文件工程类任务”上的表现是目前我用过的 AI 编程工具里最接近“结对程序员”的。和普通的对话式 AI 不同Claude Code 运行在终端里能直接读写你项目里的文件、执行命令、跑测试、看报错信息然后自己决定接下来改哪些代码。这意味着它不是“你问一句它答一句”而是“你给它一个目标它自己拆解任务、动工、验证、收尾”。比如我说“帮我建一个微信小程序项目原生框架支持商品列表和详情页”它会先去读微信小程序的项目结构规范然后自己创建 app.json、app.js、app.wxss、页面目录、组件目录生成完整代码。这个过程中你随时可以打断、纠正、要求修改。1.2 项目定位一个什么级别的电商小程序为了避免“看着像样但根本跑不通”的空中楼阁我定了几个硬指标前端微信小程序原生框架WXML WXSS JS JSON不依赖第三方 UI 库后端微信云开发云函数 云数据库 云存储免服务器部署功能范围用户登录态、首页商品瀑布流、商品详情、SKU 选择、购物车增删改、下单、订单状态流转待支付/已支付/已发货/已完成、订单列表、个人中心数据层所有商品数据、订单数据、用户数据全部走云数据库图片走云存储管理侧一个简单的后台管理页面云函数实现能查看商品列表、订单统计、手动发货选择原生框架和云开发是因为这套组合最贴近微信生态的真实开发方式不需要租服务器、配域名、搞备案。对个人开发者和小团队来说这是性价比最高的起步方案。1.3 Claude Code 的核心协作模式Plan 先行用 Claude Code 做项目和传统开发最大的不同是先规划后编码。我在项目根目录下新建了一个docs/文件夹第一件事不是让它写代码而是让 Claude Code 输出三份文档docs/01-项目结构.md整个小程序的文件目录设计docs/02-数据库设计.md所有数据集合Collection及其字段结构docs/03-页面与接口清单.md每个页面包含什么功能每个云函数提供什么接口这个习惯帮了我大忙。因为 Claude Code 上下文窗口再大也是有限的如果你不在一开始把架构定下来后面它写代码时很容易前后矛盾——前面定义的商品字段后面详情页就取了另一个字段名。实际对话命令参考请先阅读微信小程序原生开发和云开发的官方文档要点 然后基于电商小程序的常见需求在 docs/ 目录下设计完整的技术方案 包括目录结构、数据库 collections 设计、页面列表和云函数接口清单。 设计完成后请总结给我确认。它会先用 claude 命令读官方文档结构、梳理需求然后生成方案文件。我检查之后觉得数据库设计里缺少“优惠券”相关字段直接回复“现在不需要优惠券功能但请预留字段”它立刻更新所有设计文档并保持关联文件同步。2. 关键技术选型与架构决策2.1 原生框架 vs 第三方跨端框架做小程序绕不开的第一个选择就是技术栈原生小程序、Taro、uni-app还是别的我最终选了原生框架理由有三个Claude Code 对微信原生框架的代码模式学习得最透彻翻车概率最低原生框架不需要额外编译链出问题时更容易定位AI 生成的代码里编译错误最容易让人头疼小程序原生已经是跨端了iOS/Android/微信PC没必要为了多端复用再套一层框架如果你是团队已有前端基础、打算以后同时做 App 和 H5Taro/uni-app 确实可以。但对本项目的目标是快速落地、逻辑清晰、最大化利用 AI 能力原生框架是最优解。2.2 云开发省掉后端服务端的全部脏活云开发这个决策节省了我至少两天工作量。传统模式你需要搞一台服务器哪怕是便宜的云主机装数据库、写后端 API、配接口鉴权、处理图片上传。云开发直接把这三件事打包了云数据库文档型数据库类似 MongoDB支持权限控制云函数Node.js 运行环境直接在函数里操作数据库、调用微信开放能力云存储存商品图片、用户头像等静态资源自带 CDN本地开发时微信开发者工具里可以一键开通云开发环境写好的云函数右键就能上传部署数据库可以直接在开发者工具里可视化编辑。整个流程几乎没有“脱离微信生态”的操作非常顺滑。2.3 数据模型设计先想清楚集合再动手数据库设计可以说是我这个项目里收益最高的一环。Claude Code 在 docs/02-数据库设计.md 里给出了 6 个集合我们逐个过一遍集合名用途关键字段goods商品信息name, price, images, stock, category, sales, detail, skusku商品规格库存goodId, spec, price, stockusers用户信息openid, nickName, avatarUrl, addressListcart购物车条目openid, goodId, skuId, quantity, checked, updateTimeorders订单信息orderNo, openid, items, totalPrice, status, address, createTimebanners首页轮播图image, linkType, linkUrl, sort这里有个关键设计思想值得说购物车和订单都存了“商品快照”。具体来说orders 里的 items 数组里每个商品除了 goodId 之外还会冗余存一份商品名、图片、单价、规格描述。为什么因为商品信息是可变的——价格会调、图片会换、商品可能下架。订单一旦生成记录的应该是“下单那一刻的商品状态”而不是“当前商品的实时状态”。下单后再去查商品表取到的可能是涨价后的价格用户就有理由投诉了。我把这个原因讲给 Claude Code 听之后它自动在数据校验里给订单快照加了一个snapshot: true的标识字段细节拉满。2.4 云函数拆分原则电商类应用最核心的判断是哪些逻辑必须放服务端哪些可以放前端我的原则是涉及钱、库存、数据写权限的操作一律走云函数。前端可以只负责展示和基础交互。具体拆分login接收前端传的登录凭证调用微信接口换取 openid查询或创建用户记录返回用户信息getGoodsList分页获取商品列表支持分类筛选和排序getGoodsDetail读取商品数据 对应 SKU 列表addCart/updateCart/deleteCart购物车增删改校验商品是否上架createOrder核心云函数做库存扣减、生成订单号、计算总价、创建订单记录getOrderList按用户和状态查询订单列表updateOrderStatus模拟支付、发货操作getAdminStats后台统计返回商品数、订单数、销售额、待发货订单数核心原则一句话前端永远不要去操作另一个用户的数据也不要做和钱、库存相关的关键判断。比如购物车数量、订单金额的前端显示只做展示下单时云函数会重新从数据库读取价格、重新计算总价任何前端篡改都是无效的。3. 全流程实操从 0 搭建一套可运行的电商小程序3.1 环境准备装好三样东西动手之前先把环境配齐微信开发者工具稳定版即可注意登录时选择“小程序模式”而非“公众号模式”Node.js 16云函数本地调试要用Claude Code CLI如果你是 npm 安装npm install -g anthropic-ai/claude-code我在项目目录下直接执行claude命令进入交互模式。第一件事不是写代码而是先通过对话设定项目的“宪法”文件。我让 Claude Code 在项目根目录生成了一份CLAUDE.md内容包含项目技术栈、目录约定、命名风格页面文件用 camelCase、数据库操作规范必须用云函数、前端不得直连数据库写操作、注释规范中文注释。这份文件的作用是让 AI 在后续每一次对话里都能读取项目约定不跑偏。3.2 初始化项目骨架让 AI 自己搭架子如果手动搭小程序骨架你需要手动创建数十个文件app.json、pages 目录、每个页面的四件套wxml、wxss、js、json、utils、components……我用一条指令搞定请基于原生微信小程序 云开发的技术栈初始化整个项目骨架。 包含 app.json、app.js、app.wxss、project.config.json、sitemap.json 以及以下页面home(首页)、goods/detail(商品详情)、cart(购物车)、 order/confirm(确认订单)、order/list(订单列表)、user(个人中心)、admin(管理后台)。 每个页面生成四件套文件。云开发环境变量统一放在 config/index.js 里。 创建完成后请用 tree 命令列出项目结构让我确认。它用了不到五分钟就把所有文件生成完毕并给出了目录树. ├── CLAUDE.md ├── app.js ├── app.json ├── app.wxss ├── config/ │ └── index.js ├── pages/ │ ├── admin/ │ ├── cart/ │ ├── goods/ │ ├── home/ │ ├── order/ │ └── user/ ├── utils/ │ ├── auth.js │ ├── cart.js │ └── format.js ├── cloudfunctions/ │ ├── addCart/ │ ├── createOrder/ │ ├── deleteCart/ │ ├── getAdminStats/ │ ├── getGoodsDetail/ │ ├── getGoodsList/ │ ├── getOrderList/ │ ├── login/ │ ├── updateCart/ │ └── updateOrderStatus/ └── project.config.json唯一要手动操作的是在微信开发者工具里导入项目目录并把project.config.json里的cloudfunctionRoot指向cloudfunctions/然后开通云开发。3.3 首页商品流从数据库到界面的完整链路首页是电商门面我要求的效果是商品卡片两列流式排列、顶部有分类 tab、支持下拉刷新和触底加载下一页。数据库里手工 seed 了 16 件商品数据商品图片我临时用了几张本地图上传到了云存储真实项目建议用图床 云存储做 CDN 加速。首页用到的核心云函数是getGoodsList。我让 Claude Code 实现时特别要求它做到支持分类筛选all / 数码 / 服饰 / 食品 / 家居支持排序切换综合 / 销量 / 价格升序 / 价格降序使用skip limit分页单次返回 10 条返回的每条商品数据必须包含id、name、price、images[0]封面图、sales、stock实际生成的云函数核心逻辑简化后大概长这样const cloud require(wx-server-sdk) cloud.init({ env: cloud.DYNAMIC_CURRENT_ENV }) const db cloud.database() const _ db.command exports.main async (event) { const { category all, sort default, page 1, pageSize 10 } event const dbCmd db.command // 构建查询条件 let where {} if (category ! all) { where.category category } where.status dbCmd.neq(offline) // 状态不等于下架 const countRes await db.collection(goods).where(where).count() const total countRes.total const totalPages Math.ceil(total / pageSize) // 构建排序 let orderBy {} switch (sort) { case sales: orderBy { sales: desc } break case priceAsc: orderBy { price: asc } break case priceDesc: orderBy { price: desc } break default: orderBy { createTime: desc } } const goodsRes await db.collection(goods) .where(where) .orderBy(Object.keys(orderBy)[0], Object.values(orderBy)[0]) .skip((page - 1) * pageSize) .limit(pageSize) .get() return { code: 0, data: { list: goodsRes.data, page, pageSize, total, totalPages, hasMore: page totalPages } } }首页前端拿到数据后渲染两列瀑布流。这里 Claude Code 用了一个小技巧用 CSS (column-count: 2) 实现瀑布流效果而不是传统的 flex 双列。好处是实现简单、高度自动排列代价是数据顺序会变成“先左列满再右列”。实测下来视觉差异不大商品卡片高度本身就不统一瀑布流观感反而自然。注意云函数里排序字段一定要确认数据库里建了索引否则数据量大之后会有性能问题。云开发控制台里对goods集合的category status createTime建一个联合索引就好了。3.4 商品详情与 SKU 选择最考耐心的部分商品详情页是整个小程序里交互最复杂的部分。它涉及顶部轮播图商品多图滑动价格、销量、库存展示SKU 规格选择比如颜色、尺码加入购物车 / 立即购买两个动作底部操作栏吸底SKU 的数据库结构是sku集合每个 SKU 记录对应一个商品的一种规格组合{ goodId: g_1001, spec: [黑色, M码], price: 199, stock: 50, image: cloud://xxx/black-m.png }前端拿到商品详情和全部 SKU 后就需要实现一个“SKU 选择面板”——点击颜色和尺寸只有当某个组合仍有库存时才能选中否则置灰。这个逻辑我让 Claude Code 写了一个独立 util 封装核心代码function getSkuByCombination(skuList, selectedSpecs) { // 过滤掉未选择的维度 const activeSpecs Object.values(selectedSpecs).filter(Boolean) // 找到所有包含当前选中规格组合的 sku按数组长度降序匹配 const matches skuList .filter((sku) activeSpecs.every((spec) sku.spec.includes(spec))) .sort((a, b) b.spec.length - a.spec.length) return matches[0] || null } function getAvailableSpecs(skuList, selectedSpecs, specGroupIndex) { // 当前维度外已选中的规格 const lockedSpecs selectedSpecs.filter((spec, idx) idx ! specGroupIndex spec) return skuList .filter((sku) lockedSpecs.every((spec) sku.spec.includes(spec))) .flatMap((sku) sku.spec[specGroupIndex]) }逻辑本身不算难但实现中有一个容易踩的坑选中 SKU 后价格显示和加入购物车用的 skuId 必须来自同一个 SKU 对象。我一开始就让 Claude Code 把选中状态selectedSku统一定义为整个 sku 对象而不是只存 skuId否则库存校验时会出现查不到对应 SKU 的情况。加入购物车时云函数addCart会接收goodId skuId quantity然后做三件事校验商品存在且未下架校验 SKU 存在且库存足够检查购物车是否已有同款同用户 同商品 同 SKU有则合并数量无则新建条目这样购物车数据不会膨胀用户操作体验也顺滑。3.5 购物车设计一个不惹事的模块购物车的坑不在“增删改查”本身而在细节状态管理。我的页面结构是顶部有全选按钮每个商品项有勾选框、数量步进器、左滑删除原生自带的movable-view或长按删除。底部有一个悬浮结算栏实时显示“已选 N 件合计 ¥XXX”点击结算跳转到确认订单页。为了让 Claude Code 实现的购物车在前端保持状态一致我要求它把购物车逻辑封装到一个独立的utils/cart.js模块里页面只做渲染和事件绑定。模块暴露这些方法getCartList()从云函数拉取购物车列表同时合并实时商品信息商品图、名称、单价updateCheckedStatus(cartId, checked)更新单个条目的选中态selectAll(checked)全选 / 取消全选changeQuantity(cartId, delta)数量加减removeItem(cartId)删除getSelectedTotal()计算已选商品的总价其中有一个细节很关键购物车列表里的商品价格必须实时从商品表里读而不是购物车条目里存死价格。因为用户加购之后商品可能调价了。你购物车显示的价格是旧的结算时却用新价格用户会骂人。Claude Code 的实现方式是拉取购物车列表后批量根据 goodId 去查询商品表的最新价格、名称、图片、库存状态组装后返回前端。若商品已下架前端显示“已失效”且不允许勾选。整个购物车的状态管理逻辑Claude Code 一次写对我都没怎么改。唯一手动调整的是当购物车全选状态下删除最后一件商品时底部结算栏要自动切到“未全选”状态。这是典型的前端状态副作用测试时注意别漏。3.6 创建订单库存扣减的正确姿势createOrder是整个系统里我最看重的云函数因为它是资金和库存流转的关口。订单生成的完整流程前端从购物车把勾选的cartIds传给云函数云函数从数据库读取购物车条目然后根据goodId skuId读取商品和 SKU 的当前数据逐个校验商品状态计算总价以数据库实时价格为准生成唯一订单号格式yyyymmddHHMMSS 6位随机数 用户标识后3位执行库存扣减sku.stock - 数量校验扣减后不为负数生成订单记录订单状态置为pending_payment记录商品快照和地址快照清空对应购物车条目返回订单号和前端展示的订单详情关键点在第三步和第五步。Claude Code 写这段逻辑时一开始用的是“先读库存判断 数量再写入新库存”的普通方式。我直接指出如果两个用户同时下单同一件商品同时读到库存 5都判断可以扣减都写入 4最终数据就错了。库存超卖是电商大忌。我让它改用事务transaction来保证原子性。云开发数据库支持事务操作把“判断库存并扣减”包在一个事务里只有事务提交成功后才算抢购成功。改造后的关键代码const transaction await db.startTransaction() try { const skuRes await transaction.collection(sku).doc(skuId).get() const sku skuRes.data if (!sku || sku.stock quantity) { throw new Error(库存不足) } await transaction.collection(sku).doc(skuId).update({ data: { stock: sku.stock - quantity } }) // ... 写入订单等其他操作 await transaction.commit() } catch (err) { await transaction.rollback() throw err }这段代码是整篇项目里含金量最高的部分之一。电商系统里“并发导致的库存超卖”是最典型的线上事故新手往往在“单用户测试通过”之后就以为完事了忽略了并发场景。用事务之后同一时间只有一个事务能成功扣减库存其他请求要么拿到库存不足、要么等待重试数据安全有了兜底。提示云开发事务对操作次数有限制默认不超过 100 次我们单笔订单操作次数远低于上限放心用。3.7 订单列表与状态流转订单状态我定义了五个pending_payment待支付、paid已支付、shipped已发货、completed已完成、cancelled已取消。getOrderList云函数支持按照状态筛选返回的每笔订单里包含订单号、创建时间、总价、状态商品快照数组图片、名称、单价、数量、规格收货地址脱敏显示手机号中间四位打码物流信息发货后有物流单号前端做了三个 tab全部、待支付、已发货。待支付订单有“取消订单”和“模拟支付”按钮已发货订单有“确认收货”按钮。模拟支付的实现非常实用点击后调用云函数updateOrderStatus传入orderNo status: paid云函数校验订单归属人确为当前用户后把pending_payment改为paid。这里的订单归属人校验也可以看作是写这类云函数的基本功。同时在orders集合上创建了openid status的索引确保查询效率。3.8 个人中心与后台统计个人中心页面展示用户头像、昵称、地址管理入口、订单状态入口以及一个“我是管理员”的入口真实项目建议用管理员 openid 白名单控制。后台统计页调用了getAdminStats云函数基于多个集合的聚合查询返回商品总数总订单数总销售额已支付 已发货 已完成订单的总价待发货订单数按分类统计的商品数量分布这些数据只在管理后台展示所以我对getAdminStats做了一层简单的 openid 判断只有配置里的管理员 openid 才能调用成功。4. 联调、测试与常见问题排查实录4.1 联调中的三个典型报错整个开发过程中不可能每一步都顺利。我整理了三个最有代表性的坑希望能帮你避雷。第一个坑云函数调用一直超时控制台报Function not found原因基本可以锁定为云函数文件已上传到本地云端但云端环境没有部署成功或者环境 ID 不匹配。解决步骤是在微信开发者工具的资源管理器中右键云函数目录选择“上传并部署云端安装依赖”确认云开发环境 ID 与config/index.js里配置的一致在云开发控制台检查云函数列表确认函数名正确第二个坑数据库权限失控前端直接读到了所有用户的订单这属于云开发新手最容易犯的错。数据库默认权限是“仅创建者可读写”但如果配置成“所有用户可读”任何用户都能遍历别人数据。我的处理方案前端只读商品、Banner 这类公共数据涉及用户的cart/orders/users集合权限一律设置为“仅创建者可读写”并且所有写操作必须走云函数。云函数里通过cloud.getWXContext().OPENID拿到当前用户身份查询时强制带上 openid 条件双保险。第三个坑本地开发一切正常真机预览时图片加载失败原因是云存储的图片链接默认带环境 ID本地调试环境和你线上预览的环境可能不是同一个。我统一用fileID传给前端image标签组件内部用wx.cloud.getTempFileURL来换取临时链接。或者干脆配置一个全局变量在切换环境时自动更新存储域名。4.2 常见问题速查表问题现象可能原因解决方案云函数调用报FunctionName not found云函数未部署或部署失败右键重新上传检查环境 ID小程序页面空白app.json 的 pages 列表遗漏页面检查注册页面路径数据重复展示分页参数没带上确认 skip 使用(page-1)*pageSizeSKU 选择后价格不变选中状态未关联 SKU选中对象改为整个 SKU 对象库存扣成负数未使用事务操作改用事务包裹库存扣减逻辑真机图片 404存储环境不一致使用 fileID getTempFileURL订单列表显示别人的订单权限设置过宽数据库权限改为仅创建者可读写4.3 实测表现与性能优化整个项目完成后的实测首页首屏加载约 0.8 秒开发环境云函数响应稳定在 300ms 以内购物车连续添加 20 件不同类型商品无卡顿模拟两个账号同时抢购同一 SKU 的最后 1 件库存只有一个能成功下单另一个正确提示“库存不足”——这是事务生效的表现主体代码量前端页面 云函数总计约 4500 行其中 Claude Code 生成约 90%我手动调整约 10%如果想进一步压缩启动时间可以在app.js里把云开发初始化提前并缓存部分不常变的商品分类 / Banner 数据到本地 storage。商品列表页也可以加一个骨架屏体验会更好。这些优化动作和 Claude Code 协作实现都很方便基本上你一句“首页加个骨架屏”它就能帮你搞定。5. 关于 AI 协作的一点个人心得项目跑通那一刻的爽感说实话比手写代码来得更强烈一些。但使用 Claude Code 代打并不是躺平恰恰相反它把我从写代码里腾出来把精力投入到更重要的判断上架构怎么定、模块怎么切、哪些逻辑必须做严、哪些坑不能踩。几天的实战下来我最大的感受是你问得越清楚它给你的东西越靠谱。拼多多式的需求描述只能得到拼多多式的代码但条例清晰的需求比如“库存扣减必须用事务”、“用户数据只能走云函数”它就能按工程标准执行。在代码安全和数据一致性的关键问题上AI 不会主动替你兜底具体怎么设计判断权始终在你手里。如果你打算自己上手试我的建议是不要从电商这种中大型项目开始先拿一个 500 行的小工具练手跑通一遍整个流程初始化、生成、调试、修改之后再来搞电商这种多模块项目。等踩过一两轮坑你会发现这个东西真的能成为你的另一个开发搭子。
