在过去三年中，我已经将十多个 Shopify 商店迁移到 headless 架构。有些进展顺利，有些则是噩梦。区别几乎总是归结为规划 — 具体来说，是团队在编写第一行代码之前是否理解他们实际上在做什么。

本指南涵盖了我希望在第一次 headless Shopify 迁移之前有人告诉我的一切：选择哪个前端框架、如何保护你的 SEO 排名、如何在切换期间实现零停机、实际成本是多少，以及基于商店复杂性的现实时间表。没有含糊其辞。没有不解释原因的"视情况而定"。

目录

Shopify 到 Headless 迁移：Next.js、Hydrogen 和 Remix 指南

为什么要从 Shopify 迁移到 Headless？

让我们先把这个问题搞清楚：标准 Shopify 对大多数商店来说都很好。如果你的年销售额在 200 万美元以下，你的主题能满足你的需求，你可能不需要 headless。说真的。比起劝人们进行这次迁移，我劝阻他们的次数更多。

但有合理的理由去选择 headless：

  • 性能瓶颈：Liquid 主题有渲染瓶颈。即使使用 Online Store 2.0 和 Dawn，你也受限于 Shopify 的服务器端渲染管道。Headless 商店一致地实现了低于 1 秒的 LCP 分数。
  • 自定义体验：产品配置器、AR 试穿、复杂筛选、个性化引擎 — 这些在 Liquid 中构建会很痛苦。
  • 多店铺前端：一个后端为你的 DTC 站点、批发门户、移动应用和国际商店提供支持。
  • 内容丰富的品牌：如果你的品牌严重依赖编辑内容、画册和故事讲述，将 headless CMS 与 Shopify 的商务引擎配对会给你两个世界的最佳体验。
  • 开发者体验：你的团队想在 React/TypeScript 中工作，而不是 Liquid。这比人们承认的更重要。

性能收益是真实的且可衡量的。在 2026 年，Google 的核心网页活力直接影响你的搜索排名。我迁移到 headless 的商店通常看到 LCP 改善 30-50% 和总阻塞时间改善 40-60%。这转化为可衡量的转化率提高 — Shopify 自己的数据表明页面速度每改善 1%，转化率可能增加 0.7%。

Headless Shopify 架构解析

当人们说"headless Shopify"时，他们指的是将前端（客户看到的）与后端（Shopify 的商务引擎）分离。你保留 Shopify 用于产品、库存、订单、结账和支付。你构建一个通过 Storefront API 与 Shopify 通信的自定义前端。

这是典型的架构：

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   自定义前端     │────▶│  Storefront API   │────▶│  Shopify 后端    │
│ (Next.js/H2/Remix)│   │  (GraphQL)        │     │ (产品、购物车、  │
│                 │     │                  │     │   订单等)        │
└─────────────────┘     └──────────────────┘     └─────────────────┘
        │
        ▼
┌─────────────────┐
│  Headless CMS   │
│ (Sanity、Contentful、│
│   Storyblok)     │
└─────────────────┘

Shopify Plus 商户可以访问 Checkout Extensibility API，这允许你在不重定向到 Shopify 的托管结账的情况下自定义结账。对于非 Plus 商店，客户仍然会被重定向到 checkout.shopify.com 进行实际购买 — 这其实不是一个糟糕的体验，但它是一个用户体验中断。

Storefront API

所有内容都通过 Shopify 的 Storefront API 运行，这是一个 GraphQL 端点，处理：

  • 产品查询和集合
  • 购物车管理（创建、更新、删除行项目）
  • 客户认证
  • 内容（元字段、元对象）
  • 商店本地化和货币

API 有速率限制 — 单个应用每秒 50 个成本点。在实践中，如果你缓存得当，这很少是个问题，但在你未计划的闪购期间可能会出现问题。

# 示例：获取带有变体的产品
query ProductQuery($handle: String!) {
  product(handle: $handle) {
    id
    title
    descriptionHtml
    priceRange {
      minVariantPrice {
        amount
        currencyCode
      }
    }
    variants(first: 100) {
      edges {
        node {
          id
          title
          availableForSale
          price {
            amount
          }
          selectedOptions {
            name
            value
          }
        }
      }
    }
    images(first: 10) {
      edges {
        node {
          url
          altText
          width
          height
        }
      }
    }
  }
}

