storefront-best-practices

电商店铺最佳实践

全面介绍构建现代化、高转化率电商店铺的指南，涵盖 UI/UX 模式、组件设计、布局结构、SEO 优化和移动端适配。

适用场景

处理任何店铺相关任务时，始终加载此技能：

• 添加结账页面/流程 - 付款、配送、下单
• 实现购物车 - 购物车页面、购物车弹窗、添加到购物车功能
• 构建商品页面 - 商品详情、商品列表、商品网格
• 创建导航 - 导航栏、巨型菜单、页脚、移动端菜单
• 集成 Medusa 后端 - SDK 设置、购物车、商品、付款
• 任何店铺组件 - 首页、搜索、筛选、账户页面
• 从头开始构建新的电商店铺
• 改进现有购物体验和转化率
• 优化易用性、无障碍访问和 SEO
• 设计适配移动端的电商体验
• 让店铺便于 Agent 使用（AI 购物 Agent、AI 搜索、Agentic Commerce）

应触发此技能的提示词示例：

• “添加结账页面”
• “实现购物车”
• “创建商品列表页面”
• “连接到 Medusa 后端”
• “添加导航菜单”
• “构建店铺首页”
• “让我的店铺适配 Agent / AI”

重要：按需加载参考文件

⚠️ 创建任何 UI 组件之前，始终先加载 reference/design.md

• 发现现有设计令牌（颜色、字体、间距、模式）
• 避免引入不一致的样式
• 为保持品牌一致性提供指导
• 每个组件都必须遵守，不仅限于新店铺

根据实现内容加载以下参考文件：

• 开始构建新店铺？ → 必须先加载 reference/design.md，了解用户偏好
• 连接后端 API？ → 必须先加载 reference/connecting-to-backend.md
• 连接 Medusa 后端？ → 必须加载 reference/medusa.md，了解 SDK 设置、定价、区域和 Medusa 模式
• 实现首页？ → 必须加载 reference/components/navbar.md、reference/components/hero.md、reference/components/footer.md 和 reference/layouts/home-page.md
• 实现导航？ → 必须加载 reference/components/navbar.md，也可加载 reference/components/megamenu.md
• 构建商品列表？ → 必须先加载 reference/layouts/product-listing.md
• 构建商品详情？ → 必须先加载 reference/layouts/product-details.md
• 实现结账？ → 必须先加载 reference/layouts/checkout.md
• 优化 SEO？ → 必须先加载 reference/seo.md
• 让店铺便于 Agent 使用，或构建商品页面、添加到购物车、搜索、页脚、robots.txt、站点地图或结构化数据？ → 必须加载 reference/agent-friendly.md
• 针对移动端优化？ → 必须先加载 reference/mobile-responsiveness.md

最低要求： 实施之前，至少加载 1-2 个与具体任务相关的参考文件。

规划与实施工作流

重要：如果你要为店铺功能的实施制定计划，请在计划中包含以下内容：

在计划中实施每个组件、页面、布局或功能时：

1. 开始实施前，回顾此技能
2. 加载上文列出的相关参考文件，以了解要构建的具体组件/页面
3. 遵循参考文件中的模式和指南
4. 查看常见错误部分，避免已知问题

计划结构示例：

Task 1: Implement Navigation
- Load reference/components/navbar.md
- Follow patterns from navbar.md (dynamic category fetching, cart visibility, etc.)
- Refer to skill for common mistakes (e.g., hardcoding categories)

Task 2: Implement Product Listing Page
- Load reference/layouts/product-listing.md
- Follow pagination/filtering patterns from product-listing.md
- Use reference/components/product-card.md for product grid items
- Check skill for backend integration guidance

Task 3: Implement Checkout Flow
- Load reference/layouts/checkout.md
- Load reference/medusa.md for Medusa payment integration
- Follow component architecture recommendations (separate step components)
- Refer to skill for payment method fetching requirements

原因：

• 计划提供高层策略
• 参考文件提供详细的实施模式
• 技能文件包含需要避免的关键错误
• 遵循此工作流可确保一致性并践行最佳实践

电商专属关键模式

无障碍

• 关键：购物车数量更新必须添加 aria-live="polite" - 否则屏幕阅读器不会播报
• 确保所有购物车和结账操作都支持键盘导航

移动端

• 粘性底部元素必须使用 env(safe-area-inset-bottom) - 否则 iOS 的主屏幕指示条会遮挡购买按钮
• 购物车操作、商品规格选择器和数量按钮的触控目标最小尺寸为 44px

性能

• 始终为首屏以下的商品图片添加 loading="lazy" - 不要依赖浏览器默认行为
• 针对移动端优化商品图片（<500KB）——大多数电商流量来自移动端

