Menu

项目组织和文件并置

注:本文中的“并置”(colocation)指的是将相关的文件或代码放在一起的做法,旨在提高代码的组织性和可维护性。

除了路由文件夹和文件约定之外,Next.js 对于你如何组织和并置项目文件没有固定看法

本页介绍了默认行为和可用于组织项目的功能。

默认安全并置

app 目录中,嵌套文件夹层次结构定义了路由结构。

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

然而,尽管路由结构是通过文件夹定义的,但在将 page.jsroute.js 文件添加到路由段之前,路由是不可公开访问的

一张图表,展示在将 page.js 或 route.js 文件添加到路由段之前,路由不可公开访问的。

而且,即使路由变为可公开访问,也只有 page.jsroute.js 返回的内容会发送给客户端。

一张图表,展示 page.js 和 route.js 文件如何使路由公开可访问。

这意味着项目文件可以在 app 目录的路由段内安全并置,而不会意外地变得可路由。

一张图表,展示即使段包含 page.js 或 route.js 文件,并置的项目文件也不可路由。

值得注意的是

  • 这与 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 目录中。这将应用程序代码与主要存在于项目根目录的项目配置文件分开。

使用 `src` 目录的示例文件夹结构

模块路径别名

Next.js 支持模块路径别名,这使得在深层嵌套的项目文件之间更容易读取和维护导入。

app/dashboard/settings/analytics/page.js
// 修改前
import { Button } from "../../../components/button";
 
// 修改后
import { Button } from "@/components/button";

项目组织策略

在 Next.js 项目中组织你自己的文件和文件夹时,没有“对”或“错”的方式。

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

值得注意的是:在我们下面的示例中,我们使用 componentslib 文件夹作为通用占位符,它们的命名在框架中没有特殊意义,你的项目可能使用其他文件夹,如 uiutilshooksstyles 等。

将项目文件存储在 app 之外

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

项目文件位于 app 之外的示例文件夹结构

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

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

项目文件位于 app 内的示例文件夹结构

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

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

按功能或路由拆分项目文件的示例文件夹结构