Hydrogen Demo Store 模板全解析：基于 React 的 Shopify 自定义商店前端开发实战

Hydrogen Demo Store 模板全解析：基于 React 的 Shopify 自定义商店前端开发实战

【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel

Hydrogen 是 Shopify 官方推出的 React 框架与 SDK，用于构建快速、动态的 Shopify 自定义商店前端（custom storefronts）。本文以当前仓库中 packages/hydrogen/test/fixtures/demo-store-ts 目录下 TypeScript 版本的 Hydrogen Demo Store 模板为研究对象，从环境要求、脚手架初始化、本地开发、生产构建到生产构建本地预览的完整工作流展开讲解，并结合该模板真实的配置与源码，深入剖析其路由、数据查询、会话存储、Vercel 部署与端到端测试等实现细节。读完本文，你将能够独立初始化、配置、运行并理解一个完整的 Hydrogen 商店前端项目。

模板概述与仓库定位

demo-store-ts是 Hydrogen 官方提供的一个完整 Demo Store（演示商店）模板的 TypeScript 版本，存放于当前仓库的 packages/hydrogen/test/fixtures/demo-store-ts/README.md。从目录结构看，它并不仅仅是一份静态说明文档，而是一整套可运行、可测试、可部署的前端工程：

• src/：完整的 React 源码，包含组件（components/）、路由（routes/）、工具库（lib/）、样式（styles/）与全局应用入口 App.server.tsx；
• tests/：基于 Playwright 的端到端测试；
• 工程配置：hydrogen.config.ts、vite.config.ts、tailwind.config.js、postcss.config.js、vercel.json、package.json等。

该模板在仓库中被用作 Hydrogen 框架的测试夹具（fixture），其vercel.json中配置的probes探针（详见下文）也印证了它会被 CI 实际构建、部署并验证。因此，模板中的每一项配置都经过了真实工程环境的检验，具有很高的实战参考价值。

环境要求与依赖

根据模板的 package.json 与 README，运行该模板需要：

• Node.js 16.5.0 或更高版本；
• Yarn包管理器（README 明确要求；模板的test:ci脚本也直接调用了yarn build）；
• 建议同时准备一个 Shopify 商店与 Storefront API 访问令牌（下文配置章节详述）。

模板自身的依赖分为两类：

• 运行时依赖（dependencies）：@shopify/hydrogen（Hydrogen 运行时与 SDK）、react/react-dom（React 18）、@headlessui/react、@heroicons/react（UI 与图标）、graphql-tag（GraphQL 查询模板）、clsx、react-use、title、typographic-base等；
• 开发依赖（devDependencies）：@shopify/cli与@shopify/cli-hydrogen（Hydrogen 官方 CLI，提供dev/build/preview命令）、vite（开发服务器与构建）、vitest（测试）、playwright（端到端测试）、typescript、tailwindcss及其 PostCSS 插件链、prettier等。

值得一提的是，模板的dev、build、preview三个脚本都是通过shopify hydrogen ...子命令驱动的（如"dev": "shopify hydrogen dev"），而不是直接调用 Vite，说明 Hydrogen 的官方 CLI 封装了完整的开发/构建/预览体验。

初始化一个新 Hydrogen 应用

README 给出的初始化命令是：

npm init @shopify/hydrogen

执行后会生成一个全新的 Hydrogen 应用骨架。对于想要直接体验本仓库内置模板的读者，也可以直接以 packages/hydrogen/test/fixtures/demo-store-ts 为起点，复制其工程结构作为自定义开发的基础（注意该目录以~别名映射源码目录，vite.config.ts中配置了resolve.alias：[{find: /^~\/(.*)/, replacement: '/src/$1'}]，因此代码里~/components这样的导入路径指向src/components）。

启动开发服务器

初始化完成后，进入项目目录并安装依赖、启动开发服务器：

cd demo-store npm install npm run dev

其中npm run dev实际执行的是shopify hydrogen dev（见 package.json）。开发服务器由 Vite 驱动，vite.config.ts中通过import hydrogen from '@shopify/hydrogen/plugin'注册了 Hydrogen 插件，并对@headlessui/react、clsx、react-use、typographic-base等依赖做了optimizeDeps.include预构建优化。

在启动前必须完成的关键配置：README 强调，记得在hydrogen.config.ts中更新你商店的域名（storeDomain）和 Storefront API 令牌（storefrontToken）。该模板自带的配置（hydrogen.config.ts）指向 Hydrogen 官方预览商店hydrogen-preview.myshopify.com，仅供模板演示使用，实际开发请务必替换为自有商店信息。

hydrogen.config.ts 配置详解

hydrogen.config.ts 是 Hydrogen 应用的核心配置文件，模板中展示了两个最重要的配置块：

