Next.js pages路由404错误：目录结构不当的解决方案

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Next.js pages路由404错误：目录结构不当的解决方案

2025-11-04

浏览次数：次

返回列表

Next.js pages路由404错误：目录结构不当的解决方案

在next.js项目中，将`pages`目录错误地嵌套在`app`目录内部会导致路由失效并出现404错误。这是因为next.js可能会将根目录的`app`视为`app`路由的入口，从而忽略了内部的`pages`目录。解决此问题的关键在于遵循next.js的路由约定，将`pages`目录直接放置在项目根目录下，确保其被正确识别为页面路由的来源。

Next.js路由机制概述

Next.js提供了两种主要的路由机制：pages路由和app路由。理解它们的约定对于构建正确的项目结构至关重要。

pages路由 (Pages Router)：这是Next.js早期版本的主要路由方式。它依赖于项目根目录下（或src目录下）的pages目录。该目录下的每个文件（例如pages/login.js）都会自动成为一个路由（/login）。
app路由 (App Router)：这是Next.js 13及更高版本引入的最新路由方式，提供了更强大的布局、数据获取和服务器组件功能。它依赖于项目根目录下（或src目录下）的app目录。

这两种路由机制有各自的目录结构约定，不正确的目录嵌套或混用可能导致Next.js无法正确解析路由。

问题现象：pages目录嵌套导致的404错误

当您尝试在Next.js项目中使用pages路由（例如通过next/link组件导航到login页面），但pages目录却被错误地嵌套在另一个名为app的目录内部时，Next.js可能无法识别您的页面文件，从而在访问路由时返回404错误。

错误的目录结构示例：

- project-root/
  - app/            <-- 根目录下的app文件夹
    - pages/        <-- pages文件夹被嵌套在app内部
      - components/
        - N*bar.js
      - login.js
  - global.css
  - layout.js
  - pages.js
  // ...其他项目文件

在这种结构下，尽管您在N*bar.js中使用了next/link来导航，例如：

import Link from "next/link";

export default function N*bar() {
    return (
        <div>
            {/* ...其他导航元素 */}
            <Link href={'login'} className="text-xl bg-login-btn-clr px-8 py-2 rounded-3xl">Login</Link>
        </div>
    )
}

当点击“Login”链接时，Next.js会尝试解析/login路径，但由于pages目录被错误地放置在app目录下，它无法在预期的位置找到login.js文件，最终导致404页面。Next.js可能会将根目录下的app文件夹误认为是app路由的入口，进而忽略其内部的pages目录作为pages路由的定义。

Visla

AI视频生成器，快速轻松地将您的想法转化为视觉上令人惊叹的视频。

100 查看详情 Visla

解决方案：调整项目目录结构

解决此问题的核心是遵循Next.js的pages路由约定，将pages目录直接放置在项目根目录下。如果您的项目是基于pages路由的，那么根目录下的app文件夹（如果它不是用于app路由）应该被移除，以避免混淆。

正确的目录结构示例：

- project-root/
  - pages/          <-- pages文件夹直接位于项目根目录
    - components/
      - N*bar.js
    - login.js      <-- 这将被识别为 /login 路由
  - public/         <-- 静态资源目录
  - styles/         <-- 样式文件目录
  - next.config.js
  - package.json
  // ...其他项目文件

操作步骤：

将app/pages目录移动到项目根目录，使其成为project-root/pages。
删除原有的app目录（如果它不包含任何与app路由相关的有效内容，或者您明确不打算使用app路由）。
确保login.js文件导出一个React组件作为页面。
重要： 更改目录结构后，务必重启Next.js开发服务器（例如，运行npm run dev或yarn dev），以使新的文件结构生效。

通过这种调整，Next.js的pages路由系统将能够正确识别pages/login.js文件，并将其映射到/login路径，从而解决404错误。

最佳实践与注意事项

路由路径规范： 在next/link的href属性中，推荐使用绝对路径（例如href="/login"）而不是相对路径（href="login"），这可以提高路由的健壮性，避免在复杂组件嵌套时出现意外行为。
避免路由机制混淆： 在一个Next.js项目中，应明确选择使用pages路由还是app路由作为主要的路由机制。如果需要同时使用，Next.js通常要求pages目录位于src目录下，而app目录位于项目根目录，或者通过其他配置进行明确区分。不当的混合使用或嵌套是常见的错误源。
文件命名约定： 在pages目录下，文件命名决定了路由路径。例如，pages/users/[id].js会创建动态路由/users/:id。确保您的页面文件（如login.js）位于正确的位置并导出一个有效的React组件。
开发服务器重启： 任何涉及到项目文件结构（特别是pages或app目录）的重大更改，都需要重启Next.js开发服务器才能被正确识别和加载。