Next.js本地服务localhost:3001全路由突现404页面问题排查

• 核对路由目录结构

  • Pages Router：确认pages目录下文件命名/层级是否符合规则，比如动态路由需命名为[id].js，检查_app.js/_document.js是否存在逻辑错误导致路由失效。
  • App Router：确认app目录下每个路由分支都包含layout.js和page.js，动态路由文件夹需为[param]格式，避免文件名拼写错误（比如把page.js写成pages.js）。

• 检查服务启动与环境配置

  • 确保启动命令为next dev，不要误使用next start（该命令需先执行next build）。
  • 查看.env文件中的BASE_PATH或NEXT_PUBLIC_BASE_PATH配置，若设置了路径前缀，需确保前缀与实际路由匹配。

• 排查路由跳转与中间件

  • 检查项目中next/link组件的href属性是否拼写正确，避免使用原生<a>标签直接跳转可能引发的问题。
  • 若存在middleware.js/ts，核对其中的路由重写、匹配规则，确认没有错误拦截或重定向所有请求到404。

• 验证版本兼容性

  • 查看package.json中next版本，若近期有版本升级，可能存在路由规则变更，可尝试回退至之前能正常运行的版本：npm install next@x.x.x（替换为对应版本号）。

• 清理额外缓存与权限检查

  • 重启编辑器（如VS Code）清除编辑器缓存，同时确认pages/app目录下文件无权限锁定问题，确保Next.js能正常读取路由文件。

• 检查自定义服务器配置（若有）

  • 若项目使用了自定义server.js，核对其中的路由处理逻辑，避免错误的匹配规则导致所有请求返回404。

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