项目结构和组织

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

文件夹和文件约定

顶级文件夹

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


`app`	App 路由
`pages`	Pages 路由
`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`	加载界面
`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`	并行路由回退页面

嵌套路由


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

动态路由


`[folder]`	动态路由段
`[...folder]`	捕获所有路由段
`[[...folder]]`	可选捕获所有路由段

路由组和私有文件夹


`(folder)`	在不影响路由的情况下对路由进行分组
`_folder`	将文件夹和所有子段从路由中排除

并行和拦截路由


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

元数据文件约定

应用图标


`favicon`	`.ico`	网站图标文件
`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 文件

pages文件约定


`_app`	`.js` `.jsx` `.tsx`	自定义应用
`_document`	`.js` `.jsx` `.tsx`	自定义文档
`_error`	`.js` `.jsx` `.tsx`	自定义错误页面
`404`	`.js` `.jsx` `.tsx`	404 错误页面
`500`	`.js` `.jsx` `.tsx`	500 错误页面

路由


文件夹约定
`index`	`.js` `.jsx` `.tsx`	首页
`folder/index`	`.js` `.jsx` `.tsx`	嵌套页面
文件约定
`index`	`.js` `.jsx` `.tsx`	首页
`file`	`.js` `.jsx` `.tsx`	嵌套页面

动态路由


文件夹约定
`[folder]/index`	`.js` `.jsx` `.tsx`	动态路由段
`[...folder]/index`	`.js` `.jsx` `.tsx`	捕获所有路由段
`[[...folder]]/index`	`.js` `.jsx` `.tsx`	可选捕获所有路由段
文件约定
`[file]`	`.js` `.jsx` `.tsx`	动态路由段
`[...file]`	`.js` `.jsx` `.tsx`	捕获所有路由段
`[[...file]]`	`.js` `.jsx` `.tsx`	可选捕获所有路由段

组织你的项目

Next.js 对于如何组织和并置项目文件是无意见的。但它确实提供了几个功能来帮助你组织项目。

组件层次结构

在特殊文件中定义的组件按特定层次结构渲染：

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

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

并置（Colocation）

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

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

显示在向路由段添加 page.js 或 route.js 文件之前路由不可公开访问的图表。

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

这意味着项目文件可以安全地并置在 app 目录的路由段内，而不会意外地变为可路由的。

显示即使段包含 page.js 或 route.js 文件，并置的项目文件也不可路由的图表。

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

私有文件夹

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

这表示该文件夹是私有实现细节，不应被路由系统考虑，从而将文件夹及其所有子文件夹从路由中排除。

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

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

提示:

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

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

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