NNext.js 中文网 GitHub

项目结构与组织

了解 Next.js 项目中的文件夹和文件约定,以及如何组织你的项目。

本页概述了 Next.js 中所有文件夹和文件约定,并给出了组织项目的建议。

文件夹和文件约定#

顶级文件夹#

顶级文件夹用于组织应用程序的代码和静态资源。

appApp Router
pagesPages Router
public要提供的静态资源
src可选的应用程序源码文件夹

顶级文件#

顶级文件用于配置应用程序、管理依赖项、运行 proxy、集成监控工具以及定义环境变量。

Next.js
next.config.jsNext.js 的配置文件
package.json项目依赖项和脚本
instrumentation.tsOpenTelemetry 和 Instrumentation 文件
proxy.tsNext.js 请求 proxy
.env环境变量(不应被版本控制跟踪)
.env.local本地环境变量(不应被版本控制跟踪)
.env.production生产环境变量(不应被版本控制跟踪)
.env.development开发环境变量(不应被版本控制跟踪)
eslint.config.mjsESLint 的配置文件
.gitignore要忽略的 Git 文件和文件夹
next-env.d.tsNext.js 的 TypeScript 声明文件(不应被版本控制跟踪)
tsconfig.jsonTypeScript 的配置文件
jsconfig.jsonJavaScript 的配置文件

路由文件#

添加 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 .tsAPI 端点
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.icoFavicon 文件
icon.ico .jpg .jpeg .png .svgApp 图标文件
icon.js .ts .tsx生成的 App 图标
apple-icon.jpg .jpeg .pngApple App 图标文件
apple-icon.js .ts .tsx生成的 Apple App 图标

Open Graph 和 Twitter 图片#

opengraph-image.jpg .jpeg .png .gifOpen Graph 图片文件
opengraph-image.js .ts .tsx生成的 Open Graph 图片
twitter-image.jpg .jpeg .png .gifTwitter 图片文件
twitter-image.js .ts .tsx生成的 Twitter 图片

SEO#

sitemap.xmlSitemap 文件
sitemap.js .ts生成的 Sitemap
robots.txtRobots 文件
robots.js .ts生成的 Robots 文件

文件约定#

_app.js .jsx .tsx自定义 App
_document.js .jsx .tsx自定义 Document
_error.js .jsx .tsx自定义错误页面
404.js .jsx .tsx404 错误页面
500.js .jsx .tsx500 错误页面

路由#

文件夹约定
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.js
  • template.js
  • error.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) 都有自己的根布局。

Next.js 中文网