你的 Shopify Plus 店铺上线时 Lighthouse 评分为 98。部署看起来完美——Hydrogen 的流式 SSR、小于 900ms 的 LCP、零布局偏移。三个月后，结账转化率下降 14%。你的产品团队责怪购物车 API。工程部门指向第三方脚本。财务部质疑六位数的重构。自 2020 年以来，我在审计的 400+ 个 headless Shopify 构建中看到过 87 次完全相同的情景。在那些四个月内达到 $1M ARR 的店铺和陷入两个季度停滞的店铺之间的区别不是 Hydrogen 对比 Next.js——而是三个迁移决策，大多数团队在提交第一行代码之前就搞错了。以下是 400 个构建教会我们关于任何框架文档都没有提及的陷阱的内容。

本指南包含了我在 2020 年构建第一个 headless Shopify 店铺时希望有人交给我的全部内容，当时我用拼凑的 Next.js 设置和旧的 REST API。这是为 DTC 品牌、B2B 批发商和企业 Shopify Plus 商家构建店铺的精炼知识。其中一些会确认你已经怀疑的东西。其中一些会挑战你在 Twitter 上读过的常规智慧。

让我们开始吧。

目录

Headless Shopify 开发指南 2026：Hydrogen、Next.js 及更多

2026 年 Headless Shopify 的实际含义

Headless Shopify 意味着将前端展示层与 Shopify 后端分离。你保留 Shopify 真正擅长的东西——库存、订单、支付、履行——并用自定义前端替换 Liquid 主题，该前端与 Storefront API 进行通信。

但这里是大多数文章不会告诉你的东西：2026 年的 headless Shopify 与两年前的情况完全不同。三个转变从根本上改变了格局：

  1. Hydrogen 2 已成熟。 Shopify 的基于 React 的框架运行在 Oxygen（他们的托管平台）上，自 2023 年不稳定的发布以来已经大幅稳定。它现在使用 Remix 作为底层，并附带明智的默认值。

  2. Storefront API 达到 2025-04 版本。 这带来了 Customer Account API v2、改进的预测搜索以及关键的——不需要客户端 JavaScript 的服务器端购物车操作。

  3. 结账扩展完全取代了 checkout.liquid。 截至 2025 年 8 月，所有 Shopify Plus 店铺必须使用结账可扩展性。不再有 Liquid 结账自定义。仅这一点就推动了数千家店铺走向 headless 架构。

我使用的心智模型：Shopify 是你的商务引擎。你的前端是一个恰好从该引擎提取数据的目的构建的界面。两者之间的一切都是 API 调用和缓存策略。

架构堆栈

2026 年典型的 headless Shopify 设置如下所示：

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   前端应用      │────▶│  Storefront API   │────▶│  Shopify 后端    │
│  (Hydrogen/Next)│     │  (GraphQL)        │     │  (Admin, Orders) │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │                                                  │
        ▼                                                  ▼
┌─────────────────┐                              ┌─────────────────┐
│   Headless CMS  │                              │  结账扩展       │
│ (Sanity/Content │                              │  (Shopify UI Ext)│
│      ful)       │                              └─────────────────┘
└─────────────────┘

前端通过 GraphQL 与 Storefront API 通信。不属于 Shopify 的内容（编辑页面、登陆页面、复杂内容模型）存放在 headless CMS。结账自定义通过 Shopify 的扩展点进行，而不是自定义标记。

Storefront API：你的新好友

Storefront API 是专门为客户面向体验设计的公共 GraphQL API。它不同于处理后端操作的 Admin API。理解这一区别至关重要。

你能做什么

query ProductPage($handle: String!) {
  product(handle: $handle) {
    id
    title
    description
    priceRange {
      minVariantPrice {
        amount
        currencyCode
      }
    }
    variants(first: 100) {
      edges {
        node {
          id
          title
          availableForSale
          selectedOptions {
            name
            value
          }
          price {
            amount
            currencyCode
          }
        }
      }
    }
    metafields(identifiers: [
      { namespace: "custom", key: "sizing_guide" },
      { namespace: "custom", key: "material_info" }
    ]) {
      key
      value
      type
    }
    media(first: 20) {
      edges {
        node {
          ... on MediaImage {
            image {
              url
              altText
              width
              height
            }
          }
          ... on Video {
            sources {
              url
              mimeType
            }
          }
        }
      }
    }
  }
}

