Headless：Storefront API、Hydrogen 与主题店面的取舍

Headless 指店面前端与 Shopify 后端分开：商家自己构建前端，商品、购物车、客户与结账仍由 Shopify 提供。官方称之为自定义店面（custom storefront），前端可以是网站、移动应用或其他终端。它解决的是「现有销售渠道、主题或应用满足不了某种体验」；它不解决主题难改的问题，也不是主题的升级版。官方同页提醒，自定义店面带来额外成本与复杂度，需要开发资源长期维护。Custom storefronts。

本库哪些内容依赖它

本库的店面正文默认以主题（Online Store）为实现载体，下列文章在 Headless 下需要重新核对。本文是 Headless 的权威来源，其他文章只写各自页面语境下的用法：

• 店面关系网与主题结构与渲染关系：Layout、Template、Section、Block 都是主题概念；
• Dawn 15.3.0 架构：固定版本的主题源码，不能用来推断 Headless 前端怎么写；
• 销售渠道：Headless 是其中一种渠道；
• URL 重定向、店面 SEO 框架：前者写 Online Store 的重定向管理，后者写主题输出；
• 隐私与同意、Web Pixels：自建前端里的同意与事件接入；
• 支付与结账、客户账户、原生配置、应用与开发。

核心对象与概念

构建选项页并列三条路线：Hydrogen、Hydrogen React、Headless 渠道加自选技术栈（只用 Storefront API）；写明 Hydrogen 与 Headless 渠道都提供订单归因、商品发布、按渠道的分析与销售报告、令牌管理。本文不推荐具体框架，依据应是团队现有技术栈与维护能力。构建选项。

在哪里配置

• 创建店面：Shopify admin 的 Sales channels > Headless，点 Add storefront，自动带公开与私有令牌；需要员工具备 Apps and channels 权限。入门。
• 权限：Headless 渠道内 Storefront API permissions 旁点 Edit；官方写明 Storefront 与 Admin API 权限在所有店面间共享。
• 轮换私有令牌：先生成新令牌，再删除旧令牌；删除不可撤销，须先更新所有使用它的应用与脚本。渠道管理。
• 订单归因：订单在 Channel 列显示店面名称，归因发生在渠道层级。
• 结账域名：Settings > Domains 中连接结账子域名，见下文。

与主题、Liquid 和 API 的连接

主题是 Online Store 的实现方式：官方把主题定义为控制在线商店组织、功能与样式的 Liquid 文件目录，分区、区块、JSON 模板与主题编辑器属于这一体系。主题架构。theme app extensions 页写明应用块与 Online Store 2.0 主题集成，未讨论 Headless。Theme app extensions。

官方页没有逐项写「Headless 中不存在 Liquid、主题编辑器或应用块」。下表只记录读到的事实，不把「未读到」说成「官方声明不存在」：

