Next.js项目npm run dev出现404错误，多方案尝试无效

问题场景 #

运行侧边Next.js项目时，执行npm run dev后访问终端提供的正确链接，网站返回404错误。终端无报错，仅能看到对应GET请求，且输出Compiled /_not-found。此前项目运行正常，回滚版本控制后问题仍存在；同时终端出现webpack缓存警告：

<w> [webpack.cache.PackFileCacheStrategy] Caching failed for pack: Error: Unable to snapshot resolve dependencies
<w> [webpack.cache.PackFileCacheStrategy] Caching failed for pack: Error: Unable to snapshot resolve dependencies

即使重新创建项目，缓存警告消失，但404问题依旧。

已尝试以下方案未解决：

• 清理并重建项目：

rm -rf .next
rm -rf node_modules
rm package-lock.json
npm install
npm run dev

• 修复路由目录结构：
  • 创建(auth)路由组文件夹
  • 添加src/app/(auth)/layout.tsx布局文件
  • 确保登录/注册页面路径正确：

    src/app/(auth)/login/page.tsx
    src/app/(auth)/signup/page.tsx
    

• 更新配置文件：
  • 在next.config.js中启用appDir实验特性：

    experimental: {
      appDir: true,
    }
    

  • 更新tsconfig.json的路径配置：

    "paths": {
      "@/*": ["./src/*"]
    },
    "baseUrl": "."
    

• 添加Auth布局组件：

  export default function AuthLayout({
    children,
  }: {
    children: React.ReactNode
  }) {
    return (
      <div className="min-h-screen">
        {children}
      </div>
    )
  }
  

进一步排查与解决方案 #

1. 确认根路由页面存在 #

检查src/app/page.tsx（App Router）或pages/index.tsx（Pages Router）是否存在且内容正常。Next.js访问根路径时找不到对应页面会自动渲染_not-found组件。

2. 验证根布局的正确性 #

若使用App Router，必须确保根布局src/app/layout.tsx存在且正确传递children，否则会导致所有路由无法正常渲染：

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="zh-CN">
      <body>{children}</body>
    </html>
  )
}

3. 调整Next.js版本 #

部分早期App Router版本存在路由解析bug，尝试升级到最新稳定版或降级到已知兼容版本：

# 升级到最新版
npm install next@latest

# 或降级到13.4.19（已知稳定版本）
npm install next@13.4.19

4. 禁用webpack缓存测试 #

虽然缓存警告在新项目中消失，但缓存异常可能间接影响路由解析。在next.config.js中禁用缓存后重试：

module.exports = {
  webpack: (config) => {
    config.cache = false;
    return config;
  },
};

5. 排查路由重定向规则 #

检查项目中是否存在middleware.ts或环境变量配置了意外的重定向逻辑，导致请求被导向不存在的路径。

6. 严格遵循文件命名规范 #

确保路由相关文件（page.tsx、layout.tsx）命名符合要求：

• 文件名全小写，仅允许-和_作为特殊字符
• 避免同一目录下存在同名不同后缀的文件（如page.js与page.tsx共存）

内容的提问来源于stack exchange，提问作者Lars van de Griend