项目组织与文件共置
除了路由文件夹与文件约定,Next.js 对项目文件组织和共置方式不做强制约束。
本文介绍默认行为及可用于项目组织的功能特性。
默认安全共置
在 app
目录中,嵌套文件夹层级定义了路由结构。
每个文件夹对应 URL 路径中的一个路由段 (route segment)。
但需注意,即使路由结构由文件夹定义,只有当一个路由段中添加了 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 支持模块路径别名,简化深层嵌套项目文件中的导入维护。
项目组织策略
Next.js 项目中没有绝对"正确"或"错误"的文件组织方式。
以下部分列举了常见策略的高阶概述。核心原则是选择适合您和团队的策略,并保持项目内的一致性。
须知:下文示例中使用的
components
和lib
文件夹是通用占位名称,它们没有特殊框架含义,您的项目可使用其他文件夹如ui
、utils
、hooks
、styles
等。
将项目文件存储在 app
外
此策略将所有应用代码存放在项目根目录的共享文件夹中,保持 app
目录纯粹用于路由。

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

按功能或路由拆分项目文件
此策略将全局共享的应用代码存放在 app
根目录,并将特定功能的应用代码拆分到使用它们的路由段中。