对应能力要自己实现或另选方案：商品与集合走 Storefront API，搜索与推荐见搜索与发现，自定义数据走 Metafield 与 Metaobject（自定义数据）。Hydrogen 入门页列出脚手架路由：首页、/pages/:handle、/cart/* 与 /discount/*、/products/:handle、集合、政策、博客、账户、搜索、robots、sitemap；默认连接 mock.shop 示例数据，绑定真实店铺后才显示店铺数据。Hydrogen 入门。

限制、数值与易错点

核验于 2026-09-29。

Storefront API（参考）：

• 无令牌访问的查询复杂度上限 1,000；每店铺最多 100 个活动店面与令牌。
• 公开令牌用于浏览器与移动端（请求头 X-Shopify-Storefront-Access-Token）；私有令牌用于服务端（Shopify-Storefront-Private-Token），不得用在客户端，并应传 Shopify-Storefront-Buyer-IP。
• 官方写明真实买家流量没有固定的每分钟请求上限，自动化流量受限，结账创建有节流。

购物车与结账（概览、管理）：

• 概览页写有单个购物车最多 500 个行项目、未使用的购物车 30 天内过期；这两项只读自该页，未交叉核对。
• 购物车 ID 含 key 秘密部分，官方要求视同密码，不得暴露。
• checkoutUrl 应在买家准备结账时再请求，过期后可重新请求；设置了客户访问令牌时为已登录结账。
• 管理页未写折扣码处理；折扣规则见折扣。

Oxygen（基础、环境）：

• 基础页：Oxygen 在付费套餐 Starter、Basic、Grow、Advanced、Plus、Pause and build 上不额外收费，不可用于 Agentic 套餐；开发店与试用套餐没有公开环境，部署地址始终要求登录店铺。
• 运行限制：工作包不超过 10 MB，启动不超过 400 毫秒，每请求 CPU 时间 30 秒，内存 128 MB，自定义环境变量 110 个，出站请求 2 分钟内完成。
• 环境页：多数套餐 1 个公开环境，Shopify Plus 25 个。

重定向、SEO 与域名：

• 自带技术栈时，必须自行提供标准 /products/:handle 地址，或用服务端 3XX 重定向到自定义商品路径，并自行实现购物车永久链接；该页没有覆盖结账、SEO、分析与同意。自带技术栈。
• Hydrogen 的 storefrontRedirect 在路由 404 后查询 Storefront API，执行 Shopify 后台 URL 重定向；默认不按查询参数匹配，并把 /admin 跳到 Shopify Admin。storefrontRedirect。
• Hydrogen SEO：getSeoMeta 输出标题、描述、图片、规范链接与 JSON-LD；基础模板含 sitemap 与 robots，默认缓存 24 小时；在 Oxygen 上 robots.txt 只在带自定义域名的生产环境提供，非生产共享链接以全部禁止抓取覆盖；规范链接默认去掉查询参数。SEO。
• 从 Online Store 迁移：自定义路由须设置重定向；商品须同时发布到 Online Store 与 Hydrogen 店面，购物车才能共享；Online Store 的密码保护须关闭，否则阻断 Hydrogen 结账。迁移。
• 结账域名：官方建议主域名接收店面流量，另用子域名接收 Shopify web checkout，该子域名连接为主域名并指向 Online Store；上线后 *.myshopify.com 仍可访问旧 Online Store，需要时可发布官方「Hydrogen redirect theme」做客户端重定向。流量重定向。
• 同意：官方推荐 Customer Privacy API 加内置 Cookie 横幅（Settings > Customer Privacy > Cookie banner），也支持第三方同意管理服务；横幅不会显示在默认 Oxygen 地址 *.myshopify.dev；页面写明商家自行负责合规。consent。地区差异需要合规确认，见隐私与同意。

验证一次

以下步骤用于自己的 Headless 店面，本文未执行：

1. 未登录浏览器走「商品页、加购、跳转结账」，记录结账域名是否为预期的结账子域名。
2. 用旧站商品、集合、文章地址逐个请求，记录状态码与最终地址，对照后台 URL 重定向。
3. 各用公开与私有令牌查同一商品，确认私有令牌没有出现在浏览器请求里。
4. 商品同时发布到 Online Store 与 Headless 店面后，在一个渠道加购，到另一个渠道核对购物车是否共享。
5. 分别在拒绝与接受同意状态下观察事件是否发出，思路参照Web Pixels。
6. 检查生产域名与预览地址上 robots.txt 与 sitemap 的实际输出。

待继续完善

• 主题编辑器、应用块与常见应用在 Headless 下的支持范围，需逐个官方页面核对；
• Checkout 自定义在 Headless 下的适用范围，本文未读，见支付与结账；
• 购物车 500 行与 30 天过期的第二来源，以及 Hydrogen 入门页 Node 版本要求是否为现行值；
• 搜索与筛选在 Headless 下的官方实现路径；
• 本库内容类型、展现与模块中，哪些可脱离主题复用、哪些依赖主题实现，尚未逐篇标注。