Gatsby构建失败求助：部署时/404/页面静态HTML生成失败

问题概述 #

部署Gatsby项目时持续触发构建失败，核心错误为Building static HTML failed for path /404/，已执行以下操作但未解决：

• 多次重新构建项目
• 删除本地缓存（.cache目录）与node_modules后重装依赖
• 重新触发部署流程

错误日志如下：

Truncated page data information for the failed page /404/: {
  "errors": {},
  "path": "/404/",
  "slicesMap": {},
  "pageContext": {}
}
Building static HTML failed for path /404/

排查与解决方案 #

1. 检查404页面组件的浏览器API使用 #

Gatsby静态构建在Node.js环境执行，若404组件中直接使用window、document等浏览器专属API，会导致构建失败。解决方式：

• 用条件判断包裹浏览器API调用，例如：

  if (typeof window !== "undefined") {
    // 浏览器端逻辑
  }
  

• 或使用Gatsby的useEffect钩子，确保代码在客户端渲染时执行

2. 启用详细构建日志 #

默认日志截断了关键错误信息，运行以下命令获取完整调试日志：

gatsby build --verbose

通过详细日志定位404组件中具体的语法错误、数据获取问题或依赖冲突

3. 验证依赖版本兼容性 #

• 检查package.json中gatsby、react、react-dom的版本是否匹配
• 尝试降级或升级到稳定版本组合，确保各依赖版本兼容

4. 简化404组件定位问题 #

• 临时将404组件替换为极简版本：

  import * as React from "react"
  
  const NotFoundPage = () => {
    return <h1>404 Not Found</h1>
  }
  
  export default NotFoundPage
  

• 重新执行构建，若构建成功，再逐步恢复原组件内容，逐一排查引入的问题代码

5. 检查数据获取逻辑 #

若404组件使用useStaticQuery或getStaticProps获取数据：

• 验证查询语句是否正确，无语法错误
• 确保数据源在构建环境中可访问，且返回数据格式符合预期

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