Shopify CLI 与 Headless
无头架构把主题和店面拆开了，CLI 的登录态、Storefront API 令牌、theme push 的覆盖规则、app dev 隧道，每一处都可能让本地跑通、线上报错。本分类按「先确认环境、再确认令牌、最后确认发布通道」的顺序整理这些问题的定位方法。
-
01
Shopify app dev 隧道连接失败怎么排查
在 Oxygen 或 Hydrogen 相关开发中，应用开发隧道不稳定，预览网址无法访问，或回调失败。
-
02
Shopify CLI 登录陷入循环怎么解决
使用命令行工具登录店铺时陷入登录循环，浏览器跳回登录页或提示会话无效。
-
03
Shopify CLI 怎么在多个店铺之间切换
同时维护测试店与正式店，命令老是对着错的店铺执行，差点把测试主题推到线上。
-
04
Shopify CLI 报 Node 版本不兼容怎么处理
执行 shopify theme dev 或 shopify app dev 时报引擎版本不符，命令直接退出。
-
05
Shopify CLI 安装报 EACCES 权限错误怎么解决
执行 npm i -g @shopify/cli 到最后几行出现 npm ERR! code EACCES……
-
06
Shopify CLI 走公司代理一直连接超时怎么配
shopify theme dev 卡在 Connecting to Shopify 超过一分钟……
-
07
shopify theme pull 覆盖了本地改动怎么避免
执行 theme pull 后本地改了一半的文件被线上版本覆盖，代码丢失。
-
08
Shopify CLI 升级后命令报错怎么回退
升级 CLI 后 shopify theme dev 报未知参数，或 app 命令行为变化。
-
09
Shopify CLI 在 WSL 里路径报错怎么修
Git Bash 里跑 shopify theme dev 提示找不到主题目录，直接退到上一级……
-
10
Headless 站下架商品返回 200 不是 404 怎么修
商品删除后访问旧链接，页面显示自定义的“找不到”文案，HTTP 状态码却是 200……
-
11
Hydrogen 站点怎么接 Shopify 像素与 GA4
迁移到 Hydrogen 后，后台的分析报表几乎没数据，广告归因也断了。
-
12
Hydrogen 页面缓存怎么配才不会看到旧数据
改了商品价格，Hydrogen 站点几分钟内还是旧价格；或者设了 no-store 后 TTFB 明显变高。
-
13
Headless 站商品页 canonical 全指向首页怎么修
Search Console 显示大量商品页的 canonical 指向站点首页……
-
14
Hydrogen 购物车刷新后丢失怎么修
加购后刷新页面，购物车图标归零，重新加购又生成新的 cart ID。
-
15
cartId 存 localStorage 导致购物车串号
同一浏览器先以游客加购，再登录另一个账号，购物车仍是前一个游客的商品；换设备打开却是空车……
-
16
Headless 站点结账跳不回 Shopify 域名怎么办
点结账后跳到 https://shop.com/checkout 并返回 404……
-
17
Hydrogen 能不能部署到 Vercel 或 Cloudflare
团队已有 Vercel 工作流，不想用 Oxygen，不确定 Hydrogen 是否支持。
-
18
Headless 站上线后 Google 抓取不到内容怎么办
页面在浏览器正常，但 GSC 抓取显示空白或只有骨架，收录几乎为零。
-
19
Hydrogen loader 里多个请求怎么并行不串行
商品页要取商品、推荐、评论三份数据，写法是三个 await，首屏慢了一倍。
-
20
Hydrogen 站点的 SEO 要自己做什么
Headless 上线后 Search Console 收录很少，页面没有 description……
-
21
升级后 Analytics.Provider 报错怎么替换
升到 2026-10 后页面白屏，控制台报 Attempted import error: 'Analytics' ……
-
22
CacheShort 与 CacheLong 到底该选哪个
后台改价后 Hydrogen 商品页仍显示旧价……
-
23
Hydrogen 的 CartForm 提交后购物车没变怎么排查
点击 CartForm 的加购按钮后页面整页刷新，cart.totalQuantity 仍是 0……
-
24
Hydrogen 部署后环境变量读不到怎么办
本地 .env 正常，部署到 Oxygen 后请求 Storefront API 报 token 为空……
-
25
Hydrogen 里图片怎么用 Shopify CDN 自动优化
Headless 站点图片直接用了原图 URL，首屏很慢，也没有响应式尺寸。
-
26
Hydrogen loader 返回类型推导不出来怎么修
组件里 useLoaderData() 拿到的 product 是 any 或 never……
-
27
Hydrogen 升到 React Router 7 报错怎么迁
升级到 2026-10 后 npm run dev 直接报 Cannot find module '@remix-r……
-
28
Hydrogen 里 Storefront token 暴露在客户端要紧吗
构建产物里能看到 Storefront API token，安全扫描提示「密钥泄露」。
-
29
Oxygen 线上 500 但本地一切正常怎么查日志
npm run dev 全部正常，部署到 Oxygen 后首页返回 500……
-
30
Oxygen 部署显示成功但线上还是旧代码怎么办
CI 日志显示 deployment 成功，后台 Deployments 列表时间也是刚刚……
-
31
Oxygen 绑定自定义域名后一直 522 怎么排查
把 shop.example.com 指向 Oxygen 并在 DNS 加了 CNAME，访问返回 522……
-
32
Oxygen 预览部署与生产环境变量怎么隔离
预览环境连到了生产店铺，测试下单影响了真实订单。
-
33
Oxygen 部署后子路由刷新 404 怎么处理
站内跳转正常，但直接在地址栏打开 /collections/xxx 或刷新页面就 404。
-
34
Shopify 生成的类型里 GID 只是 string 怎么约束
codegen 之后 ProductVariant.id 的类型是 string……
-
35
shopify theme check 报错找不到具体文件怎么定位
终端末尾只有一行 3 offenses found 和一段被折行的 LiquidHTMLSyntaxError……
-
36
Shopify theme dev 连不上店铺怎么排查
本地主题开发命令连不上店铺，或无头项目因店面接口令牌无效而拉不到目录数据。
-
37
shopify theme publish 后前台还是旧样式怎么办
shopify theme publish 返回成功，后台主题列表也显示已发布，但前台 HTML 仍是旧版……
-
38
shopify theme pull 把线上主题设置覆盖了怎么恢复
执行 shopify theme pull 后本地 config/settings_data.json 变成商家的配……
-
39
Shopify theme push 覆盖冲突怎么修复
主题推送或无头部署后出现覆盖冲突，线上改动被本地旧分支覆盖，或远程有人同时推送。
-
40
shopify theme push 只想上传指定文件怎么加参数
只改了 sections/header.liquid……
