Routing Fundamentals

路由基础知识

Fundamentals: 基础知识

Terminology

术语

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

首先，你会在整个文档中看到这些术语。下面是一个快速参考：

throughout: 从头到尾

• 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.

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

convention: 公约

visualizing: 可视化的

hierarchical：分层的

• URL Segment: Part of the URL path delimited by slashes.
• URL Path: Part of the URL that comes after the domain (composed of segments).

composed of: 由…组成

The 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.

在第 13 版中，Next.js 引入了基于 React Server Components 的全新 App Router，它支持共享布局、嵌套路由、加载状态、错误处理等功能。

The App Router works in a new directory named app. The app directory works alongside the pages directory to allow for incremental adoption.

App 路由器在一个名为 app 的新目录中工作。app 目录与 pages 目录一起工作，以支持渐进性采用。

alongside: 与此同时

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.

这允许您将应用程序的某些路由选择性地采用新行为，同时保留 pages 目录中的其他路由以维持以前的行为。如果您的应用程序使用 pages 目录，请同时查看页面路由器文档。

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 路由器优先于页面路由器。跨目录的路由不应该解析到相同的 URL 路径，否则会在构建时出现错误以防止冲突。

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.

默认情况下，app 内的组件是 React Server Components。这是一种性能优化，使您能够轻松采用它们，并且你也可以使用 Client Components。

adopt: 采用

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

**建议：**如果您对服务器组件不熟悉，可以查看 Server 页面。

Roles of Folders and Files

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

• 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.
• Files are used to create UI that is shown for a route segment. See special files.

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

• 文件夹用于定义路由。路由是嵌套文件夹的单一路径，按照文件系统的层次结构，从根文件夹向下延伸至包含 page.js 文件的最终叶文件夹。请参见 定义路由。
• 文件 用于创建在路由段上显示的 UI。请参见 特殊文件。

Route Segments

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

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

represents：代表

corresponding: 相应的

Nested Routes

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.

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

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

• / (Root segment)
• dashboard (Segment)
• settings (Leaf segment)

该 /dashboard/settings 路由由三个段组成：。。。

File Conventions

文件公约

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

Next.js 提供了一组特殊文件，用于在嵌套路由中创建具有特定行为的用户界面：

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

Component Hierarchy

组件层次结构

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

在路由段的特殊文件中定义的 React 组件会以特定的层次结构呈现：

• layout.js
• template.js
• error.js (React error boundary)
• loading.js (React suspense boundary)
• not-found.js (React error boundary)
• 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

文件存放

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.

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

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

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

Learn more about Project Organization and Colocation.

Advanced Routing Patterns

高级路由模式

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.

  拦截路由：允许您截取一条路由，并在另一条路由的上下文中显示它。当保持当前页面的上下文非常重要时，就可以使用这些功能。例如，在编辑一项任务时查看所有任务，或在 feed 中展开一张照片。

simultaneously： 同时

independently： 独立的

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.

通过这些模式，您可以构建更丰富、更复杂的用户界面，并将以往由小型团队和个人开发人员实施的复杂功能平民化。

richer：更丰富

democratizing： 民主化

historically： 历史上