用途
Shopify Hydrogen 是 Shopify 为无头电商（headless commerce）提供的官方技术栈，基于 React Router v7 构建。它提供工具、处理器与组件，用于在 Shopify Storefront API 之上构建店面（storefront）。
所有导出均来自 @shopify/hydrogen，该包会重新导出 @shopify/hydrogen-react 的全部内容。源码地址：https://github.com/Shopify/hydrogen/tree/main/packages/hydrogen/src
主要能力
createHydrogenContext
在 server.ts 中设置全部 Hydrogen 服务的单一入口。创建并串联 storefront、customerAccount 和 cart。
- 必需环境变量：
PUBLIC_STORE_DOMAIN、PUBLIC_STOREFRONT_API_TOKEN、PRIVATE_STOREFRONT_API_TOKEN、PUBLIC_STOREFRONT_ID、PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID、SHOP_ID - 返回：
{ storefront, customerAccount, cart }
缓存策略
| 策略 | maxAge | staleWhileRevalidate | 适用场景 |
|---|---|---|---|
| CacheNone() | — | — | 用户特定或实时数据 |
| CacheShort() | 1s | 9s | 频繁变化的数据 |
| CacheLong() | 1hr | 23hr | 稳定数据（店铺信息、菜单） |
| CacheCustom({...}) | 自定义 | 自定义 | 细粒度控制 |
Cart Handler
createCartHandler 提供所有购物车操作：get、create、addLines、updateLines、removeLines、updateDiscountCodes、addGiftCardCodes、updateBuyerIdentity、updateNote、setMetafields 等。
CartForm
用于购物车变更的表单组件。使用 CartForm.ACTIONS 枚举（LinesAdd、LinesUpdate、LinesRemove、DiscountCodesUpdate 等），并通过 React Router 的 useFetcher 提交。
useOptimisticCart
在本地应用待处理的购物车变更，以实现即时 UI 反馈。需要 LinesAdd 输入中包含 selectedVariant。
分页
getPaginationVariables(request, { pageBy }) + <Pagination connection={...}> 组件。GraphQL 查询必须包含 pageInfo { hasPreviousPage hasNextPage startCursor endCursor }。
SEO
getSeoMeta(...) 生成 React Router 的 meta 数组。支持 title、titleTemplate、description、url、media、jsonLd、robots、alternates。jsonLd 会在各路由间拼接。
Sitemaps
getSitemapIndex + getSitemap —— 两级站点地图生成。需要 Storefront API 2024-10 及以上版本。
内容安全策略（CSP）
createContentSecurityPolicy({ shop: { checkoutDomain, storeDomain } }) 返回 { nonce, header, NonceProvider }。
使用方式
在线文档搜索
在技能包自身文件夹内运行以下命令（路径相对于技能根目录）：
node scripts/search_shopify_docs.mjs "<query>"
该脚本直接查询 Shopify 开发者文档（shopify.dev），返回 Hydrogen 的最新 API 参考、代码示例与指南。
示例：
node scripts/search_shopify_docs.mjs "createHydrogenContext"
node scripts/search_shopify_docs.mjs "CartForm actions"
node scripts/search_shopify_docs.mjs "caching strategies"
node scripts/search_shopify_docs.mjs "getSeoMeta"
node scripts/search_shopify_docs.mjs "Pagination component"
离线/缓存参考
当搜索脚本不可用时，可参考以下文档：
| 文件 | 内容 |
|---|---|
| references/01-setup.md | 完整的 server.ts 设置、环境变量、会话、createHydrogenContext 选项 |
| references/02-caching.md | 缓存策略、AllCacheOptions 类型、generateCacheControlHeader |
| references/03-cart.md | 购物车路由设置、CartForm 示例、useOptimisticCart 模式 |
| references/04-ssr-performance.md | SSR 包瘦身（worker 内联动态导入 —— resolveId stub 模式）、包审计、TTFB 测量方法 |
适用场景
适用于基于 Shopify Storefront API 构建无头电商店面的开发场景，特别是需要购物车处理、缓存策略、分页、SEO、站点地图、CSP 等核心能力的 React Router v7 项目。
限制
站点地图功能需要 Storefront API 2024-10+ 版本。其余限制暂未提供。