SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hydrogen-dev-workflow

hydrogen-dev-workflow

编程与开发

查看项目

更新于 10-16 04:36

技能介绍

Hydrogen 开发工作流

本技能是面向在 Shopify 无头店面生态中工作的工程师的开发实践与工作流指南。Hydrogen 框架仓库为 Shopify/hydrogen。领域背景参见 headless-storefronts-context 技能，仓库位置参见 shopify-repos 技能。

一、本地测试客户账户

要测试 Hydrogen 中任何需要客户登录的功能（订单历史、账户页面等）：

  1. 使用客户账户推送标志启动开发服务器：

使用 npm

pnpm run dev -- --customer-account-push

直接使用 Hydrogen CLI（h2 是 Hydrogen CLI 二进制文件）

h2 dev --customer-account-push

注意使用 pnpm run dev 时的 -- 分隔符。

  1. 使用 bogus gateway 测试支付信息下一笔测试订单。

  2. 使用任意邮箱和密码创建客户账户。

  3. 下单后即可登录，在客户账户区域查看订单。

二、Hydrogen Recipes（食谱）

Recipes 是记录在开发文档中的 cookbook 条目，用于向 Hydrogen 店面添加功能。它们以 markdown 文件形式存在于开发文档中。“apply”命令及相关工具仅供内部使用，用于测试或更新 recipes——商家无法以编程方式将 recipes 应用到其店面。

Cookbook 架构：Ingredients 与生成的文档

