项目组织与文件共置

除了路由文件夹与文件约定,Next.js 对项目文件组织和共置方式不做强制约束

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

默认安全共置

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

每个文件夹对应 URL 路径中的一个路由段 (route segment)。

但需注意,即使路由结构由文件夹定义,只有当一个路由段中添加了 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 根目录,并将特定功能的应用代码拆分到使用它们的路由段中。

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

On this page