选择你的前端：Next.js 与 Hydrogen 与 Remix

这是大多数团队卡住的地方。这是我用所有三个平台构建生产商店后的诚实看法。

功能 Next.js 15 Hydrogen 2026 Remix (Shopify)
框架成熟度 非常成熟，庞大的生态系统 成熟中，Shopify 特定 成熟（合并到 React Router 7）
Shopify 集成 通过 Storefront API 手动集成 第一方，内置 hooks 通过 Hydrogen UI 很好
托管 Vercel、Netlify、自托管 Oxygen (Shopify) 或自托管 任何地方，但针对 Oxygen 优化
学习曲线 中等 中等-高 中等
社区/招聘 庞大 小但增长中 中等
SSR/SSG 灵活性 优秀（App Router） SSR 重点（流式） SSR 重点（loaders）
缓存控制 ISR、按需重新验证 Oxygen 子请求缓存 标准 HTTP 缓存
最适合 有 React 经验的团队，复杂内容需求 Shopify 原生团队，简单到中等商店 想要 Shopify 推荐路径的团队

Next.js：安全的选择

Next.js 是我对大多数团队的建议，特别是如果你将 Shopify 与 headless CMS（如 Sanity 或 Contentful）配对。生态系统是巨大的，招聘更容易，你通过 App Router 的服务器组件获得令人难以置信的灵活性。

缺点？你必须自己连接 Shopify 集成。没有针对 Next.js 的官方 Shopify SDK（尽管社区包如 @shopify/hydrogen-react 为你提供购物车 hooks 和实用程序）。你会花更多时间在样板代码上。

我们在 Social Animal 用 Next.js 构建很多 headless Shopify 商店 — 对于电商项目，它是我们最受欢迎的堆栈。

Hydrogen：Shopify 的官方框架

Hydrogen 是 Shopify 的官方 headless 框架，建立在 Remix（现在是 React Router 7）之上。它附带预构建的产品、购物车和 SEO 组件 — 加上与 Oxygen（Shopify 的边缘托管平台）的紧密集成。

吸引力很清楚：更少的样板代码、Shopify 优化的缓存和一个在 Oxygen 上能正常工作的部署故事。最近的版本带来了重大改进，包括更好的 TypeScript 支持和购物车操作的乐观 UI 更新。

缺点？社区更小，当你卡住时资源更少，你在某种程度上被锁定在 Shopify 的生态系统中。如果你曾想交换商务后端，你会重写比使用 Next.js 更多的代码。

Remix / React Router 7

这是令人困惑的部分：Remix 已被合并到 React Router 7。Hydrogen 建立在 Remix 上。所以在大多数情况下，"Shopify 的 Remix"实际上意味着 Hydrogen。

如果你想使用不带 Hydrogen 的 Shopify 特定抽象的 React Router 7，你可以。你会获得相同的 loader/action 模式、相同的流式 SSR 和对 Shopify 集成的完全控制。如果你已经是一个 Remix 团队并希望获得最大灵活性，这就有了意义。

我的建议

对于内容丰富、页面布局复杂的品牌：Next.js + headless CMS。对于想要最快速路上线的直接商店：Oxygen 上的 Hydrogen。对于已经投资 Remix 生态系统的团队：带有 Hydrogen UI 组件的 React Router 7。

Shopify 到 Headless 迁移：Next.js、Hydrogen 和 Remix 指南 - 架构

分步迁移流程

这是我对每次迁移都遵循的流程。这很无聊。它有效。

第 1 阶段：审计和规划（2-3 周）

  1. 爬取现有站点 — 使用 Screaming Frog 或 Sitebulb 来目录化每个 URL、重定向、规范标签和结构化数据块。导出这个。你之后会需要它。
  2. 记录所有集成 — Klaviyo、Yotpo 评论、忠诚度计划、订阅应用（Recharge、Loop）、支付网关。每一个。
  3. 映射 URL 结构 — 你的新 URL 会与旧的匹配吗？Shopify 使用 /products/product-handle 和 /collections/collection-handle。如果你改变这些，你需要重定向。
  4. 识别自定义功能 — 标准浏览和购买之外的任何东西。礼品卡、捆绑、批发定价、多货币、B2B。
  5. 选择你的堆栈 — 前端框架、CMS、托管、CDN。

