项目结构和组织

此页面概述了 Next.js 中的文件夹和文件约定，以及组织项目的提示。

¥This page provides an overview of the folder and file conventions in Next.js, as well as tips for organizing your project.

文件夹和文件约定

¥Folder and file conventions

顶层文件夹

¥Top-level folders

顶层文件夹用于组织应用的代码和静态资源。

¥Top-level folders are used to organize your application's code and static assets.

app	应用路由
pages	页面路由
public	要提供的静态资源
src	可选的应用源文件夹

顶层文件

¥Top-level files

顶层文件用于配置应用、管理依赖、运行中间件、集成监视工具以及定义环境变量。

¥Top-level files are used to configure your application, manage dependencies, run middleware, integrate monitoring tools, and define environment variables.

Next.js
next.config.js	Next.js 的配置文件
package.json	项目依赖和脚本
instrumentation.ts	OpenTelemetry 和 Instrumentation 文件
middleware.ts	Next.js 请求中间件
.env	环境变量
.env.local	本地环境变量
.env.production	生产环境变量
.env.development	开发环境变量
.eslintrc.json	ESLint 的配置文件
.gitignore	要忽略的 Git 文件和文件夹
next-env.d.ts	Next.js 的 TypeScript 声明文件
tsconfig.json	TypeScript 的配置文件
jsconfig.json	JavaScript 的配置文件

路由文件

¥Routing Files

layout	.js .jsx .tsx	布局
page	.js .jsx .tsx	页面
loading	.js .jsx .tsx	加载用户界面
not-found	.js .jsx .tsx	未找到用户界面
error	.js .jsx .tsx	错误用户界面
global-error	.js .jsx .tsx	全局错误用户界面
route	.js .ts	API 端点
template	.js .jsx .tsx	重新渲染布局
default	.js .jsx .tsx	并行路由后备页面

嵌套路由

¥Nested routes

folder	路由段
folder/folder	嵌套路由段

动态路由

¥Dynamic routes

[folder]	动态路段
[...folder]	包罗万象的路由段
[[...folder]]	可选的包罗万象的路由段

路由组和私有文件夹

¥Route Groups and private folders

(folder)	对路由进行分组而不影响路由
_folder	选择文件夹和所有子段不参与路由

并行和拦截的路由

¥Parallel and Intercepted Routes

@folder	命名槽
(.)folder	拦截同级
(..)folder	拦截上方一层
(..)(..)folder	拦截上面两层
(...)folder	从根拦截

元数据文件约定

¥Metadata file conventions

应用图标

¥App icons

favicon	.ico	网站图标文件
icon	.ico .jpg .jpeg .png .svg	应用图标文件
icon	.js .ts .tsx	生成的应用图标
apple-icon	.jpg .jpeg、.png	苹果应用图标文件
apple-icon	.js .ts .tsx	生成的苹果应用图标

Open Graph 和 Twitter 图片

¥Open Graph and Twitter images

opengraph-image	.jpg .jpeg .png .gif	打开图形图片文件
opengraph-image	.js .ts .tsx	生成的 Open Graph 图片
twitter-image	.jpg .jpeg .png .gif	推特图片文件
twitter-image	.js .ts .tsx	生成的 Twitter 图片

SEO

sitemap	.xml	站点地图文件
sitemap	.js .ts	生成的站点地图
robots	.txt	机器人文件
robots	.js .ts	生成的机器人文件

组件层次结构

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

组织你的项目

¥Organizing your project

除了 文件夹和文件约定 之外，Next.js 对于如何组织和放置项目文件没有任何意见。但它确实提供了一些功能来帮助你组织项目。

¥Apart from folder and file conventions, Next.js is unopinionated about how you organize and colocate your project files. But it does provide several features to help you organize your project.

主机托管

¥Colocation

在 app 目录中，嵌套文件夹定义路由结构。每个文件夹代表一个路由段，该路由段映射到 URL 路径中的相应段。

¥In the app directory, nested folders define route structure. Each folder represents a route segment that is mapped to a corresponding segment in a URL path.

但是，即使路由结构是通过文件夹定义的，在将 page.js 或 route.js 文件添加到路由段之前，路由也无法公开访问。

¥However, even though route structure is defined through folders, a route is not publicly accessible until a page.js or route.js file is added to a route segment.

而且，即使路由可公开访问，也只有 page.js 或 route.js 返回的内容会发送到客户端。

¥And, even when a route is made publicly accessible, only the content returned by page.js or route.js is sent to the client.

这意味着项目文件可以安全地共存于 app 目录中的路由段内，而不会意外地被路由。

¥This means that project files can be safely colocated inside route segments in the app directory without accidentally being routable.

很高兴知道：

¥Good to know:

