Hydrogen 升到 React Router 7 报错怎么迁

现象#

升级到 2026-10 后 npm run dev 直接报 Cannot find module '@remix-run/react'；改完 import 又提示 hydrogen 不是合法 Vite 插件，shopify hydrogen dev 也不存在了。

原因#

• 2026-10 起 Hydrogen 是普通库，hydrogen dev/build 命令与插件都被移除
• Remix 与 React Router 7 包名不同，@remix-run 系列要整体换成 react-router
• 旧代码从 load context 取 storefront，新版改为 context.get 后调 graphql()
• 所有 React Router 包必须同版本，混用 7.9 与 7.15 会报 context 类型不匹配

处理步骤#

1. 看 package.json：存在 @remix-run/* 说明框架迁移与 Hydrogen 迁移都要做
2. 卸载旧包，安装 react-router 与 @react-router/dev，版本保持完全一致
3. scripts 改为 vite dev 与 react-router build，删掉 shopify hydrogen dev
4. Vite 配置换成 reactRouter() 加 ...oxygen()，删除 hydrogen() 插件
5. 根中间件调 handleShopifyRoutes()，让它接管 /checkout 与 /api/cart

验收标准#

npm run build 产出 dist/client 与 dist/server，npm run dev 下首页、商品页、购物车都正常。