用途：本技能是 Hydrogen 生态中所有版本方案的参考，帮助理解各产品的版本号含义、发布时间与支持策略。发布流程本身见 hydrogen-release-process，领域架构见 headless-storefronts-context。
Shopify GraphQL API 版本：Storefront API、Customer Account API、Admin API 均使用日历版本 YYYY-MM，用连字符而非点，无尾部 .0，如 2025-01、2025-04、2025-07、2025-10。每年发布四个版本，固定在发布月 1 日：Q1 为 1 月 1 日、Q2 为 4 月 1 日、Q3 为 7 月 1 日、Q4 为 10 月 1 日。此外始终存在 unstable 版本，新功能先进入其中，可能随时出现破坏性变更，仅供预览，不可用于生产。下一版本的候选版约提前 3 个月可用，与当季稳定版同日发布；例如 2026-01 发布时 2026-04 RC 同时可用，约 2026 年 3 月 18 日冻结破坏性变更，4 月 1 日正式发布。此约两周的冻结为内部政策，并非公开文档，不应当作对商户的官方保证。每个新版本的 API 变更发布在 Shopify 开发者更新日志中。
Hydrogen 版本：使用 YYYY.MAJOR.MINOR，用点而非连字符。YYYY 为日历年，MAJOR 为 Storefront API 发布月份（1、4、7、10），不是顺序计数，MINOR 为该主版本内的小版本或补丁号。例如 2025.7.0 对应 SF API 2025-07，2025.7.3 为其第三个补丁，2026.1.0 对应 2026-01。历史异常：2025.5.0 和 2025.5.1 是（目前唯一）脱离季度规律的版本，用于在 API 版本更新之间发布破坏性变更，暂无再次计划，但未来若需在季度更新之间发布重大变更仍可能发生。Hydrogen 的每个主版本与 SF API/CA API 版本更新同步，无论 API 是否含破坏性变更，因此 Hydrogen 每 3 个月可能出现破坏性变更。推导公式：SF API YYYY-MM 对应 Hydrogen YYYY.M.0，其中 M 为不带零填充的月份数字：01→1、04→4、07→7、10→10。
支持策略：Hydrogen 包与 Shopify GraphQL API 均至少有 365 天支持窗口，之后版本可能退役，但任何破坏性变更或退役生效前须至少提前 365 天通知。过期的 SF API 版本请求不会被拒绝，而是由当前支持的最旧版本自动处理，即 fall-forward，商户可能静默获得含破坏性变更的新行为；任何时刻通常存在 4 个有效版本（不含 unstable）。
实践影响：若破坏性变更或退役不影响商户的具体操作，版本过期后可能无需处理，但仍建议升级；当商户报告“店铺无故损坏”时，应检查其请求的 API 版本是否刚发生 fall-forward。
create-hydrogen 版本：包名为 @shopify/create-hydrogen（有作用域），而非 2024 年中止于 4.3.14 的旧无作用域 create-hydrogen。它使用 SemVer 而非 Hydrogen CalVer，因此 npm create @shopify/hydrogen@2025.7.0 无法直接工作，两者无直接对应，需要查找。npm create @shopify/hydrogen@VERSION 实际调用 @shopify/create-hydrogen@VERSION。查找命令：gh api repos/Shopify/hydrogen/releases --paginate --jq '.[] | select(.tag_name | test("create-hydrogen|@shopify/hydrogen@TARGET")) | {tag: .tag_name, date: .published_at}'，将 TARGET 替换为目标 CalVer，与 Hydrogen 发布仅相隔数秒的 create-hydrogen 即为正确匹配。已知映射：Hydrogen 2025.7.0 对应 @shopify/create-hydrogen 5.0.25（2025-09-30）。指定版本的脚手架命令：npm create @shopify/hydrogen@5.0.25。
相关技能：hydrogen-release-process、hydrogen-dev-workflow。