Hydrogen v2 无头电商模板实战指南基于 Remix 的 Shopify 店铺从零部署到 Vercel【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples导读本文围绕仓库 framework-boilerplates/hydrogen-2 目录下的 Hydrogen v2 模板展开系统讲解如何把一个基于 Remix 的 Shopify 无头电商店铺零配置部署到 Vercel并覆盖本地开发、环境变量配置、核心目录结构与请求处理链路。读完本文你将掌握 Hydrogen v2 模板的完整工程骨架Remix 路由、Oxygen Worker、Storefront GraphQL 客户端、购物车处理器能够独立完成本地调试、环境变量迁移与生产部署。一、Hydrogen v2 是什么Hydrogen 是 Shopify 为无头电商headless commerce提供的技术栈专门用于构建基于 Shopify Storefront API 的自定义店铺前端。Hydrogen v2 的核心变化在于它与 Remix 深度整合——Remix 是 Shopify 的全栈 Web 框架负责路由、数据加载与服务端渲染Hydrogen 则提供 Storefront 数据访问、购物车、会话等电商领域能力两者组合形成一套完整的无头电商开发范式。本仓库中的hydrogen-2模板正是这一组合的最小可用工程它只包含最精简的组件、GraphQL 查询与工程化工具链足以让你快速启动并在此基础上扩展自己的店铺。模板同时提供 TypeScript 与 JavaScript 两种写法当前仓库以 TypeScript 为主。技术栈速览依据 package.jsonRemixremix-run/react、remix-run/dev版本 1.19.1Hydrogenshopify/hydrogen^2023.7.2Oxygen 运行时shopify/remix-oxygen^1.1.3Shopify CLIshopify/cli3.48.0 shopify/cli-hydrogen^5.1.2ESLint、Prettiershopify/prettier-config、GraphQL 代码生成器、Tailwind CSS运行时要求 Node.js 22.x二、模板包含的完整能力清单根据 README 的 Whats included 一节并结合目录结构逐项核对本模板内置的能力如下能力仓库中的落点Remix 全栈框架app/routes 下 30 余个路由文件Hydrogen 无头电商层server.ts 中的 Storefront 客户端与购物车处理器OxygenShopify 边缘运行时remix.config.js 的 Worker 构建配置Shopify CLI 工具链package.json 的 build / dev / preview / codegen 脚本ESLint Prettierpackage.json 及eslint-plugin-hydrogenGraphQL 代码生成器storefrontapi.generated.d.ts类型声明 codegen脚本TypeScript / JavaScript 双风味仓库以 TS 为主模板本身支持两种写法最小化组件与路由集合app/components 与 app/routes路由层几乎覆盖了一个店铺的前台所需场景首页_index.tsx、商品页products.$handle.tsx、商品集合collections._index.tsx与collections.$handle.tsx、博客blogs._index.tsx等、搜索与预测搜索api.predictive-search.tsx、政策页policies._index.tsx、购物车页cart.tsx以及一整套账户体系登录、注册、找回密码、激活、地址簿、订单详情等见account*.tsx系列文件另有 SEO 相关的[robots.txt].tsx与[sitemap.xml].tsx。此外还包含一个 404 兜底路由$.tsx。三、部署到 Vercel两种方式README 明确说明该目录是一个可以零配置部署到 Vercel的 Hydrogen v2 店铺示例。3.1 一键部署Git 导入最简单的方式是使用 Vercel 的 Deploy 按钮将本模板仓库导入 Vercel 并选择hydrogen-2模板后Vercel 会自动识别框架并完成构建与发布。模板预设了vercel.json见下文环境变量一节因此首次部署无需任何额外配置即可跑通。3.2 使用 Vercel CLI 部署也可以在本目录下使用 Vercel CLInpm i -g vercel vercel第一条命令全局安装 Vercel CLI第二条命令在该目录中启动交互式部署流程首次会要求登录并关联项目。由于仓库内已存在vercel.jsonCLI 会读取其中的构建与环境配置。3.3 部署前的环境变量迁移重要部署成功后模板自带的vercel.json中定义了最小环境变量集合详见下文。但 README 特别强调这些只是默认占位值正式上线前必须将它们迁移到 Vercel 控制台的 Project Environment Variables 配置中或使用vc env系列命令管理并根据自己的 Shopify 店铺信息更新取值、把SESSION_SECRET换成自定义密钥。迁移完成后应删除项目根目录下的vercel.json文件防止其中的环境变量在部署时覆盖控制台配置、产生优先级冲突。四、环境变量连接 Shopify 的钥匙4.1 模板中的最小环境变量本模板的vercel.json内容如下{ env: { SESSION_SECRET: foobar, PUBLIC_STORE_DOMAIN: mock.shop } }对应的本地开发环境变量见 .env.example# The variables added in this file are only available locally in MiniOxygen SESSION_SECRETfoobar PUBLIC_STORE_DOMAINmock.shop两个变量的含义变量说明SESSION_SECRET用于签名会话 Cookie 的密钥生产环境必须替换为自定义值PUBLIC_STORE_DOMAIN店铺域名默认指向 Shopify 官方的演示店铺mock.shop无需真实店铺即可体验模板4.2 完整连接所需的变量集虽然模板只需上述两个变量即可跑通因为默认连的是mock.shop但接入自己的Shopify 店铺时还需要补齐 server.ts 中createStorefrontClient消费的全部变量PUBLIC_STORE_DOMAIN店铺主域名PUBLIC_STOREFRONT_API_TOKEN公开 Storefront API Token用于商品、集合等公开数据PRIVATE_STOREFRONT_API_TOKEN私有 Storefront API Token用于购物车、客户等敏感操作PUBLIC_STOREFRONT_IDStorefront ID。从 server.ts 的源码可以看到服务启动时会强制校验SESSION_SECRETif (!env?.SESSION_SECRET) { throw new Error(SESSION_SECRET environment variable is not set); }如果未设置该变量Worker 会直接抛出错误这从实现层面印证了SESSION_SECRET的必要性。4.3 本地开发的环境变量本地开发时将.env.example重命名为.envShopify dev serverMiniOxygen便会自动加载其中变量。如果你依据上面的说明新增或修改了环境变量请同步更新到.env中保持本地与生产一致。五、本地开发两行命令启动在hydrogen-2目录下依次执行npm install npm run devnpm install按 package.json 安装全部依赖npm run dev实际执行的是shopify hydrogen dev --codegen-unstable会启动本地开发服务器并开启实验性的 GraphQL 代码生成。启动后即可在本地预览基于mock.shop数据的完整店铺。其他常用脚本见 package.json脚本实际命令用途npm run buildshopify hydrogen build生产构建npm run previewnpm run build shopify hydrogen preview构建后本地预览生产产物npm run linteslint --no-error-on-unmatched-pattern --ext .js,.ts,.jsx,.tsx .代码规范检查npm run typechecktsc --noEmitTypeScript 类型检查npm run codegenshopify hydrogen codegen-unstable手动触发 GraphQL 代码生成六、源码级原理请求是如何被处理的理解模板的请求处理链路是进一步定制店铺的基础。核心逻辑集中在两处入口文件与 Remix 配置。6.1 Worker 入口server.tsserver.ts 是应用的虚拟入口virtual entry point它导出一个标准的fetchhandler运行在 Oxygen/Cloudflare Workers 环境中处理流程如下初始化缓存与会话caches.open(hydrogen)打开 Worker 缓存实例同时通过自定义的HydrogenSession.init()创建基于 Cookie 的会话存储server.ts。会话 Cookie 名为session设置了httpOnly: true、sameSite: lax并使用SESSION_SECRET作为签名密钥。创建 Storefront 客户端createStorefrontClient()注入cache、waitUntil来自executionContext.waitUntil、i18n默认语言EN、国家US、各类 Token、storeDomain与来自请求头的storefrontHeadersserver.ts。创建购物车处理器createCartHandler()绑定 Storefront 客户端配合cartGetIdDefault/cartSetIdDefault从请求头读取、在会话中写回购物车 ID并以CART_QUERY_FRAGMENT作为购物车数据查询片段server.ts。该片段查询了金额、行项目、费用、税费、折扣码等完整购物车结构。创建 Remix 请求处理器createRequestHandler()将session、storefront、env、cart全部注入 loader 上下文供各路由的 loader 使用server.ts。404 兜底重定向当应用返回 404 时调用storefrontRedirect()查询 Shopify 侧的 URL 重定向规则若不存在对应规则则原样透传 404server.ts。错误兜底任何未捕获异常都会记录日志并返回 500server.ts。其中的HydrogenSession类封装了get/set/flash/unset/has/commit/destroy等会话操作方法server.ts注释明确说明可以按需定制或替换为其他会话实现。6.2 Oxygen 构建配置remix.config.jsremix.config.js 中有一段注释The following settings are required to deploy Hydrogen apps to Oxygen。这些配置决定了构建产物面向 Worker 运行时server: ./server.ts指定 Worker 入口文件publicPath: (process.env.HYDROGEN_ASSET_BASE_URL ?? /) build/静态资源路径assetsBuildDirectory: dist/client/build、serverBuildPath: dist/worker/index.js客户端与服务端产物目录serverPlatform: neutral、serverModuleFormat: esm、serverConditions: [worker, ...]、serverDependenciesToBundle: all面向边缘运行时打包tailwind: true、postcss: true开启内置的 Tailwind/PostCSS 管线future块启用 Remix v2 的 meta、headers、errorBoundary、路由约定与表单方法等新特性。6.3 服务端与客户端渲染入口entry.server.tsx 使用renderToReadableStream进行流式 SSR并借助isbot判断爬虫请求——只有爬虫请求才等待整个流就绪body.allReady普通用户则获得更快的首字节entry.client.tsx 通过hydrateRoot在客户端完成水合并用startTransition包裹以避免阻塞首次交互。6.4 根布局与数据加载root.tsxapp/root.tsx 演示了 Hydrogen 的核心数据加载模式loader 中对首屏关键数据header 查询使用await阻塞对折叠线以下的数据购物车、footer 查询使用defer延迟返回从而兼顾首屏速度与整体数据完整性root.tsx通过storefront.query(..., {cache: storefront.CacheLong()})为菜单查询设置长缓存内置ErrorBoundary对isRouteErrorResponse与普通 Error 分别提取状态码与错误信息进行展示root.tsx内置validateCustomerAccessToken()辅助函数根据 Token 过期时间自动清理会话中的失效 Token 并下发Set-Cookieroot.tsx。6.5 商品页defer 与变体选择的最佳实践以 app/routes/products.$handle.tsx 为例可以看到模板对性能与 UX 的细致处理关键商品数据PRODUCT_QUERY被await阻塞等待而全量变体列表VARIANTS_QUERY最多 250 条被defer延迟加载UI 用SuspenseAwait包裹先渲染空变体列表再异步更新products.$handle.tsx使用getSelectedProductOptions(request)解析 URL 中的变体选项并过滤掉 Shopify 预测搜索注入的_sid、_pos、_psq、_ss、_v等内部参数products.$handle.tsx当商品没有默认变体且 URL 未携带有效选项时自动 302 重定向到首个变体的规范 URLredirectToFirstVariant加入购物车通过 Hydrogen 的CartForm route/cart action{CartForm.ACTIONS.LinesAdd}实现products.$handle.tsx按钮在售罄或提交期间自动禁用。七、从模板到正式店铺的落地清单将本模板用于真实项目时建议按以下顺序操作本地开发npm install→ 复制.env.example为.env→npm run dev接入真实店铺在 Shopify 后台创建 Storefront API Token补齐PUBLIC_STOREFRONT_API_TOKEN、PRIVATE_STOREFRONT_API_TOKEN、PUBLIC_STOREFRONT_ID与真实PUBLIC_STORE_DOMAIN更换密钥把SESSION_SECRET改为随机生成的高强度值迁移环境变量将变量配置到 Vercel 项目控制台或vc env然后删除根目录的vercel.json避免占位值覆盖生产配置适配菜单修改 root.tsx 中的headerMenuHandle默认main-menu与footerMenuHandle默认footer为你的 Shopify 菜单 handle部署上线通过 Vercel 一键导入或vercelCLI 发布如需完整文档可进一步阅读 Hydrogen 官方文档与 Remix 框架文档。八、常见问题与排查思路启动报SESSION_SECRET environment variable is not set检查.env本地或 Vercel 环境变量线上是否配置了SESSION_SECRET依据见 server.ts。页面数据为空确认PUBLIC_STORE_DOMAIN与两个 Storefront Token 是否正确未接入真实店铺时请保留mock.shop。购物车无法持久化购物车 ID 依赖会话 Cookie确认 Cookie 未被浏览器禁用且SESSION_SECRET在部署环境中保持一致。404 页未生效模板通过storefrontRedirect处理重定向若请求 Shopify 重定向规则失败会透传 404相关逻辑见 server.ts。以上各节的配置与行为均可在本仓库 framework-boilerplates/hydrogen-2 目录下直接验证其中 vercel.json、.env.example、server.ts、remix.config.js 是理解与定制该模板的四个关键文件。【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考