Hydrogen（@shopify/hydrogen）是Shopify用于在你已经使用的JavaScript框架中构建无头商店界面的工具包。它自带了代理技能，教编码代理如何使用它。

文档 ·API参考 ·更新日志

[!注] 本 README 涵盖了 Hydrogen 2026-10 及以后版本。Hydrogen 2026-04 及更早版本在 2026-04 分支，文档在 Legacy Hydrogen 中。要迁移商店，请点击迁移到最新版本的 Hydrogen。

包含了什么

• Storefront API 客户端：类型化 gql() 查询、缓存和类型错误。
• 请求处理程序：Shopify 商店前端所需的路由，如 Storefront API 代理、/api/cart、结账和购物车永久链接、URL 重定向，以及代理的 MCP 端点。
• Cart：服务器处理器、在JavaScript加载前运行的HTML表单，以及在服务器响应前显示行变更的存储。
• 产品与集合：变体选择、集合筛选、排序和分页。
• 预测搜索：一个带有服务器处理器和表单辅助的搜索存储。
• 资金：Shopify MoneyV2 金额格式化买家所在地和货币。

Hydrogen

Hydrogen (@shopify/hydrogen) is Shopify’s toolkit for building headless storefronts in the JavaScript framework you already use. It ships with agent skills that teach coding agents how to use it.

Documentation · API reference · Changelog

[!NOTE] This README covers Hydrogen 2026-10 or later. Hydrogen 2026-04 and earlier are on the 2026-04 branch, with docs in Legacy Hydrogen. To migrate a storefront, follow Migrate to the latest version of Hydrogen.

What’s included

• Storefront API client: typed gql() queries, caching, and typed errors.
• Request handlers: the routes a Shopify storefront needs, such as the Storefront API proxy, /api/cart, checkout and cart permalinks, URL redirects, and the MCP endpoints for agents.
• Cart: server handlers, HTML forms that work before JavaScript loads, and a store that shows line changes before the server responds.
• Products and collections: variant selection, collection filters, sorting, and pagination.
• Predictive search: a search store with server handlers and form helpers.
• Money: formats Shopify MoneyV2 amounts for the buyer’s locale and currency.
• Markets: country and language context for Shopify Markets.
• Analytics: Shopify storefront analytics with consent handling.
• Shop Pay: Shop Pay buttons.
• Customer accounts: the Customer Account API client, login and logout handlers, and sessions.

Get started

You need a Shopify store with Storefront API access from the Headless channel. Until you connect one, the template and the setup skill fall back to mock.shop, a public Storefront API with demo data.

Deploy a template

React Router on Oxygen. Shopify’s starter template, templates/react-router, deployed to Oxygen from your Shopify admin.

Next.js on Vercel. Vercel Shop is a Next.js storefront built on Hydrogen and maintained by Vercel.