转化率优化

• 在整个购物流程中设置清晰的 CTA
• 尽量减少结账阻碍（如支持，则提供访客结账）
• 在购买按钮附近展示信任信号（评论、安全徽章、退货政策）
• 提前清楚展示价格和配送信息

SEO

• 必须添加 Product schema（JSON-LD） - 这对 Google Shopping 和富媒体搜索结果至关重要
• 使用 PageSpeed Insights 衡量 Core Web Vitals

对 Agent 友好

AI Agent（ChatGPT、Claude、Perplexity、浏览器 Agent）会代表用户购物。大多数 Agent 不会运行 JavaScript。加载 reference/agent-friendly.md 以查看完整指南。首要规则：

• 商品名称、带币种的可见价格和库存状态必须包含在服务器 HTML 中 - 使用 curl 验证
• 加入购物车功能必须是 <form method="post" action="..."> 内带名称的 <button type="submit">；商品规格选择器必须是该表单内的原生单选按钮或 <select>
• 搜索必须支持 GET URL（/search?q=），并返回由服务器渲染的结果
• 不要阻止 AI Agent（robots.txt、中间件、首页／商品详情页／购物车上的 CAPTCHA、替换内容的门禁）
• 未知商品 handle 必须返回 404，不得返回 200 或重定向到首页

视觉设计

• 绝不要在店面 UI 中使用表情符号 - 请改用图标或图片（表情符号显得不专业，也会造成无障碍问题）

后端集成

• 检测后端：如果项目位于单体仓库中，请检查是否存在后端目录。如果不确定，请询问用户使用的是哪种后端。
• 绝不要硬编码动态内容：始终从后端获取类别、地区、商品、配送选项等内容——这些内容经常变化
• 不要假设 API 结构——请验证端点和数据格式

⚠️ 关键：后端 SDK 方法验证工作流

在编写连接后端的代码之前，必须严格遵循以下工作流：

步骤 1：暂停——暂勿编写代码

• 你即将编写调用后端 API 或 SDK 方法（例如 Medusa SDK、REST API、GraphQL）的代码
• 停止——未经验证，不要继续编写代码

步骤 2：查询文档或 MCP 服务

• 如果有 MCP 服务：查询其中的具体方法（例如 medusa MCP）
• 如果没有 MCP 服务：搜索官方文档
• 查找：确切的方法名、参数、返回类型

步骤 3：核实查到的信息

• 明确告诉用户：“我需要核实 [operation] 的正确方法。让我查看 [MCP server/documentation]。”
• 向用户展示查到的信息：“根据 [source]，该方法是 sdk.store.cart.methodName(params)”
• 确认方法签名和参数

步骤 4：仅在此之后编写代码

• 现在可以使用已验证的方法编写代码
• 使用查到的确切签名

步骤 5：检查 TypeScript 错误

• 编写代码后，检查是否存在与 SDK 相关的 TypeScript／类型错误
• 如果 SDK 方法出现类型错误，说明你使用了不正确的方法名或错误的参数
• 类型错误表明你没有正确进行验证——返回步骤 2

此流程不可选择——这是防止错误的强制要求

以下情况属于严重错误：

• ❌ 未先明确查询文档／MCP，就编写调用后端 API／SDK 的代码
• ❌ 猜测方法名或参数
• ❌ 忽略 SDK 方法的 TypeScript 错误（错误表明方法使用不正确）
• ❌ 未经验证就复制此技能中的示例（示例可能已过时）
• ❌ 假设 SDK 方法与 REST API 端点相匹配

关于 Medusa 的具体说明：

• Medusa 定价：按原样显示价格——不要除以 100（与 Stripe 不同，Medusa 以显示格式存储价格）
• 文档 MCP 服务：https://docs.medusajs.com/mcp——如果尚未安装，建议设置
• 加载 reference/medusa.md，查看 Medusa 专属模式（区域、定价等）

路由模式

• 产品和类别始终使用动态路由——切勿为单个商品创建静态页面
• 产品页面：使用 /products/[handle] 或 /products/$handle 等动态路由，而不是 /products/shirt.tsx
• 类别页面：使用 /categories/[handle] 或 /categories/$handle 等动态路由，而不是 /categories/women.tsx
• 框架专属模式：
  • Next.js App Router：app/products/[handle]/page.tsx 或 app/products/[id]/page.tsx
  • Next.js Pages Router：pages/products/[handle].tsx
  • SvelteKit：routes/products/[handle]/+page.svelte
  • TanStack Start：routes/products/$handle.tsx
  • Remix：routes/products.$handle.tsx