每个 recipe 有两层需要保持同步：

  • Ingredient 文件（cookbook/recipes/{name}/ingredients/templates/skeleton/app/routes/*.tsx）：这些是真实、独立的 .tsx 路由实现——不是补丁或 diff。商家按 recipe 操作时会应用它们。当骨架模板存在 bug（例如缺少 await）时，对应的 cookbook ingredient 文件可能独立存在相同 bug，需要单独修复。

  • 生成的文档（cookbook/recipes/{name}/README.md 和 cookbook/llms/{name}.prompt.md）：这些文件由 ingredient 源文件自动生成。它们内联了完整的路由源代码，因此如果修复了 ingredient .tsx 文件，必须同时重新生成文档：

pnpm run cookbook -- render --recipe {name} pnpm run cookbook -- validate --recipe {name}

README.md 和 llms/{name}.prompt.md 必须作为同一次修复的一部分提交。未重新生成意味着即使 ingredient 文件已正确，文档仍会教授错误的模式。

示例：markets recipe 的 ingredient 文件包括 ($locale).account.$.tsx、($locale).account.addresses.tsx 和 ($locale).account.profile.tsx。它们独立于骨架模板，不会自动继承骨架的修复。

三、修复损坏的 Recipes（补丁文件）

当骨架模板变更时，recipe 补丁文件可能损坏。两种方法：

  • 对于简单的一行改动：直接编辑补丁文件。

  • 对于非简单改动：

    1. 在本地创建新分支
    2. 硬重置到 recipes 仍能干净应用的最新提交
    3. 对每个 recipe： a. 应用 recipe b. 使用 Claude/LLM 将该提交到最新 main 的所有变更应用到已应用 recipe 的骨架模板上 c. 生成新的补丁文件 d. 取消应用 recipe，对下一个重复

四、升级 Hydrogen

升级 Hydrogen 店面的最佳方式是 upgrade CLI 命令：

pnpm exec shopify hydrogen upgrade

该命令会：

  • 自动升级并安装所有必要依赖
  • 对于手动更改，生成一个包含所有必需更改的 markdown 文件

该 markdown 文件非常适合喂给 Claude 或其他 LLM 来应用更改。

最佳实践：跨多个主版本升级时，一次升级一个主版本，并在每次升级之间验证一切正常。这比一次性尝试多个主版本升级更顺畅。

五、骨架模板（Skeleton Template）

骨架模板有两个用途：

  • 内部测试：它是我们用来测试和验证 Hydrogen 变更的单一 Hydrogen 店面。位于 Hydrogen 仓库的 templates/skeleton。
  • 新项目脚手架：当用户搭建新 Hydrogen 项目（通过 shopify hydrogen init 或 npm create @shopify/hydrogen）时，会获得骨架模板的副本。

关键事实：

  • 位于 Hydrogen monorepo 的 templates/skeleton
  • 使用 monorepo 中构建版本的 Hydrogen 包（而非来自 npm）
  • 随 Hydrogen CLI 打包并发布
  • 在 Hydrogen CLI 发布前应始终保持最新
  • 即使 Hydrogen CLI 版本未升级，也可以在发布前更新
  • 对骨架模板的任何更改都需要 changeset——详见 CLAUDE.md 中的 Changeset Rules

六、PR 约定

将 Issue 链接到 PR：始终在 PR 中包含 GitHub issue 的链接。使用 Closes <issue> 或 Fixes <issue>，以便 PR 合并时 issue 自动关闭。

七、Hydrogen 分析架构

packages/hydrogen/src/analytics-manager/ 中的分析系统有几个非显而易见的设计约束，调试前值得了解。

模块级单例

subscribers、registers 和 waitForReadyQueue 是模块级（而非实例级）的。这意味着：

  • 它们跨 React 渲染和 React 树卸载/重新挂载持续存在
  • 在测试中，它们跨测试用例累积状态——一个调用 register() 而未调用 ready() 的测试会阻塞所有后续测试
  • 每个 JS 上下文恰好有一个分析总线；多个 <Analytics.Provider> 实例共享状态

同意（Consent）在订阅者而非发布者处强制执行

publish() 始终将事件入队，无论同意状态如何。同意在三个下游层强制执行：

  • ShopifyAnalytics 仅在 privacyReady 为 true（隐私 SDK 已加载）后调用 shopifyAnalyticsReady()
  • prepareBasePageViewPayload 在处理器调用时评估 customerPrivacy.analyticsProcessingAllowed()
  • sendShopifyAnalytics（在 hydrogen-react 中）如果 payload.hasUserConsent 为 false 则丢弃事件

不要向 publish() 添加同意门控——这会导致事件在同意解决之前被丢弃（而非排队），造成竞态条件，初始化期间触发的事件将永久丢失。

八、Hydrogen CLI

Hydrogen CLI 源代码位于 Hydrogen 仓库的 packages/cli-hydrogen。它作为独立包发布到 npm。

在 Shopify CLI 中打包：商家通常不直接使用 Hydrogen CLI。相反，它被打包在 Shopify CLI 中（位于 Shopify/cli 仓库）。将新版本的 Hydrogen CLI 发布到 npm 后，还必须提升其在 Shopify CLI 中的版本。

时机：Shopify CLI 按固定节奏发布新的次版本。Hydrogen CLI 的版本提升不应等待下一个 Shopify CLI 次版本——将提升作为当前 Shopify CLI 次版本的补丁发布，以便更快推出。

如何更新：Hydrogen 仓库中存在 shopify-cli-update 命令，位于 .claude/commands/shopify-cli-update.md。这是一个 Claude Code 命令——在 Hydrogen 仓库中工作时用 /shopify-cli-update 调用。它记录了完整、细致、多步骤的流程。执行更新时始终参考此命令——不要凭记忆即兴操作。

九、项目脚手架

搭建新 Hydrogen 项目有两种方式：

  • shopify hydrogen init——通过 Shopify CLI（其中打包了 Hydrogen CLI）
  • npm create @shopify/hydrogen——通过 create-hydrogen 包

两者最终都使用骨架模板。create-hydrogen 包在底层使用 Hydrogen CLI 的 init 函数。

十、版本标签

  • @latest：最新的官方发布
  • @next：包含所有已合并到 main 的 Hydrogen 变更（带 changesets），即使尚未正式发布。每次代码推送到 main 时都会自动发布新的 next 版本。

next 标签对商家 bug 修复验证很有用：将修复合并到 main 后，商家可以用 npm create @shopify/hydrogen@next 测试，确认修复解决了他们的问题——无需等待官方发布。

十一、搭建特定版本

create-hydrogen 使用 SemVer，而 Hydrogen 使用 CalVer——两者关系详见 hydrogen-versioning 技能。搭建特定历史 Hydrogen 版本需要查找步骤，以确定哪个 create-hydrogen SemVer 版本包含所需的 Hydrogen CalVer 骨架。

十二、相关技能

  • hydrogen-release-process——发布流程、回补修复、changelog.json、发布失败恢复
  • hydrogen-versioning——CalVer 格式、版本支持策略、发布节奏
  • CLAUDE.md——Changeset 规则（适用于每个 PR）、骨架/CLI 打包链