Hydrogen v2 无头电商模板实战指南：基于 Remix 的 Shopify 店铺从零部署到 Vercel-育师

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.json）：
Remix（@remix-run/react、@remix-run/dev，版本 1.19.1）
Hydrogen（@shopify/hydrogen^2023.7.2）
Oxygen 运行时（@shopify/remix-oxygen^1.1.3）
Shopify CLI（@shopify/cli3.48.0 +@shopify/cli-hydrogen^5.1.2）
ESLint、Prettier（@shopify/prettier-config）、GraphQL 代码生成器、Tailwind CSS
运行时要求 Node.js 22.x

二、模板包含的完整能力清单

根据 README 的 "What's included" 一节，并结合目录结构逐项核对，本模板内置的能力如下：

能力	仓库中的落点
Remix 全栈框架	app/routes 下 30 余个路由文件
Hydrogen 无头电商层	server.ts 中的 Storefront 客户端与购物车处理器
Oxygen（Shopify 边缘运行时）	remix.config.js 的 Worker 构建配置
Shopify CLI 工具链	package.json 的 build / dev / preview / codegen 脚本
ESLint + Prettier	package.json 及`eslint-plugin-hydrogen`
GraphQL 代码生成器	`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 CLI：

npm i -g vercel vercel

第一条命令全局安装 Vercel CLI，第二条命令在该目录中启动交互式部署流程（首次会要求登录并关联项目）。由于仓库内已存在vercel.json，CLI 会读取其中的构建与环境配置。

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_SECRET="foobar" PUBLIC_STORE_DOMAIN="mock.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_ID：Storefront ID。

从 server.ts 的源码可以看到，服务启动时会强制校验SESSION_SECRET：

if (!env?.SESSION_SECRET) { throw new Error('SESSION_SECRET environment variable is not set'); }

如果未设置该变量，Worker 会直接抛出错误，这从实现层面印证了SESSION_SECRET的必要性。

4.3 本地开发的环境变量

本地开发时，将.env.example重命名为.env，Shopify dev server（MiniOxygen）便会自动加载其中变量。如果你依据上面的说明新增或修改了环境变量，请同步更新到.env中，保持本地与生产一致。

五、本地开发：两行命令启动

在hydrogen-2目录下依次执行：

npm install npm run dev

npm install按 package.json 安装全部依赖；npm run dev实际执行的是shopify hydrogen dev --codegen-unstable，会启动本地开发服务器并开启实验性的 GraphQL 代码生成。启动后即可在本地预览基于mock.shop数据的完整店铺。

其他常用脚本（见 package.json）：

脚本	实际命令	用途
`npm run build`	`shopify hydrogen build`	生产构建
`npm run preview`	`npm run build && shopify hydrogen preview`	构建后本地预览生产产物
`npm run lint`	`eslint --no-error-on-unmatched-pattern --ext .js,.ts,.jsx,.tsx .`	代码规范检查
`npm run typecheck`	`tsc --noEmit`	TypeScript 类型检查
`npm run codegen`	`shopify hydrogen codegen-unstable`	手动触发 GraphQL 代码生成

六、源码级原理：请求是如何被处理的

理解模板的请求处理链路，是进一步定制店铺的基础。核心逻辑集中在两处：入口文件与 Remix 配置。

6.1 Worker 入口：server.ts

server.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与来自请求头的storefrontHeaders（server.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 重定向规则；若不存在对应规则则原样透传 404（server.ts）。
错误兜底：任何未捕获异常都会记录日志并返回 500（server.ts）。

其中的HydrogenSession类封装了get/set/flash/unset/has/commit/destroy等会话操作方法（server.ts），注释明确说明可以按需定制或替换为其他会话实现。

6.2 Oxygen 构建配置：remix.config.js

remix.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.tsx

app/root.tsx 演示了 Hydrogen 的核心数据加载模式：

loader 中对首屏关键数据（header 查询）使用await阻塞，对折叠线以下的数据（购物车、footer 查询）使用defer延迟返回，从而兼顾首屏速度与整体数据完整性（root.tsx）；
通过storefront.query(..., {cache: storefront.CacheLong()})为菜单查询设置长缓存；
内置ErrorBoundary，对isRouteErrorResponse与普通 Error 分别提取状态码与错误信息进行展示（root.tsx）；
内置validateCustomerAccessToken()辅助函数，根据 Token 过期时间自动清理会话中的失效 Token 并下发Set-Cookie（root.tsx）。

6.5 商品页：defer 与变体选择的最佳实践

以 app/routes/products.$handle.tsx 为例，可以看到模板对性能与 UX 的细致处理：

关键商品数据（PRODUCT_QUERY）被await阻塞等待，而全量变体列表（VARIANTS_QUERY，最多 250 条）被defer延迟加载，UI 用Suspense+Await包裹，先渲染空变体列表再异步更新（products.$handle.tsx）；
使用getSelectedProductOptions(request)解析 URL 中的变体选项，并过滤掉 Shopify 预测搜索注入的_sid、_pos、_psq、_ss、_v等内部参数（products.$handle.tsx）；
当商品没有默认变体且 URL 未携带有效选项时，自动 302 重定向到首个变体的规范 URL（redirectToFirstVariant）；
加入购物车通过 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。