Routing Fundamentals


Fundamentals: 基础知识



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


throughout: 从头到尾

Terminology for Component Tree

  • 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: 可视化的


Terminology for URL Anatomy

  • 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 路径,否则会在构建时出现错误以防止冲突。

Next.js App Directory

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 路径中的相应段。


corresponding: 相应的

How Route Segments Map to URL Segments

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 提供了一组特殊文件,用于在嵌套路由中创建具有特定行为的用户界面:

layout Shared UI for a segment and its children
page Unique UI of a route and make routes publicly accessible
loading Loading UI for a segment and its children
not-found Not found UI for a segment and its children
error Error UI for a segment and its children
global-error Global Error UI
route Server-side API endpoint
template Specialized re-rendered Layout UI
default Fallback UI for Parallel Routes

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

Component Hierarchy for File Conventions

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


Nested File Conventions Component Hierarchy



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.


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

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

An example folder structure with colocated files

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.



democratizing: 民主化

historically: 历史上