英文原文正文为项目原始 README（英文），本站后续会翻译为中文，当前仅剔除图片与无关章节并统一排版。

📷 原文此处有图片，请前往 GitHub 仓库查看完整内容。

使用 WooCommerce 后端的 Next.js 电子商务网站

实时网址：

目录（TOC）

• 安装
• 功能
• 设计系统
• Lighthouse 性能监控
• 安全
• 问题
• 故障排除
• 待办事项
• 未来改进

安装

1. 在您的 WordPress 插件目录中安装并激活以下必需插件：

• woocommerce 用于 WordPress 的电子商务插件。
• wp-graphql 为 WordPress 提供 GraphQL 接口。
• wp-graphql-woocommerce 向 WPGraphQL 架构添加 WooCommerce 功能。
• wp-algolia-woo-indexer 我编写的 WordPress 插件。将 WooCommerce 产品发送到 Algolia。搜索功能需要此插件。

可选插件：

• headless-wordpress 禁用前端，使仅能访问后台。（可选）

当前版本已测试并确认与以下版本兼容：

• WordPress 版本 7.0.2
• WooCommerce 版本 10.9.4
• WP GraphQL 版本 2.18.0
• WooGraphQL 版本 1.0.3
• WPGraphQL CORS 版本 2.1

2. 用于调试和测试，请安装以下任一浏览器插件：

   （Firefox）

   （Chrome）

3. 确保 WooCommerce 已有一些产品。

4. 克隆或分支此仓库，修改 .env.example 并重命名为 .env。

   然后在 Vercel 或您首选的托管解决方案中相应设置环境变量。

   请参见

5. 根据您的设置修改数值

6. 使用 pnpm run dev 启动服务器

7. 在 WooCommerce 中启用 COD（货到付款）支付方式

8. 将产品添加到购物车

9. 前往结账（Gå til kasse）

10. 填写您的信息并下单

功能

• Next.js 版本 16.1.6
• React 版本 19.2.4
• Typescript
• 使用 Playwright 进行测试
• 连接到 WooCommerce GraphQL API 并列出产品的名称、价格和展示图片
• 支持简单产品和可变产品
• 使用 Zustand 进行状态管理的 WooCommerce 购物车处理和结账
  • 使用 localStorage 同步持久化购物车状态
  • 通过选择性订阅实现高效更新
  • 类型安全的购物车操作
  • 货到付款支付方式
• Algolia 搜索（需要 algolia-woo-indexer）
• 在可能的情况下符合 WCAG 可访问性标准
• 无图片产品的占位符
• 状态管理：
  • Zustand 用于全局状态管理
  • Apollo 客户端与 GraphQL
• React Hook 表单
• 原生 HTML5 表单验证
• 使用 Framer motion、Styled components 和 Animate.css 的动画
• 使用 Styled Components 创建的加载旋转器
• 在导航过程中使用 Nprogress 显示页面加载进度
• 完全响应式设计
• 分类和产品列表
• 显示库存状态
• 使用内置 Next.js 功能的漂亮网址
• 使用 Tailwind 3 进行样式设计
• JSDoc 注释
• 自动化 Lighthouse 性能监控
  • 持续进行性能、可访问性和最佳实践检查
  • 对每个拉取请求生成自动报告
  • 性能指标跟踪：
  • 性能评分
  • 可访问性合规性
  • 最佳实践遵循情况
  • 搜索引擎优化
  • 渐进式 Web 应用准备情况
• 产品筛选：
  • 使用 Tailwind 的颜色系统进行动态颜色筛选
  • 移动优化的筛选布局
  • 具有ARIA标签的可访问表单控件
  • 价格范围滑块
  • 尺寸和颜色筛选
  • 产品类型分类
  • 排序选项（热度、价格、最新）

设计系统

此项目使用自定义设计系统，该系统基于 Tailwind CSS 设计令牌构建。该系统定义在 tailwind.config.js 和 globals.css 中。

颜色调色板

该调色板使用柔和的石板蓝作为主色，搭配温暖的中性色表面——选择这种搭配是为了营造平静、北欧风格，并且适合家居用品商店。

排版

• 使用 Tailwind 的默认系统字体堆栈
• 字体比例从 text-xs (0.75rem) 到 text-5xl (3rem) 定义
• 层级规则：产品卡片标题 text-xl font-bold > 价格 text-lg、详情页 h1 text-2xl md:text-3xl font-light > 卡片标题

无障碍

• 全局 focus-visible 环（2px solid primary）应用于所有交互元素
• prefers-reduced-motion: reduce 禁用所有动画和过渡
• 表单输入显示内联错误信息，使用 role="alert" 和 aria-invalid
• 必填字段用星号标记
• 结账输入框具有正确的 type (email, tel) 和 autocomplete 属性
• 图片使用描述性 alt 文本
• 按钮使用 disabled:cursor-not-allowed
• 整个页面采用语义化 HTML (<nav>, <main>, <section>, <label htmlFor>)

按钮变体

所有按钮都包含 hover、active:scale-[0.98]、focus-visible 和 disabled 状态，并带有 duration-200 过渡。

CSS 自定义属性

设计令牌也可作为 CSS 自定义属性在 globals.css 中使用，以便在 Tailwind 以外使用：

var(--color-primary)      /* #3B6B8A */
var(--color-surface)      /* #FAF9F7 */
var(--color-text)         /* #2C2C2C */
var(--color-error)        /* #B83B2A */

Lighthouse 性能监控

该项目通过 GitHub Actions 使用自动化 Lighthouse 测试，以确保高质量的网页性能。在每次拉取请求时：

• 性能、可访问性、最佳实践和 SEO 会被自动评估
• 结果会直接发布到拉取请求中
• 强制执行最低分数阈值以：
  • 性能：分析加载性能、交互性和视觉稳定性
  • 可访问性：确保符合 WCAG 标准和包容性设计
  • 最佳实践：验证现代网页开发标准
  • SEO：检查搜索引擎优化基础
  • PWA：评估渐进式网页应用功能

在 GitHub Actions 选项卡的“Lighthouse Check”工作流程下查看最新的 Lighthouse 结果。

安全性

该项目通过 GitHub Actions 在每次推送和拉取请求时运行自动化的 OWASP 安全扫描：

自定义 Semgrep 规则覆盖 OWASP 分类 A01–A10，包括 XSS 预防、注入检测、认证检查、SSRF 保护和安全配置错误。在 GitHub Actions 标签下的“OWASP 安全扫描”工作流中查看结果。

故障排除

我收到购物车未定义错误或其他 GraphQL 错误

检查你是否使用了最新版本的 wp-graphql-woocommerce 插件

产品页面无法加载

检查产品的属性。目前应用程序需要尺寸和颜色。

问题

总体而言，该应用程序按预期工作，但尚未在生产环境中进行广泛测试。
在部署到生产环境之前，需要进行更多的测试和调试。

话虽如此，请注意以下事项：

• 目前只有简单产品和可变产品可以正常使用。其他产品类型是否可用尚不清楚。
• 目前仅支持货到付款（COD）。以后可能会添加更多支付方式。

该项目已通过 BrowserStack 进行测试。

待办事项

• 在注册页面中实现 UserRegistration.component.tsx
• 添加包含订单历史的用户仪表板
• 在注册页面上添加 Cloudflare Turnstile
• 确保注册页面上的邮箱真实有效
• 在购物车/结账页面显示总计
• 将账单地址复制到收货地址
• 隐藏缺货产品