Gatsby项目构建或Serve时出现ENOENT错误：找不到404.html文件

Hey，我碰到过好几次这种Gatsby 404页面的问题，咱们一步步来排查解决：

1. 确认404页面的文件路径与命名是否合规 #

Gatsby默认会把src/pages/404.js（或.jsx/.tsx）编译成public/404.html，这是硬规则：

• 检查你的404页面是不是放在src/pages目录下，文件名是不是严格的404加上正确的后缀（比如404.js），别写成NotFound.js或者放在子目录里，否则Gatsby不会自动生成对应的html文件。
• 如果是用TypeScript，确保文件名是404.tsx，并且文件内容是有效的React组件（至少要有基本的导出：export default function NotFound() { ... }）。

2. 检查pathPrefix与构建参数 #

如果你在gatsby-config.js里配置了pathPrefix（比如为了部署到子路径）：

• 构建时必须加上--prefix-paths参数：gatsby build --prefix-paths，否则生成的文件路径会不匹配，导致gatsby serve时找不到404.html。
• 可以先临时注释掉pathPrefix配置，重新构建测试，如果正常了，就是路径前缀的问题。

3. 清理Gatsby缓存 #

缓存残留是很多奇怪构建问题的元凶：

• 执行gatsby clean命令清除所有缓存文件和生成的public目录，然后再运行gatsby build，大概率能解决文件找不到的问题。

4. 排查文件权限（仅限Linux/macOS） #

如果是在类Unix系统下，可能是文件权限不足导致Gatsby无法生成或读取404.html：

• 检查src/pages/404.js的权限，确保当前用户有读写权限（可以用ls -l src/pages/404.js查看）。
• 临时用sudo gatsby build测试，如果能正常生成，就调整文件或目录的权限（比如sudo chown -R $USER:$USER ./），别长期用sudo运行Gatsby。

5. 检查gatsby-node.js的自定义页面配置 #

如果你在gatsby-node.js里用createPage API手动创建页面：

• 有没有不小心覆盖了默认的404页面生成逻辑？比如设置了错误的matchPath或者删除了默认的页面生成规则。
• 可以临时注释掉createPage相关代码，重新构建测试，如果正常了，再逐步排查自定义代码的问题。

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