速率限制和缓存

截至 2026 年，Storefront API 允许每个店铺的公共访问令牌每秒 100 个请求（从 2024 年初的 60 个增加）。私有访问令牌获得更高的限制。但你本来就不应该接近这些限制——如果你接近了，你的缓存策略就坏了。

以下是我在每个项目上所做的：

  • 完整页面缓存在 CDN 级别（Vercel、Cloudflare 或 Oxygen），使用 stale-while-revalidate 标头
  • 数据层缓存的 TTL 为 60 秒用于产品数据，300 秒用于集合数据
  • 购物车操作永不缓存——这些每次都直接命中 API
  • 库存检查使用轻量级轮询机制或 webhooks 来使陈旧库存数据失效
// 示例：Next.js 中产品查询的缓存策略
export async function getProduct(handle: string) {
  const data = await shopifyFetch({
    query: PRODUCT_QUERY,
    variables: { handle },
    cache: 'force-cache',
    next: { revalidate: 60, tags: [`product-${handle}`] },
  });
  return data.product;
}

Hydrogen 对比 Next.js Commerce：真实对比

这是我最常被问到的问题。诚实的答案是：这取决于你的团队、你的时间表和你的托管偏好。但这是数据。

因素 Hydrogen 2 (Remix/Oxygen) Next.js Commerce (Vercel)
框架 Remix (React) Next.js 15 (React)
托管 Oxygen (Shopify) 或自托管 Vercel、Netlify、自托管
Shopify 集成 第一方、深入 社区维护的启动程序
学习曲线 中等（Remix 模式） 较低（如果团队了解 Next.js）
CMS 灵活性 好但以 Shopify 为中心 优秀——生态系统庞大
中位数 LCP（我们的数据） 0.8s 0.7s
中位数 TTFB 120ms (Oxygen) 90ms (Vercel Edge)
规模成本 Oxygen 免费层慷慨 Vercel Pro $20/mo、企业版 $$$
结账集成 原生购物车→结账流程 需要 Storefront API 购物车设置
生态系统插件 增长中，约 200 个包 庞大，10k+ 包
社区规模 约 15k GitHub 星标 约 40k GitHub 星标

何时选择 Hydrogen

在以下情况下选择 Hydrogen：

  • 你的团队适应 Remix 的 loader/action 模式
  • 你想要最接近原生 Shopify 体验
  • 你是想要包含 Oxygen 托管的 Shopify Plus 商家
  • 你不需要繁重的非商务内容（博客、编辑等）

何时选择 Next.js

在以下情况下选择 Next.js：

  • 你的团队已经在发布 Next.js 应用
  • 你需要超越 Shopify metafields 的深入 CMS 集成
  • 你想要最大的托管灵活性
  • 你在构建与商务相关的内容丰富的品牌体验
  • 你计划在未来可能切换商务后端

我会直言不讳：在过去一年我构建的 70% 的店铺中，Next.js 是正确的选择。不是因为它在技术上优越——它不一定是——而是因为人才库大 5 倍，生态系统对边缘情况有更多解决方案。当你客户的营销团队想要特定的动画库或他们的 SEO 机构需要特定的元标签结构时，你会在 Next.js 领地更快找到答案。

也就是说，Oxygen 上的 Hydrogen 店铺具有难以匹敌的部署简单性。推送到主分支，它就活了。无需构建配置，无需调试边缘函数冷启动。

Headless Shopify 开发指南 2026：Hydrogen、Next.js 及更多 - 架构

实现小于 1 秒的 LCP

这是橡胶与道路相遇的地方。整个 headless Shopify 的商业案例——实际的财务理由——都建立在性能基础上。你需要达到的数字是移动设备上小于 1 秒的最大内容绘制 (LCP)。

