Next.js自定义错误组件不显示问题求助

可能的原因及排查步骤 #

• 核对Next.js版本与路由模式
  不同版本的路由规则有差异：

  • 若使用Next.js 13+的App Router模式，自定义404页面需放在app目录下并命名为not-found.js，pages/404.js不再生效；
  • 若使用Pages Router（Next.js 12及以下，或13+仍保留Pages Router），才需要将404.js放在pages根目录。

• 确认文件路径与命名规范
  确保404.js处于pages目录的根层级，不能嵌套在子文件夹中（如pages/errors/404.js无效）；文件名必须为小写的404.js（若用TypeScript则对应404.tsx）。

• 检查组件导出是否正确
  确保文件中只有一个默认导出，无语法错误。可简化代码验证：

  export default function Custom404() {
    return <h1>404 - 页面未找到</h1>;
  }
  

• 清除缓存并重启开发服务
  Next.js开发服务器可能缓存旧配置，执行以下操作：

  1. 终止当前服务（Ctrl+C）；
  2. 删除项目根目录下的.next文件夹；
  3. 重新运行npm run dev或yarn dev。

• 验证生产环境构建结果
  开发环境的缓存可能导致异常，尝试构建生产版本并启动：

  npm run build
  npm run start
  

  访问不存在的路径，查看自定义404页面是否正常显示。

• 排查路由或中间件干扰
  若项目中有next.config.js里的rewrites/redirects配置，或middleware.js中间件，可能拦截404请求，需检查这些配置是否影响了404页面的渲染。

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