执行gatsby build时/404/页面静态HTML构建失败求助

问题情况 #

执行gatsby build时触发ERROR #95313，提示/404/路径的静态HTML构建失败；把gatsby-config.js里的gatsby-plugin-google-gtag注释掉之后，构建就能正常完成，显然问题出在这个插件上，以下是具体排查方向和解决办法：

排查方向和解决办法 #

1. 插件配置的GTAG ID无效或结构错误 #

先核对gatsby-config.js中gatsby-plugin-google-gtag的配置，确保trackingIds里填的是有效的Google Analytics/GTAG ID，配置结构也没有写错：

// 正确配置示例
module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-google-gtag`,
      options: {
        trackingIds: [
          "GA-XXXXXXXXX", // 替换成你自己的有效ID
        ],
        pluginConfig: {
          head: false, // 可选：是否将脚本放在<head>中
          respectDNT: true,
          exclude: ["/preview/**", "/do-not-track/me/too/"],
        },
      },
    },
  ],
};

如果ID无效或格式错误，插件在渲染404页面时可能抛出未捕获的错误，直接导致HTML构建失败。

2. 404页面代码直接调用未初始化的GTAG对象 #

检查404.js页面，有没有直接操作window.gtag的逻辑——插件可能还没初始化这个全局对象，直接调用就会报错：

// 错误示例：未检查window.gtag是否存在
useEffect(() => {
  window.gtag('event', '404_page_view', {
    page_path: window.location.pathname
  });
}, []);

修复方式：先做存在性检查再调用

// 修复后的代码
useEffect(() => {
  if (typeof window !== 'undefined' && window.gtag) {
    window.gtag('event', '404_page_view', {
      page_path: window.location.pathname
    });
  }
}, []);

3. Gatsby与插件版本不兼容 #

查看package.json中gatsby和gatsby-plugin-google-gtag的版本号，确保二者兼容。最简单的处理方式是升级到最新稳定版：

npm update gatsby gatsby-plugin-google-gtag

也可以直接指定兼容的版本（参考插件官方版本说明）：

// package.json 示例
{
  "dependencies": {
    "gatsby": "^5.12.0",
    "gatsby-plugin-google-gtag": "^5.12.0"
  }
}

4. 将404页面加入插件排除列表 #

部分场景下，插件默认会跟踪所有页面，如果你的404页面有特殊渲染逻辑，不妨把/404/加到exclude列表中：

options: {
  pluginConfig: {
    exclude: ["/404/", "/404.html"],
  },
},

调试小技巧 #

• 执行gatsby build --verbose获取详细错误栈，精准定位报错位置：

gatsby build --verbose

• 查看构建后生成的public/404.html文件，检查GTAG脚本是否加载异常，或者是否存在未闭合的HTML标签。

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