Next.js 路由系统

发表于

Next.js 路由系统（约定式路由）

Next.js 的路由系统基于 约定大于配置 原则，开发者只需要将页面组件放在特定目录下，即可自动生成对应的路由，无需手动配置路由表。

路由基本约定

  1. 所有路由文件必须放在 app/ 目录下（App Router 模式）。
  2. 每个文件夹表示一个 URL 路径段。
  3. 路由页面文件必须命名为 page.tsx 或 page.js。
  4. 每个页面组件将自动作为一个路由。

示例

app/
├── page.tsx → 路由路径 /
├── about/
│ └── page.tsx → 路由路径 /about
└── contact/
└── page.tsx → 路由路径 /contact

动态路由

使用 [] 包裹文件夹名来创建动态路由参数。

示例

app/
└── products/
└── [productId]/
└── page.tsx → 路由路径 /products/:productId

1
2
3
4
// products/[productId]/page.tsx
export default function ProductPage({ params }: { params: { productId: string } }) {
  return <div>Product ID: {params.productId}</div>;
}

嵌套动态路由

支持多级动态参数结构。
app/
└── products/
└── [productId]/
├── page.tsx → /products/:productId
└── [reviewId]/
└── page.tsx → /products/:productId/:reviewId

捕获所有路由段（Catch-All Routes）

使用 […slug] 语法捕获任意数量的路径段。

示例

app/
└── blog/
└── […slug]/
└── page.tsx → /blog/* 动态匹配所有子路径

1
2
3
4
// blog/12
export default function CatchAllPage({ params }: { params: { slug: string[] } }) {
  return <div>路径段: {params.slug.join(' / ')}</div>;
}

404 页面（Not Found）

全局 404 页面
app/not-found.tsx

你也可以为每个路由子目录创建局部 404 页面：
app/
└── about/
├── not-found.tsx
└── page.tsx

在 not-found.tsx 中定义页面不存在时的 UI：

1
2
3
export default function NotFound() {
  return <h2>此页面不存在</h2>;
}

主动触发 404
你可以通过 notFound() 方法主动触发 404：

1
2
3
4
5
6
import { notFound } from 'next/navigation';

export default function Page({ params }) {
  if (!data) return notFound();
  return <div>正常页面内容</div>;
}

私有文件夹（下划线命名）

使用下划线 _ 开头的文件夹（如 _components/）不会被视为路由路径。

  • 通常用于存放共享组件、工具函数、布局模板等。
  • 如果确实需要使用下划线路径（不推荐），需通过 %5f URL 编码。

路由分组（Route Groups）

使用 括号 () 包裹文件夹名 创建逻辑上的路由分组，不影响实际 URL 路径结构。

app/
└── (auth)/
└── login/
└── page.tsx → /login

小结

功能 语法/文件名 示例路径
静态路由 page.tsx /about
动态路由 [id]/page.tsx /products/123
嵌套路由 子目录结构 /products/123/reviews/1
捕获全部路由 […slug] /blog/a/b/c
404 页面 not-found.tsx /about/not-found.tsx
路由分组 (group)/ /login from (auth)/login
私有目录 _components/ 不作为路由路径