项目结构和组织
本页面提供了 Next.js 中所有文件夹和文件约定的概述，以及组织项目的建议。
文件夹和文件约定
顶级文件夹
顶级文件夹用于组织应用程序代码和静态资产。
顶级文件
顶级文件用于配置应用程序、管理依赖项、运行中间件、集成监控工具和定义环境变量。
| 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 | 从根目录拦截 |
元数据文件约定
应用图标
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
组织你的项目
Next.js 对于如何组织和放置项目文件不持强制性意见。但它确实提供了几个功能来帮助你组织项目。
组件层次结构
特殊文件中定义的组件按特定层次结构渲染：
layout.jstemplate.jserror.js（React 错误边界）loading.js（React suspense 边界）not-found.js（React 错误边界）page.js或嵌套的layout.js
组件在嵌套路由中递归渲染，这意味着路由段的组件将嵌套在其父段组件内部。
共置
在 app 目录中，嵌套文件夹定义路由结构。每个文件夹代表一个路由段，映射到 URL 路径中的对应段。
然而，尽管路由结构是通过文件夹定义的，但在向路由段添加 page.js 或 route.js 文件之前，路由不可公开访问。
而且，即使路由已公开访问，只有 page.js 或 route.js 返回的内容才会发送到客户端。
这意味着项目文件可以安全地共置在 app 目录中的路由段内，而不会意外变成可路由的。
值得注意的是：虽然你可以在
app中共置项目文件，但你不必须这样做。如果你愿意，可以将它们存储在app目录之外。
私有文件夹
通过在文件夹名称前加下划线来创建私有文件夹：_folderName
这表示该文件夹是私有实现细节，不应被路由系统考虑，从而将该文件夹及其所有子文件夹排除在路由之外。
由于 app 目录中的文件默认可以安全共置，因此共置不需要私有文件夹。但它们对以下方面很有用：
- 将 UI 逻辑与路由逻辑分离。
- 在项目和 Next.js 生态系统中一致地组织内部文件。
- 在代码编辑器中对文件进行排序和分组。
- 避免与未来 Next.js 文件约定可能发生的命名冲突。
值得注意的是：
- 虽然这不是框架约定，但你可能还会考虑使用相同的下划线模式将私有文件夹外的文件标记为"私有"。
- 你可以通过在文件夹名称前加
%5F（下划线的 URL 编码形式）来创建以下划线开头的 URL 段：%5FfolderName。- 如果你不使用私有文件夹，了解 Next.js 特殊文件约定以防止意外命名冲突会很有帮助。
路由组
通过将文件夹名称用括号括起来可以创建路由组：(folderName)
这表示该文件夹仅用于组织目的，不应包含在路由的 URL 路径中。
路由组对以下方面很有用：
- 按网站部分、意图或团队组织路由。例如，营销页面、管理页面等。
- 在同一路由段级别启用嵌套布局：
src 目录
Next.js 支持将应用程序代码（包括 app）存储在可选的 src 目录中。这将应用程序代码与主要位于项目根目录的项目配置文件分开。
示例
以下部分列出了常见策略的非常高级概述。最简单的要点是选择适合你和你的团队的策略，并在整个项目中保持一致。
值得注意的是：在我们下面的示例中，我们使用
components和lib文件夹作为通用占位符，它们的命名对框架没有特殊意义，你的项目可能使用其他文件夹，如ui、utils、hooks、styles等。
将项目文件存储在 app 外
此策略将所有应用程序代码存储在项目根目录的共享文件夹中，并保持 app 目录纯粹用于路由目的。
将项目文件存储在 app 内的顶级文件夹中
此策略将所有应用程序代码存储在 app 目录根目录的共享文件夹中。
按功能或路由拆分项目文件
此策略将全局共享的应用程序代码存储在根 app 目录中，并将更具体的应用程序代码拆分到使用它们的路由段中。
组织路由而不影响 URL 路径
要在不影响 URL 的情况下组织路由，创建一个组将相关路由放在一起。括号中的文件夹将从 URL 中省略（例如 (marketing) 或 (shop)）。
尽管 (marketing) 和 (shop) 内的路由共享相同的 URL 层次结构，但你可以通过在它们的文件夹中添加 layout.js 文件为每个组创建不同的布局。
将特定段纳入布局
要将特定路由纳入布局，创建一个新的路由组（例如 (shop)）并将共享相同布局的路由移入该组（例如 account 和 cart）。组外的路由将不共享该布局（例如 checkout）。
在特定路由上选择加载骨架
要通过 loading.js 文件将加载骨架应用于特定路由，创建一个新的路由组（例如 /(overview)），然后将你的 loading.tsx 移入该路由组。
现在，loading.tsx 文件将只应用于你的仪表盘 → 概览页面，而不是所有仪表盘页面，同时不影响 URL 路径结构。
创建多个根布局
要创建多个根布局，移除顶级 layout.js 文件，并在每个路由组内添加 layout.js 文件。这对于将应用程序划分为具有完全不同 UI 或体验的部分很有用。<html> 和 <body> 标签需要添加到每个根布局中。
在上面的示例中，(marketing) 和 (shop) 都有自己的根布局。