Gatsby接入Strapi读取图片localFile.publicURL出现未定义报错

当前GraphQL查询中image节点下缺失localFile关联字段，本质是项目未完成Strapi媒体资源和Gatsby本地文件节点的打通链路，不是gatsby-source-strapi版本本身的问题。

1. 安装缺失的依赖包
   执行命令安装图片处理相关的必备依赖：
   npm install gatsby-plugin-sharp gatsby-transformer-sharp
   安装时注意依赖版本要和当前项目的Gatsby核心版本完全匹配，跨大版本安装会导致插件加载失效。
2. 调整gatsby-config.js的插件加载顺序与配置
   必须把sharp相关插件放在gatsby-source-strapi之前加载，否则插件无法识别同步下来的媒体文件节点。调整后的配置参考：

   module.exports = {
     plugins: [
       "gatsby-plugin-react-helmet",
       // 图片处理插件优先加载
       `gatsby-plugin-sharp`,
       `gatsby-transformer-sharp`,
       {
         resolve: `gatsby-source-filesystem`,
         options: {
           name: `images`,
           path: `${__dirname}/src/images`,
         },
       },
       {
         resolve: "gatsby-source-strapi",
         options: {
           apiURL:  "http://localhost:1337",
           contentTypes: ["articles"],
           singleTypes: [`homepage`, `global`],
           queryLimit: 1000,
         },
       },
       "gatsby-plugin-postcss",
     ],
   };
   

   同时要确认Strapi后台的公开权限配置：在Strapi的用户权限设置中，给公开角色勾选媒体资源的查询权限，否则gatsby-source-strapi无法拉取到图片的完整元数据，自然不会生成对应的localFile关联节点。
3. 修正代码中的空值容错逻辑
   原有代码直接多层嵌套读取属性，一旦某篇文章没有上传封面图，就会触发Cannot read property 'publicURL' of undefined的报错。需要给属性读取加可选链兜底，调整图片渲染部分的代码：

   <img
     className="w-10 h-10 object-cover object-center rounded-full"
     src={article.node.image?.localFile?.publicURL ?? '/default-cover.png'}
     alt={article.node.title}
   />
   

• 所有配置修改完成后，必须删除项目根目录下的.cache缓存文件夹，再重启Gatsby开发服务，否则旧的GraphQL schema不会更新，依然会找不到localFile字段
• 如果使用的是Strapi v3版本，需要搭配对应兼容的gatsby-source-strapi v0.x版本，和Strapi v4的配套v1+插件不兼容，会出现媒体字段拉取不全的问题
• 正式生产场景不推荐直接读取localFile.publicURL，可以配套使用Gatsby的图片优化组件，自动生成多尺寸、压缩后的图片资源，提升页面加载性能

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