第 2 阶段：构建前端（6-12 周）

这是实际开发发生的地方。关键领域：

  • 产品页面，带有变体选择、图像库、评论集成
  • 集合页面，带有筛选、排序、分页
  • 购物车，带有实时库存检查和追加销售
  • 搜索 — Shopify 的预测搜索 API 或第三方如 Algolia
  • 客户账户 — 登录、订单历史、地址管理
  • CMS 驱动的页面 — 主页、关于、登陆页面
  • 结账重定向 — 处理到 Shopify 结账的交接
// 示例：带有 ISR 的 Next.js 产品页面
import { getProduct } from '@/lib/shopify'
import { ProductDetails } from '@/components/product-details'

export async function generateStaticParams() {
  const products = await getAllProductHandles()
  return products.map((handle) => ({ handle }))
}

export default async function ProductPage({ 
  params 
}: { 
  params: { handle: string } 
}) {
  const product = await getProduct(params.handle)
  
  if (!product) notFound()

  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{
          __html: JSON.stringify(generateProductJsonLd(product)),
        }}
      />
      <ProductDetails product={product} />
    </>
  )
}

export const revalidate = 60 // ISR: 每 60 秒重新验证一次

第 3 阶段：集成和质量保证（2-4 周）

连接所有第三方服务。测试所有内容。我是说所有内容：

  • 跨所有支付方法下达测试订单
  • 测试折扣代码、礼品卡、自动折扣
  • 验证分析跟踪（GA4、Meta Pixel、TikTok Pixel）
  • 在预期流量下对 Storefront API 调用进行负载测试
  • 在实际设备上测试，而不仅仅是 Chrome DevTools

第 4 阶段：切换（1-2 天）

实际切换。在下面的零停机部分中有更多信息。

迁移期间的 SEO 保护

这是迁移出错的地方。我见过商店因为有人忘记了 URL 重定向而损失 40% 的有机流量。不要成为那个团队。

URL 映射

在编写单个重定向规则之前，创建一个完整的 URL 映射文档。旧网站上的每个 URL 都需要一个目标新网站上的地址。

旧：/collections/summer-2024
新：/collections/summer-2024  ← 相同？好的，不需要重定向。

旧：/blogs/news/our-story
新：/journal/our-story  ← 不同？需要 301 重定向。

旧：/pages/about-us
新：/about  ← 不同？需要 301 重定向。

结构化数据

Shopify 主题包括基本的结构化数据。当你转向 headless 时，你负责自己实现它。至少：

  • Product 架构，带有 offers、aggregateRating
  • 导航的 BreadcrumbList
  • 品牌的 Organization
  • 带有 SearchAction 的 sitelinks 搜索的 WebSite
  • 适用时的 FAQPage

元标签和规范

每个页面都需要适当的 <title>、<meta description>、规范 URL 和 Open Graph 标签。在 Next.js 中，使用 Metadata API：

export async function generateMetadata({ params }): Promise<Metadata> {
  const product = await getProduct(params.handle)
  
  return {
    title: product.seo.title || product.title,
    description: product.seo.description || product.description,
    openGraph: {
      images: [product.featuredImage?.url],
    },
    alternates: {
      canonical: `https://yourstore.com/products/${params.handle}`,
    },
  }
}

XML 站点地图

从 Shopify 的数据动态生成站点地图。包括产品、集合和 CMS 页面。迁移后立即将其提交到 Google Search Console。

迁移前 SEO 检查清单

  • 完整的 URL 映射文档
  • 配置和测试的 301 重定向
  • 实现并验证的结构化数据
  • 从 Shopify SEO 字段提取的元标签
  • 动态生成的 XML 站点地图
  • 正确配置的 robots.txt
  • 通知 Google Search Console 域名更改（如适用）
  • 更新的内部链接到新 URL 结构
  • 从 Shopify 保留的图像替代文本

零停机迁移策略

零停机不是魔法。这是 DNS 管理和准备。

