项目结构与组织

本页全面介绍了 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 的特殊文件约定有助于避免意外的命名冲突。