关于 hydrogen-upgrades
hydrogen-upgrades 面向 Shopify Hydrogen 开发者，提供按版本划分的迁移指南，涵盖破坏性变更、代码更新和逐步差异说明。还介绍如何使用 Shopify 升级命令行工具，并提供离线参考指南。
主要功能
- 01按版本划分的迁移指南
- 02破坏性变更与代码更新说明
- 03版本升级的逐步差异
- 04离线参考指南
适用场景
- 01规划 Hydrogen 版本升级
- 02依次处理多个版本跨度的变更
- 03检查升级命令行工具生成的源代码修改清单
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/hydrogen-upgrades确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/upgrade-2024.10.1-to-2025.1.0.mdupgrade-2024.4.7-to-2024.7.1.mdupgrade-2025.1.0-to-2025.1.1.mdupgrade-2025.1.2-to-2025.1.3.mdupgrade-2025.1.3-to-2025.1.4.mdupgrade-2025.5.0-to-2025.7.0.mdupgrade-2025.7.0-to-2026.1.0.mdupgrade-2026.1.0-to-2026.4.7.md详细介绍
Hydrogen 升级
按版本划分的 Shopify Hydrogen 升级迁移指南。每份指南都涵盖破坏性变更、所需的代码更新和分步差异。
在线文档
请在此技能自己的文件夹中运行以下命令。辅助脚本位于同级的
shopify-hydrogen 技能中，因此只要安装了整个技能包，../shopify-hydrogen/scripts/ 就会存在。
如果你单独安装了此技能，该文件夹便不存在，下面的命令会因 MODULE_NOT_FOUND 而失败。添加一次辅助脚本即可：
npx skills add Weaverse/shopify-hydrogen-skills --skill shopify-hydrogen
如果你不想安装该技能，此技能中的 references/ 文件仍可作为离线备用资料使用。
获取 Shopify 的最新升级信息：
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen upgrade <version>"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen breaking changes"
node ../shopify-hydrogen/scripts/search_shopify_docs.mjs "hydrogen migration"
下面整理的指南涵盖特定版本升级，并提供详细差异和 Weaverse 专项注意事项。
可用的升级指南
| 指南 | 关键变更 |
|---|---|
| 2024.4.7 → 2024.7.1 | 乐观变体、新的会话提交模式、Layout 组件重构、VariantSelector 改进 |
| 2024.10.1 → 2025.1.0 | v3_lazyRouteDiscovery 标志、样式表链接标签修复 |
| 2025.1.0 → 2025.1.1 | v3_singleFetch 标志、nonce 支持、json/defer 弃用、B2B 稳定化 |
| 2025.1.2 → 2025.1.3 | v3_routeConfig 标志、Layout 导出移至单独文件、routes.ts 配置 |
| 2025.1.3 → 2025.1.4 | 会话注销修复、VariantSelector 弃用、产品查询更新、ProductForm 重构 |
| 2025.5.0 → 2025.7.0 | 重大 — 迁移至 React Router 7.9.x、创建上下文、更新入口点 |
| 2025.7.0 → 2026.1.0 | 重大 — @react-router 7.12、@shopify/hydrogen 2026.1.0、Storefront API 2026-01、新购物车变更操作 |
| 2026.1.0 → 2026.4.7 | 重大 — Storefront API 2026-04、强制使用同源 Storefront API 代理、Customer Privacy API 同意迁移、React Router ~7.16 |
升级流程
1. 先使用官方升级工具
npx shopify hydrogen upgrade
此 CLI 会自动升级并安装所需依赖，然后生成一个 Markdown 文件，列出所需的源代码变更——请手动应用这些变更（或将文件交给你的 Agent），然后进行验证。该工具本身不会编辑源文件。
2. 在上方找到合适的指南
根据当前版本选择相应的指南。若要跨越多个版本，请按顺序应用每份指南。
3. 升级后重新生成类型
npm run codegen
切勿直接编辑生成的
.d.ts文件——请始终重新生成。
4. 资源
评论
支持 Markdown