排查gatsby-remark-images-remote导致Gatsby构建失败的根因

根因分析 #

1. 插件错误捕获范围不足：你fork的gatsby-remark-images-remote仅处理了无效链接类错误，但Input buffer contains unsupported image format是图片下载完成后，sharp库处理非图片内容（比如链接有效但返回HTML、空文件、损坏的图片文件）时抛出的错误，这部分错误未被你的插件捕获，导致构建终止。
2. gatsby-plugin-sharp配置未生效：虽然你设置了failOn: none，但如果gatsby-remark-images-remote内部调用sharp时没有继承该配置，或是手动指定了错误处理策略，这个全局配置就无法发挥作用。
3. Gatsby默认构建逻辑：Gatsby遇到未被捕获的Node.js错误时会直接终止构建，不会自动跳过单个资源的处理错误。

解决方案 #

1. 扩展fork插件的错误捕获范围 #

修改你fork的gatsby-remark-images-remote代码，在调用sharp处理图片的核心环节添加try-catch，跳过无效图片的处理流程：

async function processRemoteImage(url) {
  try {
    // 下载图片逻辑
    const response = await fetch(url);
    const imageBuffer = await response.arrayBuffer();
    
    // 调用sharp处理前捕获格式错误
    const sharpInstance = sharp(Buffer.from(imageBuffer));
    // 后续图片转换、存储逻辑...
  } catch (err) {
    console.warn(`[gatsby-remark-images-remote] 跳过无效图片: ${url}, 错误信息: ${err.message}`);
    return null; // 返回空值跳过当前图片，继续执行后续构建
  }
}

2. 确保gatsby-plugin-sharp配置生效 #

在gatsby-config.js中确认配置正确，同时在fork的插件内部手动指定sharp的错误策略：

// gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-sharp`,
      options: {
        failOn: `none`, // 全局设置sharp遇到错误不终止构建
      },
    },
    // 其他插件配置...
  ],
};

如果插件内部直接调用sharp，可以在创建实例时显式添加配置：

const sharpInstance = sharp(imageBuffer).failOn('none');

3. 全局忽略构建错误（兜底方案，不推荐） #

如果上述方法都无效，可以通过环境变量强制Gatsby忽略错误继续构建：

# 构建时设置环境变量
GATSBY_BUILD_IGNORE_ERRORS=true gatsby build

注意：该方式会忽略所有构建错误，可能掩盖其他严重问题，仅建议临时应急使用。

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