路由基础
路由是每个应用的骨架。本页将介绍 Web 路由的基础概念以及如何在 Next.js 中处理路由。
术语
首先,您会在文档中频繁遇到这些术语。以下是快速参考:

- 树 (Tree): 用于可视化层次结构的约定。例如包含父子组件的组件树、文件夹结构等。
- 子树 (Subtree): 树的一部分,从新根节点(首个)开始到叶节点(末个)结束。
- 根节点 (Root): 树或子树中的第一个节点,例如根布局。
- 叶节点 (Leaf): 子树中没有子节点的节点,例如 URL 路径的最后一段。

- URL 片段 (URL Segment): 由斜杠分隔的 URL 路径部分。
- URL 路径 (URL Path): 域名之后的部分(由多个片段组成)。
app
路由
在版本 13 中,Next.js 推出了基于 React 服务端组件 构建的新 App 路由,支持共享布局、嵌套路由、加载状态、错误处理等功能。
App 路由在名为 app
的新目录中工作。app
目录与 pages
目录共存以实现渐进式迁移。您可以将部分路由迁移到新行为,同时保留其他路由在 pages
目录中使用旧行为。如果应用使用 pages
目录,请同时参阅 Pages 路由 文档。
须知: App 路由优先级高于 Pages 路由。跨目录的路由不应解析到相同 URL 路径,否则会引发构建时错误以防止冲突。

默认情况下,app
内的组件是 React 服务端组件。这是性能优化项且便于使用,您也可以选择 客户端组件。
推荐: 如果您不熟悉服务端组件,请查阅 服务端组件 页面。
文件夹与文件的作用
Next.js 使用基于文件系统的路由规则:
路由段
路由中的每个文件夹代表一个路由段。每个路由段映射到 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 组件按特定层级渲染:
layout.js
template.js
error.js
(React 错误边界)loading.js
(React Suspense 边界)not-found.js
(React 错误边界)page.js
或嵌套的layout.js

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

同置
除了特殊文件外,您还可以在 app
目录的文件夹中同置自己的文件(例如组件、样式、测试等)。
这是因为虽然文件夹定义路由,但只有 page.js
或 route.js
返回的内容可公开访问。

了解更多关于 项目组织与同置。
高级路由模式
App 路由还提供了一系列约定来实现更高级的路由模式,包括:
- 并行路由: 允许在同一视图中同时展示两个或多个可独立导航的页面。适用于具有子导航的拆分视图(例如仪表盘)。
- 拦截路由: 允许拦截路由并在另一路由的上下文中展示。适用于需要保持当前页面上下文的情况(例如编辑任务时查看所有任务,或在信息流中展开照片)。
这些模式让您能构建更丰富复杂的 UI,使历史上对小团队和个人开发者难以实现的功能变得民主化。
下一步
现在您已了解 Next.js 路由基础,点击以下链接创建您的第一个路由: