MDX中使用gatsby-plugin-image的StaticImage加载失败（tsx环境下正常）

问题现象 #

开发调试MDX功能时，此前可通过GraphQL查询在MDX中正常使用旧版Gatsby Image，切换为gatsby-plugin-image提供的StaticImage组件时出现图片加载失败报错：

react_devtools_backend.js:2557 Image not loaded
https://images.unsplash.com/photo-1597305877032-0668b3c6413a?w=1300

经测试，相同的StaticImage组件代码放在.tsx页面文件中可正常运行，需要明确MDX内是否可使用该组件、定位报错根因及可落地的实现方式。

现有配置与测试代码 #

项目gatsby-config相关配置 #

// 现有插件配置片段
'gatsby-remark-images',
{
  resolve: "gatsby-plugin-mdx",
  options: {
    defaultLayouts: {
      default: require.resolve("./src/components/common/Layout.tsx")
    },
    gatsbyRemarkPlugins: [
      {
        resolve: `gatsby-remark-images`,
        options: {},
      },
    ],
  }
},
{
  resolve: "gatsby-source-filesystem",
  options: {
    name: "images",
    path: `${__dirname}/src/images/`,
  },
  __key: "images",
},

测试MDX文件中的StaticImage调用代码 #

<StaticImage
  src={'https://images.unsplash.com/photo-1597305877032-0668b3c6413a?w=1300'}
  alt={''}
  width={3840}
  height={1000}
  layout={'constrained'}
/>

报错原因定位 #

MDX文件完全可以正常使用StaticImage组件，当前加载失败由三类配置问题共同导致：

• 组件注册链路缺失：MDX编译阶段不会自动注入React组件，未全局映射StaticImage组件的情况下，MDX解析器无法识别对应标签的实现逻辑，直接触发资源抓取失败。而.tsx文件中可正常运行，是因为页面内手动完成了组件导入。
• 插件嵌套位置错误：现有配置中gatsby-remark-images被单独放在顶层插件数组中，没有完全嵌套在gatsby-plugin-mdx的gatsbyRemarkPlugins选项内，既无法对MDX内的Markdown图片做优化处理，也可能和StaticImage的运行时资源加载逻辑产生冲突。
• 远程图片授权缺失：使用外网图片作为StaticImage的src时，没有提前在插件层配置允许抓取的域名白名单，Gatsby构建阶段无法对未授权域名的图片做下载、格式转换，最终出现图片加载失败。

可正常运行的实现调整步骤 #

1. 全局映射StaticImage到MDX上下文
   调整gatsby-plugin-mdx配置，新增components映射项，让MDX解析时能自动识别StaticImage标签：

   {
     resolve: "gatsby-plugin-mdx",
     options: {
       defaultLayouts: {
         default: require.resolve("./src/components/common/Layout.tsx")
       },
       // 新增组件映射配置
       components: {
         StaticImage: require.resolve("gatsby-plugin-image").StaticImage
       },
       gatsbyRemarkPlugins: [
         {
           resolve: `gatsby-remark-images`,
           options: {
             maxWidth: 1200,
           },
         },
       ],
     }
   }
   

   注意：移除顶层插件数组中单独放置的gatsby-remark-images条目，避免插件重复加载触发逻辑冲突。
2. 完善gatsby-plugin-image基础配置
   确保项目根插件列表中正确注册gatsby-plugin-image插件，补充基础默认配置：

   {
     resolve: `gatsby-plugin-image`,
     options: {
       defaults: {
         placeholder: "blurred",
         formats: ["auto", "webp", "avif"],
       },
     },
   },
   

3. 远程图片抓取授权
   针对Unsplash域名的远程图片，在gatsby-node.js中补充授权配置，允许Gatsby抓取对应域名的图片资源用于StaticImage处理。
4. 配置调整完成后，删除项目本地的.cache目录，重启本地开发服务即可正常加载图片。

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