项目结构和组织

本页概述了 Next.js 中所有文件夹和文件约定，并提供了组织项目的建议。

文件夹和文件约定

顶层文件夹

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


`app`	App Router
`pages`	Pages Router
`public`	要服务的静态资源
`src`	可选的应用程序源代码文件夹

顶层文件

顶层文件用于配置应用程序、管理依赖项、运行中间件、集成监控工具和定义环境变量。


Next.js
`next.config.js`	Next.js 的配置文件
`package.json`	项目依赖项和脚本
`instrumentation.ts`	OpenTelemetry 和检测文件
`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 的配置文件

路由文件


`layout`	`.js` `.jsx` `.tsx`	布局
`page`	`.js` `.jsx` `.tsx`	页面
`loading`	`.js` `.jsx` `.tsx`	加载 UI
`not-found`	`.js` `.jsx` `.tsx`	未找到 UI
`error`	`.js` `.jsx` `.tsx`	错误 UI
`global-error`	`.js` `.jsx` `.tsx`	全局错误 UI
`route`	`.js` `.ts`	API 端点
`template`	`.js` `.jsx` `.tsx`	重新渲染的布局
`default`	`.js` `.jsx` `.tsx`	并行路由回退页面

嵌套路由


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

动态路由


`[folder]`	动态路由段
`[...folder]`	全部捕获路由段
`[[...folder]]`	可选的全部捕获路由段

路由组和私有文件夹


`(folder)`	分组路由而不影响路由
`_folder`	选择文件夹及其所有子段退出路由

并行和拦截路由


`@folder`	命名槽
`(.)folder`	拦截同一级别
`(..)folder`	拦截上一级别
`(..)(..)folder`	拦截上两级别
`(...)folder`	从根拦截

元数据文件约定

应用图标


`favicon`	`.ico`	Favicon 文件
`icon`	`.ico` `.jpg` `.jpeg` `.png` `.svg`	应用图标文件
`icon`	`.js` `.ts` `.tsx`	生成的应用图标
`apple-icon`	`.jpg` `.jpeg`, `.png`	Apple 应用图标文件
`apple-icon`	`.js` `.ts` `.tsx`	生成的 Apple 应用图标

Open Graph 和 Twitter 图像


`opengraph-image`	`.jpg` `.jpeg` `.png` `.gif`	Open Graph 图像文件
`opengraph-image`	`.js` `.ts` `.tsx`	生成的 Open Graph 图像
`twitter-image`	`.jpg` `.jpeg` `.png` `.gif`	Twitter 图像文件
`twitter-image`	`.js` `.ts` `.tsx`	生成的 Twitter 图像

SEO


`sitemap`	`.xml`	站点地图文件
`sitemap`	`.js` `.ts`	生成的站点地图
`robots`	`.txt`	Robots 文件
`robots`	`.js` `.ts`	生成的 Robots 文件

组织你的项目

对于如何组织和同地协作项目文件，Next.js 是不带主观意见的。但它确实提供了一些功能来帮助你组织项目。

组件层级

在特殊文件中定义的组件以特定层级结构渲染

layout.js
template.js
error.js (React 错误边界)
loading.js (React Suspense 边界)
not-found.js (React 错误边界)
page.js 或嵌套 layout.js

Component Hierarchy for File Conventions

组件在嵌套路由中递归渲染，这意味着路由段的组件将嵌套在其父段的组件内部。

Nested File Conventions Component Hierarchy

同地协作

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

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

A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment.

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

A diagram showing how page.js and route.js files make routes publicly accessible.

这意味着项目文件可以安全地同地协作在 app 目录中的路由段内，而不会意外地成为可路由的。

A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file.

须知：虽然你可以在 app 中同地协作项目文件，但你不必这样做。如果你愿意，你可以将它们放在 app 目录之外。

私有文件夹

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

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

An example folder structure using private folders

由于 app 目录中的文件默认可以安全地同地协作，因此同地协作不需要私有文件夹。但是，它们对于以下情况可能很有用：

将 UI 逻辑与路由逻辑分离。
在整个项目和 Next.js 生态系统中一致地组织内部文件。
在代码编辑器中排序和分组文件。
避免与未来 Next.js 文件约定发生潜在的命名冲突。

须知:

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

你可以创建以下划线开头的 URL 段，方法是在文件夹名称前加上 %5F (下划线的 URL 编码形式)：%5FfolderName。

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