项目组织与文件共置

除了路由文件夹和文件约定外，Next.js 对项目文件的组织和共置方式不做强制要求。

本页将介绍默认行为以及可用于组织项目的功能特性。

• 默认的安全共置
• 项目组织功能
• 项目组织策略

默认的安全共置

在 app 目录中，嵌套文件夹层级定义了路由结构。

每个文件夹代表一个路由段，映射到 URL 路径中的对应段。

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

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

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

须知:

• 这与 pages 目录不同，pages 中的任何文件都被视为路由。
• 虽然你可以在 app 中共置项目文件，但并非必须。如果愿意，你可以将项目文件保留在 app 目录外。

项目组织功能

Next.js 提供了多种功能来帮助组织项目。

私有文件夹

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

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

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

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

须知

• 虽然不是框架约定，你也可以考虑使用相同的下划线模式将私有文件夹外的文件标记为“私有”。
• 可以通过在文件夹名前添加 %5F（下划线的 URL 编码形式）来创建以下划线开头的 URL 段：%5FfolderName。
• 如果不使用私有文件夹，了解 Next.js 的特殊文件约定有助于避免意外的命名冲突。

路由组

通过在文件夹名外加括号可以创建路由组：(folderName)

这表示该文件夹仅用于组织目的，不应包含在路由的 URL 路径中。

路由组可用于：

• 将路由分组组织，例如按网站部分、意图或团队。
• 在同一路由段级别启用嵌套布局：
  • 在同一段中创建多个嵌套布局，包括多个根布局
  • 将布局添加到公共段中的路由子集

src 目录

Next.js 支持将应用代码（包括 app）存储在可选的 src 目录中。这将应用代码与主要位于项目根目录的配置文件分离。

模块路径别名

Next.js 支持模块路径别名，使深度嵌套的项目文件中的导入更易于阅读和维护。

// 之前
import { Button } from '../../../components/button'

// 之后
import { Button } from '@/components/button'

项目组织策略

在 Next.js 项目中组织和共置文件没有“正确”或“错误”的方式。

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

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

将项目文件存储在 app 外

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

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

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

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

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