路由基础

路由是每个应用的骨架。本页将介绍 Web 路由的基础概念以及如何在 Next.js 中处理路由。

术语

首先,您会在文档中频繁遇到这些术语。以下是快速参考:

组件树术语
  • 树 (Tree): 用于可视化层次结构的约定。例如包含父子组件的组件树、文件夹结构等。
  • 子树 (Subtree): 树的一部分,从新根节点(首个)开始到叶节点(末个)结束。
  • 根节点 (Root): 树或子树中的第一个节点,例如根布局。
  • 叶节点 (Leaf): 子树中没有子节点的节点,例如 URL 路径的最后一段。
URL 结构术语
  • URL 片段 (URL Segment): 由斜杠分隔的 URL 路径部分。
  • URL 路径 (URL Path): 域名之后的部分(由多个片段组成)。

app 路由

在版本 13 中,Next.js 推出了基于 React 服务端组件 构建的新 App 路由,支持共享布局、嵌套路由、加载状态、错误处理等功能。

App 路由在名为 app 的新目录中工作。app 目录与 pages 目录共存以实现渐进式迁移。您可以将部分路由迁移到新行为,同时保留其他路由在 pages 目录中使用旧行为。如果应用使用 pages 目录,请同时参阅 Pages 路由 文档。

须知: App 路由优先级高于 Pages 路由。跨目录的路由不应解析到相同 URL 路径,否则会引发构建时错误以防止冲突。

Next.js App 目录

默认情况下,app 内的组件是 React 服务端组件。这是性能优化项且便于使用,您也可以选择 客户端组件

推荐: 如果您不熟悉服务端组件,请查阅 服务端组件 页面。

文件夹与文件的作用

Next.js 使用基于文件系统的路由规则:

  • 文件夹用于定义路由。路由是从根文件夹到最终包含 page.js 文件的叶文件夹的嵌套文件夹路径。参见 定义路由
  • 文件用于创建路由段对应的 UI。参见 特殊文件

路由段

路由中的每个文件夹代表一个路由段。每个路由段映射到 URL 路径 中的对应片段

路由段如何映射到 URL 片段

嵌套路由

要创建嵌套路由,可以将文件夹互相嵌套。例如,通过在 app 目录中嵌套两个新文件夹,可添加 /dashboard/settings 路由。

/dashboard/settings 路由由三个段组成:

  • / (根段)
  • dashboard (段)
  • settings (叶段)

文件约定

Next.js 提供了一组特殊文件来为嵌套路由创建具有特定行为的 UI:

layout为路由段及其子项提供共享 UI
page路由的唯一 UI 并使路由可公开访问
loading为路由段及其子项提供加载 UI
not-found为路由段及其子项提供 404 UI
error为路由段及其子项提供错误 UI
global-error全局错误 UI
route服务端 API 端点
template专用于重新渲染的布局 UI
default并行路由 提供回退 UI

须知: 特殊文件可使用 .js.jsx.tsx 扩展名。

组件层级

路由段特殊文件中定义的 React 组件按特定层级渲染:

  1. layout.js
  2. template.js
  3. error.js (React 错误边界)
  4. loading.js (React Suspense 边界)
  5. not-found.js (React 错误边界)
  6. page.js 或嵌套的 layout.js
文件约定的组件层级

在嵌套路由中,子段的组件会嵌套在其父段组件内部

嵌套文件约定的组件层级

同置

除了特殊文件外,您还可以在 app 目录的文件夹中同置自己的文件(例如组件、样式、测试等)。

这是因为虽然文件夹定义路由,但只有 page.jsroute.js 返回的内容可公开访问。

包含同置文件的文件夹结构示例

了解更多关于 项目组织与同置

高级路由模式

App 路由还提供了一系列约定来实现更高级的路由模式,包括:

  • 并行路由: 允许在同一视图中同时展示两个或多个可独立导航的页面。适用于具有子导航的拆分视图(例如仪表盘)。
  • 拦截路由: 允许拦截路由并在另一路由的上下文中展示。适用于需要保持当前页面上下文的情况(例如编辑任务时查看所有任务,或在信息流中展开照片)。

这些模式让您能构建更丰富复杂的 UI,使历史上对小团队和个人开发者难以实现的功能变得民主化。

下一步

现在您已了解 Next.js 路由基础,点击以下链接创建您的第一个路由:

On this page