蓝绿部署方法

  1. 在临时域上构建和部署新站点（例如，new.yourstore.com）
  2. 同时运行两个站点至少一周，彻底测试新站点
  3. 配置你的 CDN/DNS 以支持即时切换（Cloudflare、Vercel 或 Netlify 都支持这一点）
  4. 切换 DNS 以指向新前端 — TTL 应提前设置为 60 秒
  5. 监控所有内容：错误率、404、转化率、Core Web Vitals

代理方法（更安全）

对于超过 100 万美元/月的商店，我倾向于基于代理的迁移：

  1. 在旧网站和新网站前面放置反向代理（Cloudflare Workers、Vercel Edge Middleware）
  2. 路由流量逐页 — 从低风险页面如 /about 开始
  3. 逐步将页面迁移到新前端，持续 2-4 周
  4. 在移动下一批之前监控每个页面的性能
  5. 产品和集合页面最后（最高收入风险）

这种方法增加了复杂性，但允许你在影响整个商店之前捕获问题。

// Vercel Edge Middleware 示例，用于渐进式迁移
import { NextResponse } from 'next/server'

export function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl
  
  // 已迁移到新前端的页面
  const migratedPaths = ['/about', '/contact', '/journal']
  
  if (migratedPaths.some(path => pathname.startsWith(path))) {
    return NextResponse.next() // 从新前端提供
  }
  
  // 所有其他内容代理到旧 Shopify 商店
  return NextResponse.rewrite(
    new URL(pathname, 'https://old-store.myshopify.com')
  )
}

定价和时间表分解

让我们谈论真实数字。这些是基于我在 2026 年看到的项目，范围从简单的 DTC 商店到复杂的多市场运营。

商店复杂性 时间表 机构成本 自由职业者成本
简单（< 50 个产品、基本页面、标准结账） 8-12 周 $40,000 - $75,000 $20,000 - $40,000
中等（50-500 个产品、CMS、订阅、多货币） 12-20 周 $75,000 - $150,000 $40,000 - $80,000
复杂（500+ 产品、B2B+DTC、自定义结账、多个集成） 20-32 周 $150,000 - $300,000+ $80,000 - $150,000

持续成本

不要忘记经常性费用：

  • Shopify Plus：$2,300/月（对于结账可扩展性是必需的，对 headless 是推荐的）
  • 托管：$20-500/月（Vercel Pro 是 $20/用户，Oxygen 包含在 Shopify 中）
  • Headless CMS：$0-500/月（Sanity、Contentful、Storyblok 都有免费层）
  • 搜索：$0-500/月，如果使用 Algolia 或类似的
  • 维护：预算初始构建成本的 10-15% 年度费用

对于探索 headless Shopify 迁移对其特定情况成本的团队，我们在这里分解了我们的定价方法。我们也很乐意在快速通话中为事情定范围。

常见迁移陷阱

1. 低估购物车

购物车看起来很简单，直到你考虑：折扣代码、自动折扣、礼品卡、行项目属性、购物车备注、估计运费、税收计算和购物车级元字段。为购物车功能预算两倍的时间。

2. 忘记应用

你依赖的 Shopify 应用生态系统？大多数应用将 JavaScript 注入到你的 Liquid 主题。转向 headless 意味着你需要基于 API 的替代方案或针对评论、愿望列表、忠诚度计划等的自定义实现。

3. 结账自定义

没有 Shopify Plus（$2,300/月），你无法自定义结账体验。客户将被重定向到 Shopify 的托管结账，这会造成视觉上的脱节。Plus 商户可以使用 Checkout Extensibility，但它仍然比完全自定义结账更受限制。

4. 不进行早期性能测试

Storefront API 增加了延迟。如果你进行 8 次 API 调用来呈现产品页面，你会感受到它。积极缓存，使用 GraphQL 片段来最小化过度获取，并在可能的情况下实现流式 SSR。

5. 忽视内容团队

你的营销团队在 Shopify 的管理员中管理内容。现在他们需要一个 headless CMS。预算时间用于培训和构建实际上令人愉快的内容编辑体验。这就是headless CMS 开发专业知识真正重要的地方。

何时 Headless 不是正确选择