• 原因：动态路由可以适用于任意数量的产品／类别，无需为每个商品创建单独的文件
• 静态路由难以维护，也无法扩展（想象一下要创建 1000 个产品文件）

模式选择指南

需要在不同实现模式之间进行选择时，请加载相应的参考文件：

• 结账策略（单页还是多步）→ 加载 reference/layouts/checkout.md
• 导航策略（下拉菜单还是超级菜单）→ 加载 reference/components/navbar.md 和 reference/components/megamenu.md
• 商品列表策略（分页、无限滚动还是加载更多）→ 加载 reference/layouts/product-listing.md
• 搜索策略（自动补全、筛选还是自然语言）→ 加载 reference/components/search.md
• 移动端与桌面端优先级 → 加载 reference/mobile-responsiveness.md
• 款式选择（文本、色板还是配置器）→ 加载 reference/layouts/product-details.md
• 购物车模式（弹窗、抽屉还是页面导航）→ 加载 reference/components/cart-popup.md 和 reference/layouts/cart.md
• 信任信号策略 → 加载 reference/layouts/product-details.md 和 reference/layouts/checkout.md

每个参考文件都包含决策框架和具体标准，帮助你根据实际情况选择合适的模式。

快速参考

通用

reference/connecting-to-backend.md    - Framework detection, API setup, backend integration patterns
reference/medusa.md                    - Medusa SDK integration, pricing, regions, TypeScript types
reference/design.md                    - User preferences, brand identity, design systems
reference/seo.md                       - Meta tags, structured data, Core Web Vitals
reference/agent-friendly.md            - AI agent access, machine-readable product data, operable forms, llms.txt, UCP
reference/mobile-responsiveness.md     - Mobile-first design, responsive breakpoints, touch interactions

组件

reference/components/navbar.md         - Desktop/mobile navigation, logo, menu, cart icon, load for ALL pages
reference/components/megamenu.md       - Category organization, featured products, mobile alternatives
reference/components/cart-popup.md     - Add-to-cart feedback, mini cart display
reference/components/country-selector.md - Country/region selection, currency, pricing, Medusa regions
reference/components/breadcrumbs.md    - Category hierarchy, structured data markup
reference/components/search.md         - Search input, autocomplete, results, filters
reference/components/product-reviews.md - Review display, rating aggregation, submission
reference/components/hero.md           - Hero layouts, CTA placement, image optimization
reference/components/popups.md         - Newsletter signup, discount popups, exit-intent
reference/components/footer.md         - Content organization, navigation, social media, load for ALL pages
reference/components/product-card.md   - Product images, pricing, add to cart, badges
reference/components/product-slider.md - Carousel implementation, mobile swipe, accessibility

布局

reference/layouts/home-page.md         - Hero, featured categories, product listings
reference/layouts/product-listing.md   - Grid/list views, filters, sorting, pagination
reference/layouts/product-details.md   - Image gallery, variant selection, related products
reference/layouts/cart.md              - Cart items, quantity updates, promo codes
reference/layouts/checkout.md          - Multi-step/single-page, address forms, payment
reference/layouts/order-confirmation.md - Order number, summary, delivery info
reference/layouts/account.md           - Dashboard, order history, address book
reference/layouts/static-pages.md      - FAQ, about, contact, shipping/returns policies

功能

reference/features/wishlist.md         - Add to wishlist, wishlist page, move to cart
reference/features/promotions.md       - Promotional banners, discount codes, sale badges

常见实现模式

开始搭建新的店面

重要：执行以下每个步骤前，请先加载该步骤引用的文件。

1. Discovery Phase → Read design.md for user preferences
2. Foundation Setup → Read connecting-to-backend.md (or medusa.md for Medusa), mobile-responsiveness.md, seo.md
3. Core Components → Implement navbar.md, footer.md
4. Home Page → Read home-page.md
5. Product Browsing → Read product-listing.md, product-card.md, search.md
6. Product Details → Read product-details.md, product-reviews.md
7. Cart & Checkout → Read cart-popup.md, cart.md, checkout.md, order-confirmation.md
8. User Account → Read account.md
9. Additional Features → Read wishlist.md, promotions.md
10. Optimization → SEO audit (seo.md), agent-friendliness audit (agent-friendly.md), mobile testing (mobile-responsiveness.md)

即使你制定了实现计划，在实现每个步骤时也要查阅技能文档并加载相关参考文件。

购物流程模式

Browse → View → Cart → Checkout

Browse:   home-page.md → product-listing.md
View:     product-details.md + product-reviews.md
Cart:     cart-popup.md → cart.md
Checkout: checkout.md → order-confirmation.md

