Skip to main content

项目组织和文件托管

除了 路由文件夹和文件约定 之外，Next.js 对于如何组织和放置项目文件没有任何意见。

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

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

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

默认情况下安全托管​

¥Safe colocation by default

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

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

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

¥Each folder represents a route segment that is mapped to a corresponding segment in a URL path.

但是，即使路由结构是通过文件夹定义的，在将 page.js 或 route.js 文件添加到路由段之前，路由也无法公开访问。

¥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.

这意味着项目文件可以安全地共存于 app 目录中的路由段内，而不会意外地被路由。

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

很高兴知道：

¥Good to know:

  • 这与 pages 目录不同，pages 中的任何文件都被视为路由。

    ¥This is different from the pages directory, where any file in pages is considered a route.

  • 虽然你可以将项目文件放在 app 中，但你不必这样做。如果你愿意，你可以 将它们保留在 app 目录之外。

    ¥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.

项目组织特点​

¥Project organization features

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

¥Next.js provides several features to help you organize your project.

私有文件夹​

¥Private Folders

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

¥Private folders can be created by prefixing a folder with an underscore: _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.

由于 app 目录中的文件可以是 默认情况下安全地共置，因此共置不需要私有文件夹。然而，它们可用于：

¥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:

  • 将 UI 逻辑与路由逻辑分离。

    ¥Separating UI logic from routing logic.

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

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

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

    ¥Sorting and grouping files in code editors.

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

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

很高兴知道

¥Good to know

  • 虽然不是框架约定，但你也可以考虑使用相同的下划线模式将私有文件夹外部的文件标记为 "private"。

    ¥While not a framework convention, you might also consider marking files outside private folders as "private" using the same underscore pattern.

  • 你可以通过在文件夹名称前添加 %5F（下划线的 URL 编码形式）作为前缀来创建以下划线开头的 URL 段：%5FfolderName。

    ¥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.

  • 如果你不使用私有文件夹，那么了解 Next.js 特殊文件约定 会很有帮助，以防止意外的命名冲突。

    ¥If you don't use private folders, it would be helpful to know Next.js special file conventions to prevent unexpected naming conflicts.

路由组​

¥Route Groups

可以通过将文件夹括在括号中来创建路由组：(folderName)

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

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

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

路由组可用于：

¥Route groups are useful for:

src 目录​

¥src Directory

Next.js 支持将应用代码（包括 app）存储在可选的 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.

模块路径别名​

¥Module Path Aliases

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

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

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

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

项目组织策略​

¥Project organization strategies

在 Next.js 项目中组织自己的文件和文件夹时，不存在 "right" 或 "wrong" 方式。

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

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

¥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.

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

¥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.

将项目文件存储在 app 之外​

¥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 内的顶层文件夹中​

¥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.

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

¥Split project files by feature or route

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

¥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.