Gatsby中如何基于GraphQL映射图库图片接入灯箱组件解决undefined报错

先理清组件入参的硬性要求 #

• react-image-gallery要求传入的images参数必须是字段结构匹配的对象数组，每个数组项至少包含original（全屏大图地址）、thumbnail（缩略图地址）两个核心字段
• 组件运行时会直接读取数组项上的上述字段做渲染，如果传入的是GraphQL返回的childImageSharp原始对象，因对象本身不存在对应字段，就会触发undefined属性读取的渲染报错
• 针对你疑惑的「是否需要将childImageSharp集合直接赋值给images参数」的问题，结论是不能直接赋值，必须经过结构转换后再传入，否则100%会触发undefined属性读取的报错

分步实现流程 #

1. 编写匹配需求的GraphQL查询 #

在页面级查询或useStaticQuery hooks中拉取所有图库图片的Sharp处理结果，确保返回结构可支撑后续图片地址生成：

query GalleryResourceQuery {
  allFile(
    filter: { sourceInstanceName: { eq: "gallery-assets" } }
    sort: { order: ASC, fields: name }
  ) {
    nodes {
      name
      childImageSharp {
        gatsbyImageData(
          placeholder: BLURRED
          formats: [AUTO, WEBP, AVIF]
          widths: [400, 800, 1200]
        )
      }
    }
  }
}

2. 做数据结构转换，从根源规避undefined报错 #

拿到查询返回的节点数组后，必须先做两层处理再传入组件：

• 第一重过滤：剔除没有生成childImageSharp结果的无效节点，避免后续读取空对象属性
• 第二重映射：把Sharp返回的图片对象，转换成react-image-gallery能识别的结构

参考转换代码：

import { getImage } from "gatsby-plugin-image"

// 从查询结果中提取并转换图库数据
const buildGalleryItems = (nodes = []) => {
  return nodes
    // 过滤空值节点，直接拦截后续可能的报错
    .filter(node => node.childImageSharp)
    .map(node => {
      const imageAsset = getImage(node.childImageSharp.gatsbyImageData)
      return {
        // 从Sharp生成的图片结构中提取可直接访问的静态资源地址
        original: imageAsset.images.fallback[0].src,
        thumbnail: imageAsset.images.fallback[0].src,
        alt: node.name,
      }
    })
}

3. 增加渲染容错逻辑 #

在组件渲染阶段加数据存在性判断，避免数据未加载完成时组件空跑：

// 拿到转换后的图库数据
const galleryItems = buildGalleryItems(data?.allFile?.nodes)

// 仅在数据有效时渲染画廊组件，杜绝undefined入参触发的报错
return (
  <div className="gallery-container">
    {galleryItems.length > 0 && (
      <ImageGallery
        items={galleryItems}
        showPlayButton={false}
        showFullscreenButton={true}
      />
    )}
  </div>
)

高频报错点对照 #

• 直接将GraphQL返回的childImageSharp原始数组赋值给images参数，未做结构转换
• 未过滤查询结果中childImageSharp为null的无效节点，遍历过程中读取空对象属性
• 初始渲染阶段未做数据判空，此时GraphQL查询结果尚未返回，images入参为undefined

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