Shopify Headless 路线:Storefront API 驱动的前端工程

前言

Headless 是 Shopify 中自由度最高的路线。你可以用任意前端框架构建体验,但也要承担性能与工程复杂度。核心能力来自 Storefront API,前端负责体验与交互,Shopify 负责产品数据与结账。

本文给出工程化落地的关键路径。

1. 适用场景

• 高定制化的前端体验
• 多端统一(网站 + App + 小程序)
• 不想依赖 Shopify 主题体系

2. 技术栈建议

• Storefront API(GraphQL)
• Hydrogen / Next.js / Remix
• SSR/ISR + CDN 缓存
• Shopify Checkout 作为结账终点

3. Storefront API 基本请求

GraphQL 查询示例:

query Products {
  products(first: 10) {
    edges {
      node {
        id
        title
        description
      }
    }
  }
}

JS 调用示例:

const res = await fetch(
  "https://{shop}.myshopify.com/api/2024-10/graphql.json",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Shopify-Storefront-Access-Token": process.env.STOREFRONT_TOKEN,
    },
    body: JSON.stringify({ query }),
  }
);
const data = await res.json();

4. 购物车与结账

Headless 通常通过 cartCreate 获取 checkoutUrl,再跳转到 Shopify Checkout:

mutation cartCreate($input: CartInput!) {
  cartCreate(input: $input) {
    cart {
      id
      checkoutUrl
    }
  }
}

前端完成购物体验,结账仍交给 Shopify 以保证支付合规和稳定性。

5. 性能策略是核心

• 使用 SSR/ISR 保证首屏
• 对商品列表做缓存与分页
• 合理拆分 GraphQL 查询
• CDN 与边缘缓存提升稳定性

6. 工程化建议

• 采用 GraphQL codegen,避免字段漂移
• 明确哪些数据来自 Shopify,哪些来自自有系统
• 对 API 失败做兜底处理
• 针对 SEO 做结构化数据输出

7. 常见坑

• 忽略缓存导致 API 超限
• 购物车状态未持久化
• Checkout 可定制化期待过高(非 Plus 有限制)
• 前端与 Shopify 数据字段不同步

结语

Headless 是最自由的 Shopify 路线,但自由意味着更高成本。只要你能把性能、缓存、结账路径与数据边界设计清楚,它就是最适合品牌体验和多端统一的解法。