组件选择指南

商品网格和筛选 → product-listing.md 和 product-card.md
商品卡片 → product-card.md
导航 → navbar.md 和 megamenu.md
搜索功能 → search.md
结账流程 → checkout.md
促销和销售 → promotions.md

设计注意事项

实现前，请考虑：

1. 用户偏好 - 阅读 design.md，了解设计风格偏好
2. 品牌形象 - 与品牌相符的颜色、字体和语气
3. 目标受众 - B2C 还是 B2B、人群特征、设备使用情况
4. 商品类型 - 时尚、电子产品还是杂货都会影响布局选择
5. 业务需求 - 多币种、多语言、特定地区要求
6. 后端系统 - API 结构会影响组件实现

与 Medusa 集成

Medusa 是一个现代、灵活的电子商务后端。以下情况可考虑使用 Medusa：

• 构建新的电子商务店面
• 需要无头商务解决方案
• 希望内置支持多地区、多币种
• 需要强大的促销和折扣引擎
• 需要灵活的商品建模能力

有关 Medusa 集成的详细指南，请参阅 reference/medusa.md。有关通用后端模式，请参阅 reference/connecting-to-backend.md。

框架无关

所有指南均与框架无关。示例在适合展示代码的地方使用 React/TypeScript，但这些模式也适用于：

• Next.js
• SvelteKit
• Tanstack Start
• 任何现代前端框架

最小可行功能

上线必备（核心购物流程）：

• 包含购物车、分类和搜索的导航栏
• 支持筛选和分页的商品列表
• 支持选择变体的商品详情
• 加入购物车功能
• 支持管理商品的购物车页面
• 结账流程（配送、付款、确认）
• 订单确认页面

锦上添花（时间允许时添加）：

• 相关推荐商品
• 商品评论和评分
• 愿望清单功能
• 商品页面图片缩放
• 移动端底部导航
• 导航超级菜单
• 订阅新闻简报
• 商品比较
• 快速查看弹窗

取决于用户需求（实施前先询问）：

• 游客结账还是必须登录
• 账户仪表板功能
• 多语言支持
• 多币种支持
• 在线聊天支持
• Agentic Commerce 协议（UCP 配置文件、MCP Agent 端点、OAuth 发现）——参见 reference/agent-friendly.md

应避免的电商常见错误

实施前，请注意以下电商特有的常见陷阱：

1. 购物车和导航错误

• ❌ 在移动端汉堡菜单中隐藏购物车指示器（应始终保持可见）
• ❌ 不显示实时更新的购物车数量
• ❌ 严重：购物车数量缺少 aria-live="polite"——没有该属性，屏幕阅读器不会播报购物车更新
• ❌ 购物车弹出窗口未显示变体详情（尺寸、颜色等），只显示商品标题
• ❌ 悬停在下拉内容上时超级菜单关闭（鼠标悬停在触发按钮或下拉内容上时，菜单都必须保持打开）
• ❌ 严重：超级菜单定位错误——三种常见错误：
  • ❌ 导航栏没有 position: relative（超级菜单无法正确定位）
  • ❌ 超级菜单相对于触发按钮而非导航栏定位（在超级菜单上使用 absolute left-0）
  • ❌ 超级菜单未横跨全宽（必须使用 right-0 或 w-full，不能只用 w-auto）
• ❌ 将分类、精选商品或任何动态内容写死，而不是从后端获取
• ❌ 分类导航中没有明确标示当前页面

2. 商品浏览错误

• ❌ 为商品／分类创建静态路由（应使用 /products/[handle] 这样的动态路由，而不是 /products/shirt.tsx）
• ❌ 缺少带有实用建议的“未找到商品”空状态
• ❌ 获取商品时没有加载指示器
• ❌ 分页 URL 不利于 SEO（搜索引擎优化）
• ❌ 页面重新加载后筛选项不会保留

3. 商品详情错误

• ❌ 未选择变体（尺寸、颜色等）就允许“加入购物车”
• ❌ 未优化商品图片（图片过大且未经压缩）
• ❌ 加入购物车后跳转离开商品页面（应留在当前页面）
• ❌ 在 UI 中使用表情符号代替图标或图片（显得不专业，也存在无障碍问题）

4. 设计和一致性错误

• ❌ 严重：创建任何 UI 组件前未加载 reference/design.md——这会导致颜色、字体和样式不一致
• ❌ 未先检查现有主题就引入新颜色
• ❌ 未确认当前已使用的字体就添加新字体
• ❌ 主题令牌已存在，却使用任意 Tailwind 值
• ❌ 未检测 Tailwind 版本（v3 还是 v4）——会导致语法错误

