项目结构和组织

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

文件夹和文件约定

顶级文件夹

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

顶级文件

顶级文件用于配置应用程序、管理依赖项、运行中间件、集成监控工具和定义环境变量。

路由文件

嵌套路由

动态路由

路由组和私有文件夹

并行和拦截路由

元数据文件约定

应用图标

Open Graph 和 Twitter 图片

SEO

组件层次结构

路由段中特殊文件定义的 React 组件按特定层次结构渲染：

• layout.js
• template.js
• error.js（React 错误边界）
• loading.js（React suspense 边界）
• not-found.js（React 错误边界）
• page.js 或嵌套 layout.js

在嵌套路由中，一个段的组件将被嵌套在其父段的组件内部。

组织你的项目

除了文件夹和文件约定外，Next.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 支持在可选的 src 目录中存储应用程序代码（包括 app）。这将应用程序代码与主要位于项目根目录的项目配置文件分开。

常见策略

以下部分列出了常见策略的非常高级概述。最简单的要点是选择适合你和你的团队的策略，并在整个项目中保持一致。

值得注意的是：在我们下面的示例中，我们使用 components 和 lib 文件夹作为通用占位符，它们的命名没有特殊的框架意义，你的项目可能使用其他文件夹，如 ui、utils、hooks、styles 等。

将项目文件存储在 app 之外

此策略将所有应用程序代码存储在项目根目录的共享文件夹中，并将 app 目录纯粹用于路由目的。

将项目文件存储在 app 内的顶级文件夹中

此策略将所有应用程序代码存储在 app 目录的根目录中的共享文件夹中。

按功能或路由拆分项目文件

此策略将全局共享的应用程序代码存储在根 app 目录中，并将更具体的应用程序代码拆分到使用它们的路由段中。