项目结构与组织
了解 Next.js 中的文件夹和文件约定,以及如何组织你的项目。
本页概述了 Next.js 中所有文件夹和文件约定,并给出了组织项目的建议。
文件夹和文件约定#
顶级文件夹#
顶级文件夹用于组织应用程序的代码和静态资源。
app | App Router |
pages | Pages Router |
public | 要提供的静态资源 |
src | 可选的应用程序源码文件夹 |
顶级文件#
顶级文件用于配置应用程序、管理依赖项、运行 proxy、集成监控工具以及定义环境变量。
| Next.js | |
next.config.js | Next.js 的配置文件 |
package.json | 项目依赖项和脚本 |
instrumentation.ts | OpenTelemetry 和 Instrumentation 文件 |
proxy.ts | Next.js 请求 proxy |
.env | 环境变量(不应被版本控制跟踪) |
.env.local | 本地环境变量(不应被版本控制跟踪) |
.env.production | 生产环境变量(不应被版本控制跟踪) |
.env.development | 开发环境变量(不应被版本控制跟踪) |
eslint.config.mjs | ESLint 的配置文件 |
.gitignore | 要忽略的 Git 文件和文件夹 |
next-env.d.ts | Next.js 的 TypeScript 声明文件(不应被版本控制跟踪) |
tsconfig.json | TypeScript 的配置文件 |
jsconfig.json | JavaScript 的配置文件 |
路由文件#
添加 page 以公开路由,添加 layout 用于共享 UI(如页头、导航或页脚),添加 loading 用于骨架屏,添加 error 用于错误边界,添加 route 用于 API。
layout | .js .jsx .tsx | 布局 |
page | .js .jsx .tsx | 页面 |
loading | .js .jsx .tsx | 加载 UI |
not-found | .js .jsx .tsx | 未找到 UI |
error | .js .jsx .tsx | 错误 UI |
global-error | .js .jsx .tsx | 全局错误 UI |
route | .js .ts | API 端点 |
template | .js .jsx .tsx | 重新渲染的布局 |
default | .js .jsx .tsx | 并行路由的回退页面 |
嵌套路由#
文件夹定义 URL 段。嵌套文件夹会嵌套段。任何层级的布局都会包裹其子段。当存在 page 或 route 文件时,路由即变为公开的。
| 路径 | URL 模式 | 说明 |
|---|---|---|
app/layout.tsx | — | 根布局包裹所有路由 |
app/blog/layout.tsx | — | 包裹 /blog 及其后代 |
app/page.tsx | / | 公开路由 |
app/blog/page.tsx | /blog | 公开路由 |
app/blog/authors/page.tsx | /blog/authors | 公开路由 |
动态路由#
使用方括号对段进行参数化。使用 [segment] 表示单个参数,使用 [...segment] 表示全捕获(catch-all),使用 [[...segment]] 表示可选全捕获。通过 params prop 访问值。
| 路径 | URL 模式 |
|---|---|
app/blog/[slug]/page.tsx | /blog/my-first-post |
app/shop/[...slug]/page.tsx | /shop/clothing, /shop/clothing/shirts |
app/docs/[[...slug]]/page.tsx | /docs, /docs/layouts-and-pages, /docs/api-reference/use-router |
路由组和私有文件夹#
使用路由组 (group) 在不改变 URL 的情况下组织代码,并使用私有文件夹 _folder 将不可路由的文件就近放置在一起。
| 路径 | URL 模式 | 说明 |
|---|---|---|
app/(marketing)/page.tsx | / | 组不会出现在 URL 中 |
app/(shop)/cart/page.tsx | /cart | 在 (shop) 内共享布局 |
app/blog/_components/Post.tsx | — | 不可路由;可安全存放 UI 工具代码 |
app/blog/_lib/data.ts | — | 不可路由;可安全存放工具函数 |
并行路由和拦截路由#
这些功能适用于特定的 UI 模式,例如基于插槽的布局或模态框路由。
使用 @slot 表示由父布局渲染的命名插槽。使用拦截模式在当前布局中渲染另一个路由而不改变 URL,例如将详情视图作为列表之上的模态框显示。
| 模式(文档) | 含义 | 典型用例 |
|---|---|---|
@folder | 命名插槽 | 侧边栏 + 主内容 |
(.)folder | 拦截同级 | 在模态框中预览同级路由 |
(..)folder | 拦截父级 | 将父级的子路由作为覆盖层打开 |
(..)(..)folder | 拦截两级 | 深层嵌套的覆盖层 |
(...)folder | 从根拦截 | 在当前视图中显示任意路由 |
元数据文件约定#
App 图标#
favicon | .ico | Favicon 文件 |
icon | .ico .jpg .jpeg .png .svg | App 图标文件 |
icon | .js .ts .tsx | 生成的 App 图标 |
apple-icon | .jpg .jpeg .png | Apple App 图标文件 |
apple-icon | .js .ts .tsx | 生成的 Apple App 图标 |
Open Graph 和 Twitter 图片#
opengraph-image | .jpg .jpeg .png .gif | Open Graph 图片文件 |
opengraph-image | .js .ts .tsx | 生成的 Open Graph 图片 |
twitter-image | .jpg .jpeg .png .gif | Twitter 图片文件 |
twitter-image | .js .ts .tsx | 生成的 Twitter 图片 |
SEO#
sitemap | .xml | Sitemap 文件 |
sitemap | .js .ts | 生成的 Sitemap |
robots | .txt | Robots 文件 |
robots | .js .ts | 生成的 Robots 文件 |
文件约定#
_app | .js .jsx .tsx | 自定义 App |
_document | .js .jsx .tsx | 自定义 Document |
_error | .js .jsx .tsx | 自定义错误页面 |
404 | .js .jsx .tsx | 404 错误页面 |
500 | .js .jsx .tsx | 500 错误页面 |
路由#
| 文件夹约定 | ||
index | .js .jsx .tsx | 首页 |
folder/index | .js .jsx .tsx | 嵌套页面 |
| 文件约定 | ||
index | .js .jsx .tsx | 首页 |
file | .js .jsx .tsx | 嵌套页面 |
动态路由#
| 文件夹约定 | ||
[folder]/index | .js .jsx .tsx | 动态路由段 |
[...folder]/index | .js .jsx .tsx | 全捕获路由段 |
[[...folder]]/index | .js .jsx .tsx | 可选全捕获路由段 |
| 文件约定 | ||
[file] | .js .jsx .tsx | 动态路由段 |
[...file] | .js .jsx .tsx | 全捕获路由段 |
[[...file]] | .js .jsx .tsx | 可选全捕获路由段 |
组织项目#
Next.js 对如何组织和就近放置项目文件不做强制规定。但它确实提供了一些功能来帮助你组织项目。
组件层级#
在特殊文件中定义的组件按照特定的层级渲染:
layout.jstemplate.jserror.js(React 错误边界)loading.js(React suspense 边界)not-found.js(用于“未找到” UI 的 React 错误边界)page.js或嵌套的layout.js
组件在嵌套路由中递归渲染,这意味着路由段的组件将嵌套在其父段组件的内部。
就近放置(Colocation)#
在 app 目录中,嵌套文件夹定义路由结构。每个文件夹代表一个路由段,映射到 URL 路径中的相应段。
然而,即使路由结构是通过文件夹定义的,在将 page.js 或 route.js 文件添加到路由段之前,路由无法公开访问。
而且,即使路由已可公开访问,也只有 page.js 或 route.js 返回的内容会发送到客户端。
这意味着项目文件可以安全地就近放置在 app 目录的路由段内,而不会意外地变为可路由。
小知识:虽然你可以将项目文件就近放在
app中,但你并非必须这样做。如果你愿意,可以将它们保存在app目录之外。
私有文件夹#
可以通过在文件夹名称前加下划线来创建私有文件夹:_folderName
这表示该文件夹是私有实现细节,不应被路由系统考虑,从而将该文件夹及其所有子文件夹排除在路由之外。
由于 app 目录中的文件默认可以安全地就近放置,因此就近放置不需要私有文件夹。不过,它们在以下方面可能很有用:
- 将 UI 逻辑与路由逻辑分离。
- 在整个项目和 Next.js 生态系统中一致地组织内部文件。
- 在代码编辑器中对文件进行排序和分组。
- 避免与未来 Next.js 文件约定发生潜在的命名冲突。
小知识:
- 虽然这不是框架约定,但你也可以考虑使用相同的下划线模式将私有文件夹之外的文件标记为“私有”。
- 你可以通过在文件夹名称前加
%5F(下划线的 URL 编码形式)来创建以下划线开头的 URL 段:%5FfolderName。- 如果你不使用私有文件夹,了解 Next.js 的特殊文件约定会很有帮助,以防止意外的命名冲突。
路由组#
可以通过将文件夹名括在括号中创建路由组:(folderName)
这表示该文件夹仅用于组织目的,不应包含在路由的 URL 路径中。
路由组可用于:
- 按网站板块、用途或团队组织路由。例如营销页面、管理页面等。
- 在同一路由段层级启用嵌套布局:
src 文件夹#
Next.js 支持将应用程序代码(包括 app)存储在可选的 src 文件夹中。这将应用程序代码与主要位于项目根目录的项目配置文件分离开来。
示例#
以下部分概述了一些常见策略。最简单的要点是选择一种适合你和团队的策略,并在整个项目中保持一致。
小知识:在下面的示例中,我们使用
components和lib文件夹作为通用占位符,它们的命名没有特殊的框架意义,你的项目可能会使用其他文件夹,如ui、utils、hooks、styles等。
将项目文件存储在 app 之外#
此策略将所有应用程序代码存储在项目根目录的共享文件夹中,并使 app 目录仅用于路由目的。
将项目文件存储在 app 内的顶级文件夹中#
此策略将所有应用程序代码存储在 app 目录根目录的共享文件夹中。
按功能或路由拆分项目文件#
此策略将全局共享的应用程序代码存储在根 app 目录中,并将更具体的应用程序代码拆分到使用它们的路由段中。
组织路由而不影响 URL 路径#
要在不影响 URL 的情况下组织路由,可以创建一个组将相关路由放在一起。括号中的文件夹将不会出现在 URL 中(例如 (marketing) 或 (shop))。
尽管 (marketing) 和 (shop) 内的路由共享相同的 URL 层级,但你可以通过在它们的文件夹中添加 layout.js 文件来为每个组创建不同的布局。这些布局嵌套在现有的 app 布局中。
让特定段选用布局#
要让特定路由选用某个布局,创建一个新的路由组(例如 (shop)),并将共享同一布局的路由移入该组(例如 account 和 cart)。组外的路由将不会共享该布局(例如 checkout)。
为特定路由选用加载骨架屏#
要通过 loading.js 文件将加载骨架屏应用于特定路由,创建一个新的路由组(例如 /(overview)),然后将 loading.tsx 移入该路由组。
现在,loading.tsx 文件将仅应用于你的仪表盘 → 概览页面,而不是所有仪表盘页面,且不影响 URL 路径结构。
创建多个根布局#
要创建多个根布局,删除顶层的 layout.js 文件,并在每个路由组内添加一个 layout.js 文件。这对于将应用程序划分为具有完全不同 UI 或体验的板块很有用。需要为每个根布局添加 <html> 和 <body> 标签。
在上面的示例中,(marketing) 和 (shop) 都有自己的根布局。