路由基础知识

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

¥The skeleton of every application is routing. This page will introduce you to the fundamental concepts of routing for the web and how to handle routing in Next.js.

术语

¥Terminology

首先，你将看到整个文档中使用了这些术语。这是一个快速参考：

¥First, you will see these terms being used throughout the documentation. Here's a quick reference:

• 树：用于可视化层次结构的约定。例如，具有父组件和子组件的组件树、文件夹结构等。

  ¥Tree: A convention for visualizing a hierarchical structure. For example, a component tree with parent and children components, a folder structure, etc.

• 子树：树的一部分，从新的根（第一个）开始，到叶子（最后一个）结束。

  ¥Subtree: Part of a tree, starting at a new root (first) and ending at the leaves (last).

• 根：树或子树中的第一个节点，例如根布局。

  ¥Root: The first node in a tree or subtree, such as a root layout.

• 叶子：子树中没有子节点的节点，例如 URL 路径中的最后一段。

  ¥Leaf: Nodes in a subtree that have no children, such as the last segment in a URL path.

• 网址段：URL 路径的一部分，由斜杠分隔。

  ¥URL Segment: Part of the URL path delimited by slashes.

• 网址路径：域后面的 URL 部分（由段组成）。

  ¥URL Path: Part of the URL that comes after the domain (composed of segments).

app 路由

¥The app Router

在版本 13 中，Next.js 引入了基于 React 服务器组件 构建的新 App Router，它支持共享布局、嵌套路由、加载状态、错误处理等。

¥In version 13, Next.js introduced a new App Router built on React Server Components, which supports shared layouts, nested routing, loading states, error handling, and more.

App Router 在名为 app 的新目录中工作。app 目录与 pages 目录一起工作，以允许增量采用。这允许你将应用的某些路由选择为新行为，同时将其他路由保留在 pages 目录中以实现以前的行为。如果你的应用使用 pages 目录，另请参阅 页面路由 文档。

¥The App Router works in a new directory named app. The app directory works alongside the pages directory to allow for incremental adoption. This allows you to opt some routes of your application into the new behavior while keeping other routes in the pages directory for previous behavior. If your application uses the pages directory, please also see the Pages Router documentation.

很高兴知道：App Router 的优先级高于 Pages Router。跨目录的路由不应解析为相同的 URL 路径，并且会导致构建时错误以防止冲突。

¥Good to know: The App Router takes priority over the Pages Router. Routes across directories should not resolve to the same URL path and will cause a build-time error to prevent a conflict.

默认情况下，app 内的组件是 React 服务器组件。这是一个性能优化，可以让你轻松采用它们，你也可以使用 客户端组件。

¥By default, components inside app are React Server Components. This is a performance optimization and allows you to easily adopt them, and you can also use Client Components.

推荐：如果你不熟悉服务器组件，请查看 服务器 页面。

¥Recommendation: Check out the Server page if you're new to Server Components.

文件夹和文件的角色

¥Roles of Folders and Files

Next.js 使用基于文件系统的路由，其中：

¥Next.js uses a file-system based router where:

• 文件夹用于定义路由。路由是嵌套文件夹的单个路径，遵循从根文件夹到包含 page.js 文件的最终叶文件夹的文件系统层次结构。参见 定义路由。

  ¥Folders are used to define routes. A route is a single path of nested folders, following the file-system hierarchy from the root folder down to a final leaf folder that includes a page.js file. See Defining Routes.

• 文件用于创建为路由段显示的 UI。参见 特殊文件。

  ¥Files are used to create UI that is shown for a route segment. See special files.

路由片段

¥Route Segments

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

¥Each folder in a route represents a route segment. Each route segment is mapped to a corresponding segment in a URL path.

嵌套路由

¥Nested Routes

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

¥To create a nested route, you can nest folders inside each other. For example, you can add a new /dashboard/settings route by nesting two new folders in the app directory.

/dashboard/settings 路由由三段组成：

¥The /dashboard/settings route is composed of three segments:

• /（根段）

  ¥/ (Root segment)

• dashboard（片段）

  ¥dashboard (Segment)

• settings（叶段）

  ¥settings (Leaf segment)

文件约定

¥File Conventions

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

¥Next.js provides a set of special files to create UI with specific behavior in nested routes:

layout	段及其子段的共享 UI
page	路由的独特 UI 并使路由可公开访问
loading	加载段及其子段的 UI
not-found	未找到段及其子段的 UI
error	段及其子段的错误 UI
global-error	全局错误用户界面
route	服务器端 API 端点
template	专门重新渲染布局 UI
default	并行路由 的后备 UI

很高兴知道：.js、.jsx 或 .tsx 文件扩展名可用于特殊文件。

¥Good to know: .js, .jsx, or .tsx file extensions can be used for special files.

组件层次结构

¥Component Hierarchy

路由段的特殊文件中定义的 React 组件以特定的层次结构渲染：

¥The React components defined in special files of a route segment are rendered in a specific hierarchy:

• layout.js

• template.js

• error.js（反应误差边界）

  ¥error.js (React error boundary)

• loading.js（反应悬念边界）

  ¥loading.js (React suspense boundary)

• not-found.js（反应误差边界）

  ¥not-found.js (React error boundary)

• page.js 或嵌套 layout.js

  ¥page.js or nested layout.js

在嵌套路由中，段的组件将嵌套在其父段的组件内。

¥In a nested route, the components of a segment will be nested inside the components of its parent segment.

主机托管

¥Colocation

除了特殊文件之外，你还可以选择将自己的文件（例如组件、样式、测试等）放置在 app 目录中的文件夹中。

¥In addition to special files, you have the option to colocate your own files (e.g. components, styles, tests, etc) inside folders in the app directory.

这是因为虽然文件夹定义了路由，但只有 page.js 或 route.js 返回的内容是可公开寻址的。

¥This is because while folders define routes, only the contents returned by page.js or route.js are publicly addressable.

了解有关 项目组织和托管 的更多信息。

¥Learn more about Project Organization and Colocation.

高级路由模式

¥Advanced Routing Patterns

App Router 还提供了一组约定来帮助你实现更高级的路由模式。这些包括：

¥The App Router also provides a set of conventions to help you implement more advanced routing patterns. These include:

• 并行路由：允许你在同一视图中同时显示两个或多个可以独立导航的页面。你可以将它们用于具有自己的子导航的分割视图。例如。仪表板。

  ¥Parallel Routes: Allow you to simultaneously show two or more pages in the same view that can be navigated independently. You can use them for split views that have their own sub-navigation. E.g. Dashboards.

• 拦截路由：允许你拦截一条路由并将其显示在另一条路由的上下文中。当保留当前页面的上下文很重要时，你可以使用它们。例如。在编辑一个任务或展开摘要中的一张照片时查看所有任务。

  ¥Intercepting Routes: Allow you to intercept a route and show it in the context of another route. You can use these when keeping the context for the current page is important. E.g. Seeing all tasks while editing one task or expanding a photo in a feed.

这些模式使你能够构建更丰富、更复杂的 UI，从而实现小型团队和个人开发者过去难以实现的功能的民主化。

¥These patterns allow you to build richer and more complex UIs, democratizing features that were historically complex for small teams and individual developers to implement.

下一步

¥Next Steps

现在你已经了解了 Next.js 中路由的基础知识，请按照以下链接创建你的第一个路由：

¥Now that you understand the fundamentals of routing in Next.js, follow the links below to create your first routes: