Shopify Admin API 401 错误排查指南

问题轮廓#

401 表示未通过身份验证，优先查 access token 是否过期或未放入 Authorization 头。另外，确认用的是 Admin API 令牌而不是 Storefront 令牌。另外，自定义应用在 Dev Dashboard 或后台开发应用里轮换密钥后，旧令牌立即失效。

技术解释#

GraphQL 与 REST 的鉴权头格式以现行 shopify.dev 为准，勿混用私有应用已淘汰说明。随后，用最简单的 shop { name } 查询验证令牌本身是否可用。随后，时间漂移过大可能导致部分 HMAC 场景失败，服务器应对时 NTP。

落地步骤#

1. 记录返回的 WWW-Authenticate 或错误正文，避免只看状态码。
2. 测试与生产店铺令牌分开，防拷错 .env。
3. Partner 应用安装范围变更后需重新授权。
4. 401 连续出现时应暂停重试，以免被限流掩盖根因。

复核清单#

工单附请求 ID 与 Asia/Shanghai 时间。验收阶段，勿在前端暴露 Admin 令牌。