Project Organization and File Colocation 项目组织和文件并置

Apart from routing folder and file conventions, Next.js is unopinionated about how you organize and colocate your project files.

除了路由文件夹和文件约定之外,Next.js 不会对您如何组织和并置项目文件发表意见。

This page shares default behavior and features you can use to organize your project.

此页面共享您可以用来组织项目的默认行为和功能。

1.Safe colocation by default 默认安全共置

In the app directory, nested folder hierarchy defines route structure.

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

However, even though route structure is defined through folders, a route is not publicly accessible until a page.js or route.js file is added to a route segment.

但是,即使通过文件夹定义了路由结构,在向路由段添加 page.js 或 route.js 文件之前,路由仍无法公开访问。

And, even when a route is made publicly accessible, only the content returned by page.js or route.js is sent to the client.

而且,即使某个路由被公开访问,也只有 page.js 或 route.js 返回的内容才会被发送给客户端。

This means that project files can be safely colocated inside route segments in the app directory without accidentally being routable.

这意味着项目文件可以安全地与 app 目录中的路由段一起放置,而不会被意外路由。

ps: 在app系统级目录中页面的展示方式

Good to know: 值得了解:

  • This is different from the pages directory, where any file in pages is considered a route.
    这与 pages 目录不同,其中 pages 中的任何文件都被视为路由。

  • While you can colocate your project files in app you don't have to. If you prefer, you can keep them outside the app directory.
    虽然您可以将项目文件放在 app 中,但您不必这样做。如果您愿意,可以将它们保留在 app 目录之外。

2.Project organization features 项目组织功能

a.Private Folders 私有文件夹

Private folders can be created by prefixing a folder with an underscore: _folderName

可以通过在文件夹前加上下划线来创建私有文件夹: _folderName

This indicates the folder is a private implementation detail and should not be considered by the routing system, thereby opting the folder and all its subfolders out of routing.

这表示该文件夹是私有实现细节,路由系统不应考虑它,从而使该文件夹及其所有子文件夹不参与路由。

Since files in the app directory can be safely colocated by default, private folders are not required for colocation. However, they can be useful for:

由于 app 目录中的文件默认情况下可以安全地进行同置,因此同置不需要私有文件夹。但是,它们对于以下情况很有用:

-Separating UI logic from routing logic.

将 UI 逻辑与路由逻辑分开。

-Consistently organizing internal files across a project and the Next.js ecosystem.

在项目和 Next.js 生态系统中一致地组织内部文件。

-Sorting and grouping files in code editors.

在代码编辑器中对文件进行排序和分组。

-Avoiding potential naming conflicts with future Next.js file conventions.

避免与未来的 Next.js 文件约定产生潜在的命名冲突。

Good to know 需要了解的知识

  • While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern.
    虽然这不是框架约定,但您也可以考虑使用相同的下划线模式将私有文件夹之外的文件标记为“私有”。

  • You can create URL segments that start with an underscore by prefixing the folder name with %5F (the URL-encoded form of an underscore): %5FfolderName.
    您可以通过在文件夹名前加上 %5F (下划线的 URL 编码形式)来创建以下划线开头的 URL 片段: %5FfolderName

  • If you don't use private folders, it would be helpful to know Next.js special file conventions to prevent unexpected naming conflicts.
    如果您不使用私有文件夹,了解 Next.js 特殊文件约定将有助于防止意外的命名冲突。

b.Route Groups 路由组

Route groups can be created by wrapping a folder in parenthesis: (folderName)

可以通过用括号括起文件夹来创建路由组: (folderName)

This indicates the folder is for organizational purposes and should not be included in the route's URL path.

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

Route groups are useful for:

路由组对于以下情况很有用:

c.src Directory src 目录

Next.js supports storing application code (including app) inside an optional src directory. This separates application code from project configuration files which mostly live in the root of a project.

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

d.Module Path Aliases 模块路径别名

Next.js supports Module Path Aliases which make it easier to read and maintain imports across deeply nested project files.

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

// before
import { Button } from '../../../components/button'
 
// after
import { Button } from '@/components/button'

3.Project organization strategies 项目组织策略

There is no "right" or "wrong" way when it comes to organizing your own files and folders in a Next.js project.

在 Next.js 项目中整理自己的文件和文件夹时,没有“正确”或“错误”的方式。

The following section lists a very high-level overview of common strategies. The simplest takeaway is to choose a strategy that works for you and your team and be consistent across the project.

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

Good to know: In our examples below, we're using components and lib folders as generalized placeholders, their naming has no special framework significance and your projects might use other folders like ui, utils, hooks, styles, etc.

需要了解的是:在下面的示例中,我们使用 components 和 lib 文件夹作为通用的占位符,它们的命名没有任何特殊的框架意义,您的项目可能会使用其他文件夹,如 ui 、 utils 、 hooks 、 styles 等。

a.Store project files outside of app 将项目文件存储在 app 之外

This strategy stores all application code in shared folders in the root of your project and keeps the app directory purely for routing purposes.

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

b.Store project files in top-level folders inside of app 将项目文件存储在 app 内的顶级文件夹中

This strategy stores all application code in shared folders in the root of the app directory.

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

ps: 官方的目录构建方式推荐还是很随意的

c.Split project files by feature or route 按功能或路由拆分项目文件

This strategy stores globally shared application code in the root app directory and splits more specific application code into the route segments that use them.

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