当next.js应用在使用`next/link`进行页面导航时遭遇404错误，这通常源于项目目录结构不当，特别是当`pages`目录被错误地嵌套在`app`目录下时。next.js会优先识别顶层`app`目录作为路由根目录，从而忽略内部的`pages`目录。解决此问题的关键在于确保`pages`目录位于项目根目录，或者明确选择使用app router并遵循其结构规范。
Next.js路由404错误的常见陷阱
在使用Next.js构建应用时，开发者经常会利用next/link组件实现客户端路由跳转。然而，有时尽管代码中Link的href属性看似正确，用户在点击后仍会遇到“404 - Page Not Found”错误。这种问题往往不是Link组件本身的问题，而是Next.js底层文件系统路由机制与项目目录结构之间存在冲突。理解Next.js的两种主要路由机制及其对目录结构的严格要求，是解决此类问题的关键。
理解Next.js的两种路由机制
Next.js提供了两种主要的路由机制，它们基于不同的目录结构和工作原理：
-
Pages Router (页面路由器):
- 这是Next.js早期版本中使用的传统路由方式。
- 它通过项目根目录下的pages文件夹来定义路由。pages目录中的每个文件（例如pages/login.js）都会自动映射为一个对应的路由路径（例如/login）。
- pages目录负责处理页面组件、数据获取方法（如getServerSideProps、getStaticProps）和API路由（pages/api）。
-
App Router (应用路由器):
- 这是Next.js 13及更高版本引入的全新路由机制，基于React Server Components。
- 它通过项目根目录下的app文件夹来定义路由。路由段通过文件夹结构表示，而页面UI则由page.js文件定义（例如app/login/page.js对应/login路径）。
- App Router提供了更强大的布局管理、数据获取、流式传输和嵌套路由能力。
核心冲突点： Next.js在启动时会检测项目根目录。如果它在根目录发现了app文件夹，它会优先将其视为App Router的入口。在这种情况下，如果pages文件夹被错误地嵌套在app文件夹内部（例如app/pages/login.js），Next.js将不会将其识别为Pages Router的路由入口。它会尝试在app目录下寻找匹配的App Router路由，如果找不到，就会返回404错误。
案例分析：不正确的目录结构导致404
考虑以下导致404错误的典型项目结构：
-- (项目根目录) ---- app ------ pages -------- component ---------- Navbar.js -------- login.js ---- global.css ---- layout.js ---- pages.js ---- next.config.js ---- package.json
在这种结构中，开发者可能期望app/pages/login.js能够通过/login路径访问。然而，由于顶层存在app目录，Next.js会认为你在使用App Router。它会尝试在app目录下寻找如app/login/page.js这样的结构来匹配/login路由。由于pages目录被嵌套在app内部，并且没有遵循App Router的命名约定（例如page.js），Next.js将无法找到对应的路由，从而导致404错误。
即使Navbar.js中的next/link使用方式是正确的：
// app/pages/component/Navbar.js
import Link from "next/link";
export default function Navbar() {
return (
Klove
{/* 期望跳转到 /login 页面 */}
Login
HOME
ABOUT
CONTACT
)
}这里的href={'/login'}本身没有问题，但由于文件系统路由未能正确解析app/pages/login.js，导致了404。
解决方案：修正目录结构
解决这个问题的关键在于确保你的路由文件（无论是Pages Router还是App Router）位于Next.js期望的位置。
如果你打算使用Pages Router：
pages目录必须直接位于项目的根目录。你需要将pages目录从app内部移出，并移除顶层的app目录（如果它不用于App Router）。
正确的Pages Router目录结构示例：
-- (项目根目录) ---- pages ------ component -------- Navbar.js ------ login.js // 现在会被正确识别为 /login 路由 ---- public // 静态资源 ---- styles // 全局样式 ---- next.config.js ---- package.json
完成此更改后，Navbar.js中的Link组件将能够正确导航到/login路径，因为pages/login.js现在已被Next.js识别为一个有效的路由页面。
如果你打算使用App Router：
如果你的项目确实想使用App Router，那么你的路由文件应该遵循App Router的结构，例如：
-- (项目根目录) ---- app ------ login -------- page.js // 这将被识别为 /login 路由 ------ layout.js // 根布局 ---- public ---- styles ---- next.config.js ---- package.json
在这种情况下，Navbar.js中的Link仍然可以指向/login，但它会解析到app/login/page.js。
重要注意事项与最佳实践
- 明确选择路由策略： 在一个Next.js项目中，强烈建议明确选择使用Pages Router还是App Router。虽然Next.js支持两种路由方式并存（通过app和pages目录），但在混合使用时，需要非常清楚它们的优先级和各自的约定，以避免混淆和潜在的路由冲突。对于新项目，通常推荐使用App Router。
- src目录的使用： 如果你的项目使用了src目录作为源代码的根目录，那么pages或app目录应放置在src内部（例如src/pages或src/app）。Next.js会自动识别src目录。
- 清空缓存并重启开发服务器： 在修改了项目目录结构后，务必停止并重新启动Next.js开发服务器（通常通过运行npm run dev或yarn dev）。这是因为Next.js会在启动时构建路由映射，重启可以确保新的目录结构被正确识别和加载。
- 路径的相对与绝对： 在next/link的href属性中，使用绝对路径（如'/login'）通常比相对路径更明确和健壮，尤其是在应用结构复杂时。
总结
Next.js的强大之处在于其基于文件系统的路由能力，但这也要求开发者对项目目录结构有清晰的理解。当遇到next/link导致的404错误时，首先应检查项目的根目录是否同时存在app和pages目录，或者pages目录是否被错误地嵌套。通过将pages目录放置在项目根目录（如果使用Pages Router），或严格遵循App Router的目录约定（如果使用App Router），可以有效解决此类路由问题，确保应用能够正确导航。