以下是为什么：根据 Shopify 的 2025 年性能研究，LCP 每提高 100ms 大约对应 1% 的转化率提升。一家年收入 $5M 的店铺从 2.5s LCP（典型 Liquid 主题）到 0.9s LCP 可以预期大约 15% 的提升。这是额外的 $750K 收入。

我们 400+ 个站点的数据确认了这个范围。Headless 店铺的速度比 Liquid 主题快 60-75%，按实际用户的核心网络生命体征数据和 CrUX 报告衡量。

性能手册

以下是我们如何一致地实现小于 1 秒 LCP 的方式：

1. 服务器渲染关键路径

// Next.js App Router——产品页面的服务器组件
export default async function ProductPage({ params }: { params: { handle: string } }) {
  const product = await getProduct(params.handle);
  
  return (
    <main>
      <ProductHero product={product} />
      <Suspense fallback={<PriceSkeleton />}>
        <ProductPricing productId={product.id} />
      </Suspense>
      <Suspense fallback={<ReviewsSkeleton />}>
        <ProductReviews productId={product.id} />
      </Suspense>
    </main>
  );
}

2. 积极优化图像

Shopify 的 CDN 支持 width、height 和 crop 参数。使用它们。不要向 375px 移动视口提供 2000px 英雄图像。

function getOptimizedImageUrl(url: string, width: number) {
  const imageUrl = new URL(url);
  imageUrl.searchParams.set('width', String(width));
  imageUrl.searchParams.set('format', 'webp');
  return imageUrl.toString();
}

3. 预加载 LCP 图像

<link rel="preload" as="image" href="/hero.webp" fetchpriority="high" />

4. 内联关键 CSS，延迟其他一切

我们将首屏 CSS 保持在 14KB 以下（一个 TCP 往返）。其他一切都异步加载。

5. 边缘端渲染

Vercel 边缘函数和 Oxygen 的 worker 运行时都在边缘执行，给你全球小于 100ms 的 TTFB。这是你可以拉动的单个最大性能杠杆。

6. 在意图上预取

不要预取视口上的所有内容。在悬停/触摸开始时预取。这在仍然感觉即时的同时减少了约 40% 的不必要带宽。

结账扩展和 Post-Checkout.liquid 时代

以下是强制许多商家行动的改变：截至 2025 年 8 月，Shopify 在 Plus 店铺上停用了 checkout.liquid。如果你有自定义结账修改——大多数 Plus 商家都有——你必须迁移到结账扩展。

结账扩展使用 Shopify 的 UI 扩展框架。你编写看起来像 React 的组件，在 Shopify 结账内定义的扩展点（购前、购后、运输、支付等）中渲染。

// 示例：购后追加销售扩展
import { useApi, reactExtension, BlockStack, Text, Button } from '@shopify/ui-extensions-react/checkout';

export default reactExtension('purchase.checkout.block.render', () => <UpsellBlock />);

function UpsellBlock() {
  const { cost, lines } = useApi();
  
  return (
    <BlockStack>
      <Text size="medium">添加配套配件？</Text>
      <Button onPress={() => { /* 添加到购物车逻辑 */ }}>
        添加 $19.99
      </Button>
    </BlockStack>
  );
}

需要理解的关键点：无论你是 headless 还是使用 Liquid 主题，结账扩展的工作方式都相同。 你的 headless 前端会转交给 Shopify 的结账，扩展在那里运行。这实际上是 headless 方法的重大优势——你的店铺完全自定义，但结账保持 Shopify 托管（PCI 合规、由 Shopify 维护等）。

Shopify Plus 迁移策略

将现有 Shopify Plus 店铺迁移到 headless 是一个分阶段的操作。不要试图一次完成所有操作。以下是在我们项目中效果最好的方法：

阶段 1：基础（第 1-3 周）

  • 设置前端框架（Next.js 或 Hydrogen）
  • 使用缓存实现 Storefront API 连接层
  • 构建设计系统/组件库
  • 设置 CI/CD 管道

阶段 2：核心商务（第 4-8 周）

  • 产品列表页面（集合）
  • 产品详情页面
  • 购物车功能
  • 搜索（使用 Shopify 的预测搜索 API 或第三方如 Algolia）
  • 通过 Customer Account API 的账户页面

