Next.js WooCommerce 集成 (nextjs-woocommerce)
用于架构、查询和集成 Next.js App Router 应用与无头 WooCommerce 后端（通过 WPGraphQL、WooGraphQL 和 JWT 认证）的操作手册和检查清单。
前提条件与文档参考
- 已初始化 Next.js 14+ 项目，使用 App Router 和 TypeScript。
- 活跃的 WooCommerce 后端，安装了 WPGraphQL、WooGraphQL 和 wp-graphql-jwt-authentication。
- 有关完整的 API 模式和 Next.js 代码模式，请参考 nextjs-woocommerce-reference.md。
- 有关可重用的数据获取客户端实现，请参见 woocommerce-fetcher.ts。
分步实施检查清单
flowchart TD
S1["1. 环境与客户端设置"] --> S2["2. 公开产品目录 (ISR/SSG)"]
S2 --> S3["3. 用户认证 (JWT + Cookies)"]
S3 --> S4["4. 受保护的个人资料与订单历史"]
S4 --> S5["5. 购物车会话与原生结账桥接"]
阶段 1：环境与客户端配置
- 配置环境变量：
- 将
NEXT_PUBLIC_WORDPRESS_API_URL=https://your-store.com/graphql添加到.env.example和.env.development。 - 为结账重定向添加
NEXT_PUBLIC_WORDPRESS_URL=https://your-store.com。
- 将
- 设置通用 Fetcher：
- 实现 woocommerce-fetcher.ts，支持 ISR 缓存和认证头。
阶段 2：公开产品目录与分类
- 类别导航：为页眉和类别菜单查询
productCategories，设置hideEmpty: true。 - 产品网格列表：使用联合片段（
... on SimpleProduct，... on VariableProduct）查询products。配置next: { revalidate: 300, tags: ['products'] }。 - 产品详情页：使用
generateStaticParams()查询所有产品 slug，预渲染动态路由（app/products/[slug]/page.tsx）。
阶段 3：JWT 认证管道
- 登录 Mutation：实现 Server Action，执行
login(input: { username, password })。 - Cookie 存储：将返回的
authToken存储在安全的HttpOnlycookie（auth_token）中。 - 会话绑定：如果客户返回
sessionToken，则将其存储在wc_sessioncookie 中。 - 登出：用户登出时清除认证 cookies。
阶段 4：受保护的用户数据与订单
- 客户个人资料：使用
Authorization: Bearer <authToken>头查询viewer { id name email }。 - 订单历史：使用
cache: 'no-store'查询customer { orders { nodes { id orderNumber total status } } }。
阶段 5：购物车管理与结账策略
- 购物车状态：捕获并持久化
addToCartmutations 返回的woocommerce-session头。 - 原生结账桥接：
- 将用户重定向到
https://your-store.com/checkout，以利用原生 WooCommerce 支付网关（如 ZarinPal、Mellat、Stripe）、区域物流和合规认证，无需重写自定义网关。
- 将用户重定向到
边界情况与已知陷阱
- 静态与动态优化降级：在根布局或产品页面中读取 Cookie 会使 Next.js 切换到完全 SSR 动态模式。仅应在 Server Actions、Route Handlers 或隔离的账户仪表板子树（
app/account/...）中读取认证 cookies。 - 多态片段：直接的查询如
products { nodes { price } }会在 WooGraphQL 中通过验证失败。始终将定价和变体包装在... on SimpleProduct和... on VariableProduct中。 - 会话丢失：向购物车添加商品时，未能重新发送
woocommerce-session头会导致每次 mutation 都创建一个新的空购物车。 - GraphQL 端点的 CORS：确保 WordPress 为您的 Next.js 域名发送
Access-Control-Allow-Origin和Access-Control-Allow-Headers: Authorization, Content-Type, woocommerce-session头。
验证与起飞前测试
-
pnpm build成功，产品页面静态生成。 - 测试登录表单发出
auth_token并重定向到仪表板。 - 账户页面使用有效令牌渲染客户详情和订单列表。
- 添加到购物车操作在多个客户端请求中更新购物车商品数量。