Gatsby构建失败：404页面与gtag插件报错排查求助

错误根源 #

从报错日志的TypeError: Cannot read properties of undefined (reading 'map')可以直接定位问题：gatsby-plugin-google-gtag的配置项trackingIds未被正确设置，导致代码尝试调用undefined.map()时抛出异常，进而中断了404页面的静态HTML构建流程。

解决步骤 #

• 检查插件配置格式：打开gatsby-config.js，确保trackingIds是数组类型，哪怕只有一个跟踪ID也要用数组包裹：

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-google-gtag`,
      options: {
        // 正确示例：数组格式的跟踪ID列表
        trackingIds: [
          "GA-123456789", // 替换成你的Google Analytics ID
        ],
        // 其他可选配置（按需保留）
        gtagConfig: {
          anonymize_ip: true,
        },
        pluginConfig: {
          head: false,
          respectDNT: true,
        },
      },
    },
  ],
}

• 排查环境变量问题：如果用环境变量动态设置trackingIds，要避免变量不存在时返回undefined，确保始终返回数组（空数组也可，只是插件不会生效）：

// 错误写法：环境变量不存在时trackingIds为undefined
trackingIds: process.env.GA_ID ? [process.env.GA_ID] : undefined

// 正确写法：兜底返回空数组
trackingIds: process.env.GA_ID ? [process.env.GA_ID] : []

• 清除缓存重新构建：确认配置无误后，执行以下命令清除Gatsby缓存再重新构建，避免旧缓存干扰：

gatsby clean && gatsby build

为什么404页面会触发报错？ #

Gatsby在构建静态站点时会自动生成404页面，gatsby-plugin-google-gtag会尝试为所有页面注入统计代码，包括404页。当插件配置错误时，404页的HTML渲染流程会最先暴露这个问题，导致整个构建失败。

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