Shopify Hydrogen通过GraphQL获取博客文章遇UNAUTHORIZED错误

问题现象 #

• 此前稳定运行的博客文章拉取功能突然失效，返回500错误：

  Oops
  500 [h2:error:storefront.query] [object Object] - Request ID: 3c8bc60f-d909-4821-89e7-6fd796495c13-1712578684
  

• 通过GraphiQL排查，返回明确授权错误：

  {
    "errors": [
      {
        "message": "",
        "extensions": {
          "code": "UNAUTHORIZED"
        }
      }
    ]
  }
  

• 所有文章均受影响；Shopify后台无主动变更，文章状态为visible；非无头站点可正常展示文章，主博客集合能加载文章及关联资源，但直接通过GraphQL拉取单篇文章时触发错误。

执行的GraphQL查询语句 #

query Article($articleHandle: String!, $blogHandle: String!, $country: CountryCode, $language: LanguageCode) @inContext(language: $language, country: $country) {
  blog(handle: $blogHandle) {
    articleByHandle(handle: $articleHandle) {
      title
      contentHtml
      publishedAt
      author: authorV2 {
        name
      }
      image {
        id
        altText
        url
        width
        height
      }
      seo {
        description
        title
      }
    }
  }
}

排查思路 #

• 验证Storefront API密钥有效性：
  • 检查Shopify后台「应用和销售渠道」中对应应用的API密钥状态，确认是否被意外禁用、删除或过期。
  • 核对请求中携带的X-Shopify-Storefront-Access-Token是否正确，排查是否存在拼写错误或被无意替换。
• 检查API权限范围：
  • 确认应用的Storefront API权限是否包含read_content权限——这是拉取博客文章的必要权限，可能因平台自动更新或误操作导致权限丢失。
• 校验上下文参数合法性：
  • 检查请求中的country和language参数是否为Shopify支持的有效值，非法参数可能触发授权类错误。
  • 测试移除@inContext指令后能否正常查询，排除上下文参数引发的权限校验问题。
• 排查店铺访问限制配置：
  • 确认博客文章是否设置了地区访问限制，即使状态为visible，地区限制也可能导致Storefront API返回授权错误。
  • 检查店铺是否启用密码保护，若启用，Storefront API请求需携带正确的密码参数，否则会触发授权失败。
• 排查平台侧问题：
  • 查看Shopify状态页面确认是否存在Storefront API服务故障或维护。
  • 使用提供的请求ID联系Shopify支持，查询该请求的具体错误详情，平台侧可能存在未暴露的权限变更或日志。
• 测试简化查询定位问题：
  • 先执行极简查询（仅请求文章标题），排查是否因请求字段过多触发权限限制：

    query Article($articleHandle: String!, $blogHandle: String!) {
      blog(handle: $blogHandle) {
        articleByHandle(handle: $articleHandle) {
          title
        }
      }
    }
    

  • 若极简查询正常，逐步添加字段，定位是否因某个特定字段的权限问题导致报错。

内容的提问来源于stack exchange，提问作者hanji