• 虽然你可以将项目文件放在 app 中，但你不必这样做。如果你愿意，你可以 将它们保留在 app 目录之外。

  ¥While you can colocate your project files in app you don't have to. If you prefer, you can keep them outside the app directory.

私有文件夹

¥Private folders

可以通过在文件夹前添加下划线来创建私有文件夹：_folderName

¥Private folders can be created by prefixing a folder with an underscore: _folderName

这表明该文件夹是私有实现细节，路由系统不应考虑该文件夹，从而选择该文件夹及其所有子文件夹不进行路由。

¥This indicates the folder is a private implementation detail and should not be considered by the routing system, thereby opting the folder and all its subfolders out of routing.

由于 app 目录中的文件可以是 默认情况下安全地共置，因此共置不需要私有文件夹。然而，它们可用于：

¥Since files in the app directory can be safely colocated by default, private folders are not required for colocation. However, they can be useful for:

• 将 UI 逻辑与路由逻辑分离。

  ¥Separating UI logic from routing logic.

• 跨项目和 Next.js 生态系统一致地组织内部文件。

  ¥Consistently organizing internal files across a project and the Next.js ecosystem.

• 在代码编辑器中对文件进行排序和分组。

  ¥Sorting and grouping files in code editors.

• 避免与未来的 Next.js 文件约定发生潜在的命名冲突。

  ¥Avoiding potential naming conflicts with future Next.js file conventions.

很高兴知道：

¥Good to know:

• 虽然不是框架约定，但你也可以考虑使用相同的下划线模式将私有文件夹外部的文件标记为 "private"。

  ¥While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern.

• 你可以通过在文件夹名称前添加 %5F（下划线的 URL 编码形式）作为前缀来创建以下划线开头的 URL 段：%5FfolderName。

  ¥You can create URL segments that start with an underscore by prefixing the folder name with %5F (the URL-encoded form of an underscore): %5FfolderName.

• 如果你不使用私有文件夹，那么了解 Next.js 特殊文件约定 会很有帮助，以防止意外的命名冲突。

  ¥If you don't use private folders, it would be helpful to know Next.js special file conventions to prevent unexpected naming conflicts.

路由组

¥Route groups

可以通过将文件夹括在括号中来创建路由组：(folderName)

¥Route groups can be created by wrapping a folder in parenthesis: (folderName)

这表明该文件夹用于组织目的，不应包含在路由的 URL 路径中。

¥This indicates the folder is for organizational purposes and should not be included in the route's URL path.

路由组可用于：

¥Route groups are useful for:

• 将路由分组 例如 按站点部分、意图或团队。

  ¥Organizing routes into groups e.g. by site section, intent, or team.

• 在同一路由段级别中启用嵌套布局：

  ¥Enabling nested layouts in the same route segment level:

  • 在同一段中创建多个嵌套布局，包括多个根布局

    ¥Creating multiple nested layouts in the same segment, including multiple root layouts

  • 将布局添加到公共路段中的路由子集

    ¥Adding a layout to a subset of routes in a common segment

src 目录

¥src directory

Next.js 支持将应用代码（包括 app）存储在可选的 src 目录 内。这将应用代码与项目配置文件分开，项目配置文件主要位于项目的根目录中。

¥Next.js supports storing application code (including app) inside an optional src directory. This separates application code from project configuration files which mostly live in the root of a project.

常用策略

¥Common strategies

以下部分列出了常见策略的高度概述。最简单的要点是选择一种适合你和你的团队的策略，并在整个项目中保持一致。

¥The following section lists a very high-level overview of common strategies. The simplest takeaway is to choose a strategy that works for you and your team and be consistent across the project.

很高兴知道：在下面的示例中，我们使用 components 和 lib 文件夹作为通用占位符，它们的命名没有特殊的框架意义，你的项目可能会使用其他文件夹，如 ui、utils、hooks、styles 等。

¥Good to know: In our examples below, we're using components and lib folders as generalized placeholders, their naming has no special framework significance and your projects might use other folders like ui, utils, hooks, styles, etc.

将项目文件存储在 app 之外

¥Store project files outside of app

此策略将所有应用代码存储在项目根目录的共享文件夹中，并保留 app 目录纯粹用于路由目的。

¥This strategy stores all application code in shared folders in the root of your project and keeps the app directory purely for routing purposes.

将项目文件存储在 app 内的顶层文件夹中

¥Store project files in top-level folders inside of app

此策略将所有应用代码存储在 app 目录根目录的共享文件夹中。

¥This strategy stores all application code in shared folders in the root of the app directory.

按功能或路由拆分项目文件

¥Split project files by feature or route

该策略将全局共享的应用代码存储在根 app 目录中，并将更具体的应用代码拆分到使用它们的路由段中。

¥This strategy stores globally shared application code in the root app directory and splits more specific application code into the route segments that use them.