阶段 3：内容与营销（第 9-11 周）

  • CMS 集成非商务页面
  • 博客/编辑部分
  • 营销团队的登陆页面构建器
  • SEO 迁移（301 重定向、站点地图、结构化数据）

阶段 4：启动和优化（第 12-14 周）

  • 性能审计和优化
  • A/B 测试设置
  • 分析迁移（GA4、服务器端跟踪）
  • 通过功能标志或分割测试的逐步流量迁移

总时间表：典型 Shopify Plus 店铺为 12-14 周。具有复杂目录（50k+ SKU）或繁重自定义的企业店铺可能需要 16-20 周。

$1M ARR 阈值：Headless 何时在财务上有意义

Headless 不是免费的。自定义前端开发比安装 Liquid 主题成本更高。持续维护需要开发者时间。那么什么时候数学成立呢？

基于我们的数据：$1M ARR 是 headless Shopify 开始做出明确财务意义的阈值。

以下是数学：

收入水平 估计转化率提升 收入增益 Headless 构建成本 年度运营成本 ROI 时间表
$500K ARR 10-15% $50-75K $80-150K $24-48K 18-24 个月
$1M ARR 10-15% $100-150K $80-150K $24-48K 8-14 个月
$3M ARR 10-15% $300-450K $120-200K $36-60K 4-6 个月
$10M ARR 10-15% $1-1.5M $150-300K $48-96K 2-3 个月

低于 $1M，你最好在一个构建良好的 Liquid 主题上投资转化率优化。高于 $1M，性能提升的复合速度足以证明投资的正当性。高于 $3M，不采用 headless 就是在留下真金白银。

有关 headless 构建定价的具体信息，请查看我们的 定价页面——我们对项目范围是透明的。

选择代理商：Naturaily、Aalpha 及其他

如果你在为 headless Shopify 工作评估代理商，这是我对 2026 年格局的诚实评估。

Naturaily 是一家波兰代理商，在 headless 商务方面建立了良好声誉，特别是在 Next.js 和 Vue Storefront 方面。他们的优势在于中端市场——年收入 $1-10M 的品牌需要专业构建而不是企业定价。他们在技术上称职，具有良好的 Shopify Storefront API 体验。他们有时在哪些方面遇到困难：高度定制的 B2B 工作流和多市场 Shopify 设置。

Aalpha 是一家印度开发公司，专注范围更广——他们从事移动应用、企业软件和 headless 商务。他们的费率明显较低（通常比西方代理商低 40-60%），这对于预算有限的项目很有吸引力。折衷通常在于项目管理开销和设计精细度。如果你有强大的内部设计团队并能够密切管理项目，他们可以交付扎实的技术工作。

我们在 Social Animal 的表现： 我们专门从事 headless web 开发——不仅仅是 Shopify，还包括包括 Next.js 和 Astro 在内的全谱 headless CMS 和框架工作。我们的甜蜜点是需要深入技术专业知识而不是大型代理商开销的品牌和公司。如果你对合适程度感到好奇，请联系我们——我们会诚实地告诉你我们是否适合你的项目。

因素 Social Animal Naturaily Aalpha
专业化 Headless web（深入） Headless 商务 + web 全服务开发
主要框架 Next.js、Astro、Hydrogen Next.js、Vue Storefront Next.js、React Native
团队位置 美国 波兰 印度
典型项目范围 $80-250K $60-200K $25-100K
Shopify Plus 经验 是（400+ headless 站点） 是 是
最适合 性能关键店铺 中端市场 headless 商务 预算有限的构建

使用 Astro 和其他框架的自定义店铺

以下是大多数 Shopify headless 指南不会告诉你的东西：你不必使用 React。

我们已用 Astro 构建了几个 Shopify 店铺——特别是对于内容和编辑与商务同样重要的品牌。Astro 的岛屿架构意味着你默认不发送任何 JavaScript，仅水合交互部分（购物车、产品选择器、搜索）。

结果？LCP 一致低于 0.6 秒。总页面重量低于 100KB。这快得离谱。

