使用 Hydrogen 的 Headless Shopify：构建高性能定制店面

无头商务将前端表示层与后端商务引擎解耦。 Shopify Hydrogen 是用于构建通过 Storefront API 连接到 Shopify 后端的自定义店面的官方框架。 Hydrogen 基于 Remix（基于 React 的全栈框架）构建，提供了特定于商业的组件、挂钩和实用程序，可在利用 Shopify 的购物车、结账和客户管理基础设施的同时加速开发。本指南涵盖了从架构决策到部署的所有内容。

要点

• Hydrogen 基于 Remix 和 React Server Components 构建，可实现最佳服务器端渲染性能
• Storefront API 提供对产品、产品系列和内容的读取访问；客户帐户 API 处理身份验证
• 商务组件（ProductPrice、CartForm、AddToCartButton）消除了样板文件，同时保持完全可定制
• 氧气托管提供针对氢气优化的边缘部署基础设施，并具有自动扩展功能
• 与 Shopify Liquid 主题相比，Largest Contentful Paint 的性能通常提高 30-50%

何时去无头

何时选择氢气

• 您的品牌需要超出 Liquid 主题功能的定制设计
• 您需要集成来自无头 CMS 的内容（Contentful、Sanity、Strapi）
• 性能是一个关键的竞争优势（页面加载时间不到 1 秒）
• 您的前端团队更喜欢 React 和现代 JavaScript 工具
• 您需要渐进式网络应用程序 (PWA) 体验
• 您想要跨网络、移动设备和其他渠道共享组件

保持流畅的主题

• 现有主题可通过定制满足您的设计要求
• 您缺乏用于持续维护的前端开发资源
• 您需要非技术用户的完整 Shopify 管理主题编辑器体验
• 您的预算不支持自定义前端开发和托管

架构概述

氢气的工作原理

Hydrogen 架构包括：

Remix（全栈框架）：处理路由、服务器端渲染、数据加载和表单处理。每个路由定义一个 loader 函数（在服务器上运行）和一个组件（在客户端上呈现）。

店面 API (GraphQL)：产品信息、集合、搜索和内容的主要数据源。所有产品数据都通过此 API 流动，而不是直接访问数据库。

客户帐户 API：处理客户身份验证、订单历史记录和帐户管理。此 API 提供 Shopify 原生的无密码身份验证流程。

购物车 API：使用服务器端状态管理购物车。购物车操作（添加、更新、删除）使用 Shopify 的购物车基础设施。

结帐：Shopify 托管的结帐（结帐扩展性）。无头店面重定向到 Shopify 的结帐，后者处理付款处理、运输和订单创建。

数据流

项目设置

创建氢项目

使用 Shopify CLI 搭建新的 Hydrogen 项目：

使用 npx shopify hydrogen init 运行 Shopify Hydrogen CLI 以创建新项目。 CLI 提示：

1. 项目名称：您的店面名称
2. 模板：骨架（最小）、演示商店（完整示例）或自定义
3. 语言：TypeScript（推荐）或JavaScript
4. 样式：Tailwind CSS、CSS 模块或普通 CSS
5. Storefront API 凭证：商店域和 API 令牌

项目结构

Hydrogen 项目遵循 Remix 约定：

店面 API 连接

在 hydrogen.config.ts 中配置 Storefront API 连接：

• 商店域名：您的 myshopify.com 域名
• 店面 API 令牌：公共访问令牌（客户端使用安全）
• API 版本：店面 API 版本（例如 2026-01）
• 默认国家/语言：用于本地化定价和内容

构建核心页面

产品列表页面

产品系列页面使用 loader 函数从 Storefront API 获取产品：

加载器函数从 URL 参数接收集合句柄，使用分页查询 Storefront API（前 N 个产品），然后返回集合数据。该组件呈现一个包含图像、标题、价格和变体信息的响应式产品网格。

关键考虑因素：

• 分页：使用基于光标的分页（Storefront API 使用中继式连接）
• 过滤：通过产品查询中的 filters 参数应用过滤器
• 排序：支持价格、标题、畅销、相关性排序
• 无限滚动或“加载更多”：获取其他页面而无需重新加载整页

产品详细信息页面

产品页面获取包含所有变体、图像和元字段的单个产品：

加载程序通过句柄查询产品，包括定价变体、图像（具有响应式大小）以及包含扩展产品信息的任何元字段。该组件呈现图像库、变体选择器、价格显示和添加到购物车按钮。

购物车实施

Hydrogen 通过 CartForm 组件提供购物车实用程序：

CartForm 将购物车操作（添加、更新、删除）包装为无需 JavaScript 即可工作的表单提交（渐进增强）。购物车状态存储在 Shopify 购物车基础设施的服务器端，确保选项卡和设备之间的一致性。

