Shopify Storefront API productByHandle返回undefined问题求助

问题场景 #

跟随教程开发时，已成功从路径中获取handle（URL可见且经console.log验证），但productByHandle查询无法正常工作。其他页面使用products查询可正常运行，尝试替换为固定handle值'gift-card'后仍报错，产品权限已全部开放。

错误信息 #

Error fetching product data: TypeError: Cannot read properties of undefined (reading 'productByHandle')
at getStaticProps (webpack-internal:///./pages/products/[handle].js:375:31)
at process.processTicksAndRejections (node:internal/process/task_queues:95:5)

相关代码 #

GraphQL查询语句 #

const handleQuery = gql`
    query Products {
        products(first: 10) {
            edges {
                node {
                    handle
                }
            }
        }
    }
`

const singleProductQuery = gql`
    query SingleProduct($handle: String!) {
        productByHandle(handle: $handle) {
            title
            handle
            updatedAt
            priceRangeV2 {
                minVariantPrice {
                amount
                }
            }
            images(first: 1) {
                edges {
                node {
                    transformedSrc
                    altText
                }
                }
            }
        }
    }
`

getStaticPaths与getStaticProps代码 #

export async function getStaticPaths() {
    try { 
    const { data } = await storefront(handleQuery)
    console.log("Path data:", data.products.edges);    
    return {
        paths: data.products.edges.map(product => (
            { 
                params: {
                    handle: product.node.handle
                } 
            }
        )),
        fallback: false, 
    }} catch (error) {
        console.error("Error fetching handle path: ", error); 
        return {
            paths: [{
                params: {
                    handle: null
                }
            }]
        }
    }
}

export async function getStaticProps({params}) { 
    try {
        const { data } = await storefront(singleProductQuery, {handle: params.handle})
        console.log("Response data:", data);    

        return {
            props: {
                product: data.productByHandle,
            }
        };
      } catch (error) {
        console.error("Error fetching product data:", error);
        return {
          props: {
            product: null, // Handle the error case with a default value or null
          },
        };
      }
}

排查与解决步骤 #

1. 在Shopify GraphQL Playground中测试查询
   直接在Shopify后台的GraphQL Playground（应用->Manage private apps->找到你的Storefront应用->点击GraphQL Playground）中运行singleProductQuery，传入固定handle值，比如：

   query SingleProduct {
       productByHandle(handle: "gift-card") {
           title
           handle
       }
   }
   

   • 如果Playground中也无法返回数据：检查API版本是否支持productByHandle（建议使用最新稳定版）、确认产品handle是否正确、检查Storefront API权限是否包含read_products。
   • 如果Playground中能正常返回数据：问题出在代码中的storefront客户端调用。

2. 检查storefront客户端配置
   确认storefront函数是否正确配置了店铺域名、Storefront访问令牌、API版本。可以在调用时打印完整响应，而不是仅打印data：

   const response = await storefront(singleProductQuery, {handle: params.handle})
   console.log("Full API response:", response)
   

   查看响应中是否有errors字段，这会暴露API返回的具体错误（比如权限不足、版本不兼容）。

3. 添加数据存在性判断
   即使API调用成功，data也可能为undefined，所以在访问data.productByHandle前增加可选链判断，避免报错：

   return {
       props: {
           product: data?.productByHandle || null,
       }
   };
   

4. 确认变量传递正确性
   在getStaticProps中打印传入的变量值，确保params.handle是正确的字符串：

   console.log("Current handle:", params.handle)
   

   注意Shopify的handle是全小写的，若传入值存在大小写问题会导致查询失败。

5. 检查API版本兼容性
   某些旧版本的Storefront API可能对字段名有调整，确保使用的API版本支持productByHandle（推荐使用2024-01及以后版本）。

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