Shopify 商店配置

shopify: { defaultCountryCode: 'US', defaultLanguageCode: 'EN', storeDomain: 'hydrogen-preview.myshopify.com', storefrontToken: '3b580e70970c4528da70c98e097c2fa0', storefrontApiVersion: '2022-07', },

各字段说明：

需要特别说明的是：storefrontToken是模板公开仓库中用于演示的明文令牌。在真实项目中，应将令牌放入环境变量（如process.env.SHOPIFY_STOREFRONT_TOKEN）并在服务端读取，切勿硬编码或提交到公开仓库。

Cookie 会话存储配置

session: CookieSessionStorage('__session', { path: '/', httpOnly: true, secure: import.meta.env.PROD, // 生产环境自动启用 HTTPS-only sameSite: 'Strict', maxAge: 60 * 60 * 24 * 30, // 30 天 }),

CookieSessionStorage来自@shopify/hydrogen/config，以 Cookie 方式持久化会话状态：

• __session：Cookie 名称；
• httpOnly: true：禁止客户端脚本读取，提升安全性；
• secure: import.meta.env.PROD：生产构建（npm run build）时自动启用Secure标记，仅通过 HTTPS 传输；开发环境关闭以便本地调试；
• sameSite: 'Strict'：严格限制跨站请求携带该 Cookie，兼顾安全与 CSRF 防护；
• maxAge: 60 * 60 * 24 * 30：30 天有效期。

这套配置既保证生产环境会话安全，又照顾了本地开发体验，是值得直接复用的会话配置范式。

生产构建与本地预览

构建生产包

npm run build

该命令执行shopify hydrogen build，产出可用于部署的构建产物。生产构建同时意味着import.meta.env.PROD为true，会话 Cookie 会自动带上Secure标记。

预览生产构建

npm run build npm run preview

npm run preview执行shopify hydrogen preview，会在与 Oxygen 运行环境相似的本地环境中启动一个生产构建预览服务。README 特别强调"an environment similar to Oxygen"——Oxygen 是 Shopify 的 Hydrogen 托管平台，因此preview能最大程度还原线上运行环境，用于上线前的最终验证。注意preview依赖已存在的构建产物，因此必须先build再preview。

模板工程结构剖析：一个完整的商店前端

除 README 描述的工作流外，该模板本身就是一份极佳的学习素材。理解它的目录结构，就能理解一个完整 Hydrogen 应用应有的形态：

src/ ├── App.server.tsx # 应用根组件（服务端渲染入口） ├── components/ # 组件库 │ ├── account/ # 账户体系（登录、注册、地址簿、订单历史等） │ ├── cards/ # 商品卡、文章卡、收藏集卡 │ ├── cart/ # 购物车抽屉与购物车行项 │ ├── elements/ # 基础 UI 元素（Button、Input、Icon 等） │ ├── global/ # 全局布局（Header、Footer、CartDrawer、NotFound 等） │ ├── product/ # 商品详情、商品表单、商品图库、商品选项 │ ├── search/ # 搜索结果与无结果推荐 │ └── sections/ # 首页区块（Hero、FeaturedCollections 等） ├── lib/ # 工具库（常量、GraphQL fragment、占位数据、工具函数） ├── routes/ # 文件系统路由 │ ├── index.server.tsx # 首页 │ ├── cart.server.tsx # 购物车页 │ ├── search.server.tsx # 搜索页 │ ├── products/[handle].server.tsx # 商品详情页 │ ├── collections/[handle].server.tsx # 收藏集页 │ ├── journal/[handle].server.tsx # 博客文章页 │ ├── policies/[handle].server.tsx # 政策页 │ ├── pages/[handle].server.tsx # 自定义页面 │ ├── account/… # 账户相关路由 │ └── api/… # 服务端 API 路由（bestSellers、countries） └── styles/ # 全局样式（Tailwind CSS）

几点值得深入的设计细节：

文件系统路由与服务端组件

src/routes/下的.server.tsx/.server.ts文件即文件系统路由：products/[handle].server.tsx对应/products/:handle，collections/[handle].server.tsx对应/collections/:handle，index.server.tsx对应/。App.server.tsx中通过FileRoutes自动注册这些路由，并配置了basePath支持国家码前缀（如/us/），同时以Route path="*"兜底渲染NotFound组件：

<Router> <FileRoutes basePath={countryCode ? `/${countryCode}/` : undefined} /> <Route path="*" page={<NotFound />} /> </Router>

App.server.tsx还展示了 Hydrogen 的经典服务端能力组合：ShopifyProvider（提供商店上下文）、CartProvider（购物车状态）、DefaultSeo（默认 SEO 元信息）、PerformanceMetrics（性能指标上报）与ShopifyAnalytics（Shopify 分析）。Suspense被用于服务端流式渲染的分段加载。

首页数据流：useShopQuery + GraphQL

src/routes/index.server.tsx 展示了 Hydrogen 最核心的数据获取模式——useShopQuery：

• 通过useLocalization()获取当前语言与国家 ISO 码，作为查询变量；
• useShopQuery在服务端执行 GraphQL 查询，variables中传入language、country，并通过@inContext(country: $country, language: $language)指令让 Storefront API 按上下文返回本地化数据；
• preload: true允许该查询在客户端路由跳转时被预加载；
• SEO 查询使用CacheLong()做长缓存，首页商品/收藏集查询则按需缓存。

模板还演示了 GraphQL fragment 复用（MEDIA_FRAGMENT、PRODUCT_CARD_FRAGMENT定义于 src/lib/fragments.ts）以及 metafield 读取（heronamespace 的title、byline、cta、spread等字段驱动 Hero 区块），并使用getHeroPlaceholder（src/lib/placeholders.ts）在 Hero 数据缺失时回退到占位图，保证页面始终可用。

购物车与 API 路由

src/routes/cart.server.tsx 是一个简洁的路由示例：页面由Layout+PageHeader+CartDetails（客户端组件）构成，购物车数据由CartProvider与 Cart API 管理。src/routes/api/下还提供了bestSellers.server.ts（畅销榜）与countries.server.ts（国家列表）两个服务端 API 路由示例，可作为自定义 API 端点的参考。

部署到 Vercel：vercel.json 探针配置

该模板虽由 Shopify 官方维护，但当前仓库中同时给出了 Vercel 部署配置 vercel.json：

{ "version": 2, "builds": [ { "src": "package.json", "use": "@vercel/hydrogen", "config": { "zeroConfig": true } } ], "probes": [ {"path": "/", "mustContain": "All Mountain All Season"}, {"path": "/404", "mustContain": "We’ve lost this page"} ] }

• builds指定使用@vercel/hydrogen这一 Vercel 构建适配器，以package.json为构建入口，zeroConfig: true表示零配置即可完成部署（Hydrogen 相关依赖与脚本会由适配器自动识别）；
• probes是 Vercel 的部署健康探针：部署完成后会请求/，校验响应正文包含"All Mountain All Season"（首页 Hero 文案），并请求/404校验包含"We’ve lost this page"（NotFound 页面文案）。这两条探针直接验证了首页渲染与 404 兜底路由都工作正常，也说明该模板在仓库 CI 中真实经过部署验证。

端到端测试：Playwright + Vite

模板自带端到端测试，可验证整套工程可运行。测试入口在 tests/e2e/index.test.ts，测试工具封装在 tests/utils.ts：

• 使用 Playwright 的chromium.launch()启动无头浏览器；
• 测试环境有两种模式：WATCH=true时（npm test）启动 Vite 开发服务器；否则（test:ci先yarn build -t node再vitest run）直接加载dist/node的生产构建产物，更贴近线上环境；
• 测试用例对首页发起请求并断言 HTTP 状态码为 200（超时上限 60 秒）。

配合package.json中的test:ci（先构建 Node 目标产物再跑测试），可以看到模板覆盖了「构建 → 运行 → 断言」的完整验证链路。

常见问题与注意事项

1. 令牌未替换：直接使用模板自带的hydrogen-preview.myshopify.com与演示令牌虽然可以跑通页面，但生产项目必须替换为自有商店域名与 Storefront API 令牌，并将令牌放入环境变量管理。
2. npm run preview前必须npm run build：preview 依赖构建产物，跳过 build 会因产物缺失而失败。
3. Node 版本：要求 Node.js 16.5.0+，低于该版本可能出现依赖安装或构建失败。
4. 生产环境 HTTPS：会话 Cookie 的secure字段在生产构建下自动开启，本地预览（非 PROD）时不会强制 HTTPS，属预期行为。

总结

从 packages/hydrogen/test/fixtures/demo-store-ts/README.md 出发，本文完整走通了 Hydrogen 商店前端的「初始化 → 开发 → 构建 → 预览」工作流，并结合模板源码深入讲解了hydrogen.config.ts的商店与会话配置、文件系统路由、useShopQuery数据获取、Vercel 部署探针与 Playwright 端到端测试等实现细节。该模板是一个结构完整、配置真实、可构建可测试可部署的实战范例——无论是第一次接触 Hydrogen 的开发者，还是需要在 Vercel 上部署 Hydrogen 应用的团队，都可以直接以它为起点进行二次开发。

【免费下载链接】vercelDevelop. Preview. Ship.项目地址: https://gitcode.com/gh_mirrors/ve/vercel