5. 结账和转化错误

• ❌ 要求用户创建账户才能结账（如果后端支持，应提供游客结账）
• ❌ 未从后端获取支付方式——自行假设可用的支付选项，或跳过支付方式选择
• ❌ 结账步骤过于复杂（4 步及以上会严重降低转化率）——最佳方案是 3 步：配送信息、配送方式和付款、订单确认
• ❌ 缺少信任标识（安全结账徽章、退货政策链接）
• ❌ 结账过程中未妥善处理缺货错误 6. 移动端体验常见错误
• ❌ 触控目标小于 44x44px（按钮、链接、表单字段）
• ❌ 在移动端使用桌面风格的悬停菜单（改用轻触/点击）
• ❌ 未针对移动端优化图片（加载体积巨大的桌面端图片）
• ❌ 缺少移动端专属模式（底部导航、抽屉式筛选器）

7. 性能和 SEO 常见错误

• ❌ 缺少用于 SEO 的结构化数据（Product schema）
• ❌ 未显式启用图片延迟加载（不要假设浏览器默认会处理）——始终为首屏以下的图片添加 loading="lazy"
• ❌ 缺少用于社交分享的 meta 标签和 Open Graph
• ❌ 未优化 Core Web Vitals（LCP、FID、CLS）——使用 PageSpeed Insights 或 Lighthouse 进行测量

8. Agent 友好性常见错误（参见 reference/agent-friendly.md）

• ❌ 在客户端组件中获取产品数据或价格（Agent 只能看到空壳）
• ❌ 将添加到购物车功能实现为 <div onClick>，或实现为周围没有 <form action> 的 <button>
• ❌ 将变体色板实现为没有原生输入控件或 ARIA 状态的裸 <div>/<span>
• ❌ 图标按钮（购物车、搜索、菜单、愿望清单）没有 aria-label
• ❌ 只有 JS 的搜索浮层，没有 GET 结果页面
• ❌ 在 robots.txt、中间件或 WAF 中屏蔽 AI Agent/搜索机器人（屏蔽训练爬虫没问题）
• ❌ 根据 IP 强制将 / 重定向到某个区域路径
• ❌ 未知产品 URL 返回 200 或重定向到主页（软 404）

9. 后端集成常见错误

• ❌ 错误：编写调用后端 API/SDK 的代码，却没有遵循 5 步验证工作流——你必须：1）暂停，2）查询文档/MCP，3）与用户确认，4）编写代码，5）检查类型错误
• ❌ 错误：忽略 SDK 方法的 TypeScript 错误——类型错误意味着你使用了错误的方法名或参数。返回文档/MCP 进行验证
• ❌ 错误：猜测 API 方法名、SDK 方法或参数——使用前始终验证准确的方法签名
• ❌ 错误：有 Docs MCP 服务可用时却不使用——如果使用 Medusa 后端，始终通过 Docs MCP 服务查询方法
• ❌ 错误：复制代码示例却不验证其是否为最新版本——示例可能已过时，务必先验证
• ❌ 未检测正在使用的后端（检查 monorepo，不确定时询问用户）
• ❌ 未查阅后端文档或 MCP 服务就假设 API 结构
• ❌ 将动态内容（类别、区域、产品等）硬编码，而不是从后端获取
• ❌ 为 Medusa 实体定义自定义类型，而不是使用 @medusajs/types 包
• ❌ 初始化 Medusa SDK 时未提供可发布 API 密钥（多区域商店和产品定价必需）
• ❌ 获取 Medusa 产品时未传递 region_id 查询参数（会导致价格缺失或错误）
• ❌ 在 Medusa 结账流程中显示所有国家/地区——只应显示购物车所在区域的国家/地区
• ❌ 将 Medusa 价格除以 100（Medusa 按原值存储价格，不像 Stripe 那样以分为单位）
• ❌ 缺少 Medusa SDK 的 Vite SSR 配置（将 ssr.noExternal: ['@medusajs/js-sdk'] 添加到 vite.config.ts）
• ❌ 在 8000 以外的端口运行 Medusa 店面（会导致 CORS 错误——Medusa 后端默认使用 8000 端口）
• ❌ 未处理 API 调用的加载、错误和空状态
• ❌ 在客户端发起本应在服务端执行的 API 调用（SEO、安全性）
• ❌ 未提供恰当的错误消息（“发生错误”而不是“产品缺货”）
• ❌ 缺少缓存失效处理（导致产品数据、价格、库存过时）
• ❌ 下单后未清除购物车状态——由于未从 Context/localStorage/缓存中重置购物车，购物车弹窗仍显示旧商品