项目结构与组织

本页概述了 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`	404 页面
`error`	`.js` `.jsx` `.tsx`	错误边界 UI
`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`	`.js` `.ts`	代码生成的爬虫协议

项目组织方式

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 目录外。

私有文件夹 (Private Folders)

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

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

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

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

须知：

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

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

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