项目结构和组织

此页面概述了 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 文件

组件层级结构

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

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

组织你的项目

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

共置 (Colocation)

在 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 文件约定发生潜在的命名冲突。

须知:

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

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

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