我会直言不讳：headless Shopify 不适合所有人。如果出现以下情况，请不要迁移：

  • 你的商店年销售额在 100 万美元以下，你没有复杂的自定义需求
  • 你没有预算用于持续开发和维护
  • 你的团队没有 React 开发人员（或没有预算来雇用/聘用他们）
  • 你对当前主题的性能和功能感到满意
  • 你主要在寻找"酷科技"故事，而不是解决实际业务问题

Shopify 的 Online Store 2.0 与优化良好的主题可以在 Lighthouse 上获得 90+。有时正确的答案是优化你已有的东西，而不是从头开始重建。

如果你在犹豫，考虑从混合方法开始：保留你的 Shopify 主题但将特定的高影响力页面（如你的主页或登陆页面）构建为 headless。你可以在现有主题旁边使用 Shopify 的 Storefront API。这让你在承诺完全迁移之前证明价值。

常见问题

从 Shopify 迁移到 headless 需要多长时间？ 对于典型的中等复杂度商店，预计从启动到启动需要 12-20 周。少数产品和基本功能的简单商店可以在 8-12 周内发送。具有自定义结账和广泛集成的复杂多市场商店通常需要 20-32 周。审计和规划阶段本身应该是 2-3 周 — 不要跳过它。

迁移到 headless Shopify 时我会丧失 SEO 排名吗？ 如果做得正确，就不会。关键是：保持相同的 URL 结构（或设置适当的 301 重定向）、在每个页面类型上实现结构化数据、保留元标签和规范 URL，以及在启动后立即向 Google Search Console 提交更新的站点地图。我通常看到迁移后排名波动 1-2 周，一旦 Google 识别出更好的 Core Web Vitals 分数，就会改进。

Headless 需要 Shopify Plus 吗？ 技术上不需要。Storefront API 在所有 Shopify 计划上都可用。但是，Shopify Plus 为你提供 Checkout Extensibility（自定义结账体验）、更高的 API 速率限制和访问 Oxygen 托管。对于认真的 headless 项目，Plus 每月 $2,300 几乎总是值得的。

Hydrogen 和将 Next.js 与 Shopify 一起使用有什么区别？ Hydrogen 是 Shopify 的官方 headless 框架，建立在 Remix/React Router 7 之上。它开箱即用地包括 Shopify 特定的组件、hooks 和实用程序，加上 Oxygen 上优化的部署。Next.js 需要你自己构建 Shopify 集成，但为你提供了更大的生态系统、更多的托管选项和对复杂内容架构的更好支持。大多数机构，包括我们的，基于特定的项目需求在这里有很强的观点。

我可以通过零停机迁移到 headless Shopify 吗？ 是的，使用蓝绿部署（DNS 切换）或渐进式代理迁移。蓝绿方法通过 DNS 一次切换所有流量，而代理方法在数周内逐步迁移页面。两者都有效。代理方法对于高收入商店更安全，但增加了复杂性。

Headless Shopify 迁移成本多少？ 机构成本通常从简单商店的 $40,000 到复杂多市场运营的 $300,000+ 不等。自由职业者费率大约是机构成本的 50-60%，但可能缺少项目管理结构和专家数量。持续成本包括 Shopify Plus（$2,300/月）、托管（$20-500/月）、CMS（$0-500/月）和维护（初始构建成本的 10-15% 年度）。

对于 headless Shopify，我应该使用 Astro 而不是 Next.js 或 Hydrogen 吗？ Astro 是内容丰富的站点（带有可交互的岛屿）的绝佳选择，我们已经构建了几个由 Astro 驱动的店铺。它对于目录式商店运作良好，其中大多数页面是静态的，你只需要 React（或 Svelte、Vue）用于购物车等交互式组件。但是，对于具有大量客户端交互性的商店 — 实时库存、复杂筛选、即时搜索 — Next.js 或 Hydrogen 的完整 React 运行时通常是更好的适配。

迁移到 headless 后我的 Shopify 应用会发生什么？ 大多数注入前端代码的 Shopify 应用（弹出窗口、小部件、评论显示）不会开箱即用。你需要直接使用应用的 API、找到 headless 兼容的替代方案，或构建自定义实现。仅在后端运行的应用（库存管理、运费、ERP 集成）通常继续工作而无需更改。始终在规划阶段审计你的应用堆栈。