购物车操作：

性能优化

服务器端渲染

Hydrogen 利用 Remix 的流式 SSR 来实现快速首字节时间 (TTFB)：

• 流式传输：服务器立即发送 HTML shell，然后在数据加载时流式传输动态内容
• 缓存标头：为 CDN 缓存的每个路由设置 Cache-Control 标头
• 重新验证时陈旧：在后台刷新时立即提供缓存内容

图像优化

使用 @shopify/hydrogen 中的 Image 组件来优化图像：

• 自动生成 srcset 响应图像
• 基于浏览器支持的WebP/AVIF格式交付
• 延迟加载首屏图像
• 加载期间占位符图像模糊

代码分割

Remix 按路线自动进行代码分割。额外优化：

• 对重型组件使用动态导入（图片库、3D 查看器）
• 页面加载后延迟加载第三方脚本（分析、聊天小部件）
• 使用 React 服务器组件最小化客户端 JavaScript

性能基准

与液体主题相比的典型氢性能：

使用氧气进行部署

什么是氧气？

Oxygen 是 Shopify 专为 Hydrogen 店面构建的托管平台。它部署到全球边缘网络：

• 根据流量自动缩放
• 内置 DDoS 防护
• SSL/TLS 证书管理
• CI/CD 与 GitHub 集成
• 环境变量管理
• 预览拉取请求的部署

部署过程

1.通过 Shopify 后台将您的 GitHub 存储库连接到 Oxygen 2.推送到主分支触发自动部署 3. Pull 请求生成用于测试的预览 URL 4.环境变量通过Shopify后台管理 5.自定义域名配置DNS CNAME记录

替代托管

虽然 Oxygen 针对 Hydrogen 进行了优化，但您可以部署到任何与 Node.js 兼容的托管：

• Vercel：具有边缘功能的出色混音支持
• Cloudflare Workers：使用 Workers 运行时进行边缘部署
• Fly.io：基于容器的部署，全球分布
• AWS：ECS、Lambda 或 App Runner 部署

无头 CMS 集成

内容架构

Hydrogen 店面通常与无头 CMS 平台集成以获取非产品内容：

流行的 CMS 集成

• Sanity：使用嵌入 Hydrogen 的 Sanity Studio 进行实时预览
• Contentful：GraphQL API 与内容建模集成
• Strapi：具有 REST 或 GraphQL API 的自托管选项
• Shopify Metaobjects：原生 Shopify 内容可满足更简单的要求

无头店面的 SEO

关键的 SEO 实施

• 服务器端渲染：所有内容都在服务器上渲染以供搜索引擎爬虫使用
• 元标签：使用 Remix 的 meta 导出作为标题、描述和 Open Graph 标签
• 结构化数据：产品、面包屑列表和组织的 JSON-LD 架构
• 站点地图：从店面 API 数据动态生成
• 规范 URL：防止跨变体和集合的重复内容
• Hreflang：实现多语言 Markets Pro 店面

ECOSIRE 氢气服务

构建无头 Shopify 店面需要前端开发专业知识和商务策略。 ECOSIRE 的 Shopify 自定义主题开发 团队构建了从概念到发布的 Hydrogen 店面。我们的速度优化服务 确保您的无头店面满足 Core Web Vitals 目标，而我们的持续支持 将随着 Shopify 平台的进步维护和发展您的店面。

相关阅读

• Shopify 无头商务与氢
• Shopify API 集成指南
• Shopify 页面速度优化指南
• Shopify 应用开发指南
• Shopify 主题定制指南

使用 Hydrogen 进行无头处理是否意味着失去 Shopify 的主题编辑器？

是的。 Hydrogen 店面不使用 Shopify 主题编辑器。内容更改需要更新代码或与提供可视化编辑体验的无头 CMS 集成。这是无头架构的主要权衡——以无代码编辑体验为代价获得最大的前端灵活性。

我可以仅在我的 Shopify 商店的一部分中使用 Hydrogen 吗？

不直接——氢取代了整个前端。但是，您可以使用混合方法：为主站点运行 Hydrogen 店面，并使用 Shopify 托管的结账来处理支付流程（这是标准方法）。一些商家还使用 Hydrogen 进行营销页面，同时保留目录的 Liquid 主题。

与 Liquid 主题相比，Hydrogen 店面的开发成本是多少？

由于 React 开发要求和基础设施设置，定制 Hydrogen 构建的成本通常比定制 Liquid 主题高 2-5 倍。然而，对于具有 React 经验的团队来说，持续的迭代速度更快，并且性能优势可以转化为可衡量的转换改进，从而证明投资的合理性。