---
// Astro Shopify 产品卡片组件
import { getProduct } from '../lib/shopify';

const product = await getProduct(Astro.params.handle);
---

<article class="product-card">
  <img 
    src={product.featuredImage.url + '&width=600'}
    alt={product.featuredImage.altText}
    width="600"
    height="600"
    loading="lazy"
  />
  <h2>{product.title}</h2>
  <p class="price">${product.priceRange.minVariantPrice.amount}</p>
  
  <!-- 只有这个组件发送 JavaScript -->
  <AddToCart client:visible productId={product.id} />
</article>

折衷：Astro 的商务生态系统较小。你将为购物车管理、身份验证和搜索编写更多自定义代码。但如果性能是你的主要指标，你的团队对额外工作感到满意，这是一个合法的选择。

常见问题

Headless Shopify 对小店铺值得吗？ 对于年收入少于 $500K 的店铺，通常不值得。开发和维护成本超过转化率提升。你最好使用快速、优化良好的 Liquid 主题，如 Dawn。一旦你超过 $1M ARR，经济动态转向赞成 headless。

2026 年 headless Shopify 构建的成本是多少？ 根据复杂性、代理商位置和功能范围，预期初始构建成本为 $80K-$300K。持续维护运行 $2K-$8K 每月。南亚的预算代理商可以以 $25K-$80K 的价格交付，但你通常需要更强的内部项目管理和质量保证。

我可以在 headless 店铺中使用 Shopify 的结账吗？ 是的，你应该。Shopify 的结账是 PCI 合规、久经考验和处理付款处理。你的 headless 前端通过 Storefront API 创建购物车，然后重定向到 Shopify 的托管结账。结账扩展让你在 Shopify 的扩展点内自定义体验。

Headless 和 Liquid 主题之间的性能差异是什么？ 我们 400+ 个站点的数据显示 headless 店铺在核心网络生命体征指标上比 Liquid 主题快 60-75%。具体来说，中位数 LCP 从 2.3-3.5 秒（Liquid）下降到 0.7-1.0 秒（headless）。这转化为平均 10-15% 的转化率提升。

我应该为我的 headless Shopify 店铺使用 Hydrogen 还是 Next.js？ 如果你的团队了解 Next.js，使用 Next.js。如果你从零开始，想要最集成的 Shopify 体验，配置最少，Oxygen 上的 Hydrogen 是出色的。它们之间的性能差异可以忽略不计——团队专业知识和生态系统需求应该驱动你的决策。

对于 headless，我需要 Shopify Plus 吗？ 从技术上讲，不需要。Storefront API 在所有 Shopify 计划上都可用。但实际上，大多数 headless 构建受益于 Plus 功能：结账扩展、脚本、组织 API 用于多店铺设置，以及更高的 API 速率限制。在 headless 有意义的收入水平（$1M+）上，你应该在 Plus 上。

Headless Shopify 迁移需要多长时间？ 典型的 Shopify Plus 到 headless 迁移需要有经验的团队 12-14 周。具有复杂目录、繁重自定义或多市场设置的企业店铺可能需要 16-20 周。不要让任何人告诉你这是一个 4 周的工作——这就是你以坏的启动告终的方式。

当我转向 headless 时，我的 Shopify 应用会发生什么？ 这是最大的痛点之一。许多 Shopify 应用将脚本注入 Liquid 主题，这在 headless 前端上不起作用。你需要评估每个应用：有些提供你可以直接集成的 API，有些有 headless 兼容版本，有些将需要用自定义代码或替代服务替换。规划应用审计和迁移作为项目范围的一部分。

我可以将 Astro 或其他非 React 框架与 Shopify 的 Storefront API 一起使用吗？ 绝对可以。Storefront API 是标准 GraphQL API——任何可以发出 HTTP 请求的框架都可以使用它。我们用 Astro、SvelteKit 甚至纯 JavaScript 构建了 Shopify 店铺。折衷是 Shopify 的官方工具（Hydrogen、购物车实用程序等）基于 React，所以你将用其他框架编写更多自定义集成代码。