本页概述了 Next.js 中所有文件夹和文件约定，以及组织项目的建议
文件夹和文件约定
顶层文件夹
| 文件夹 | 作用 |
|---|---|
app | App Router |
pages | Pages Router |
public | 待服务的静态资产 |
src | 可选的应用程序源文件夹 |
App Router VS. Pages Router
Next.js 有两个不同的路由器：
- App Router ：支持服务器组件等新 React 功能的较新的路由器
- Pages Router ：原始路由器，仍然受支持并正在改进
本文只介绍 App Router，因为实际项目中，除非要维护老项目才可能使用 Pages Router
顶层文件
顶层文件用于配置您的应用程序、管理依赖项、运行中间件、集成监控工具和定义环境变量
| 文件 | 作用 |
|---|---|
next.config.js | Next.js 的配置文件 |
package.json | 项目依赖项和脚本 |
instrumentation.ts | OpenTelemetry 和 Instrumentation 文件 |
middleware.ts | Next.js 请求中间件 |
.env | 环境变量 |
.env.local | 本地环境变量 |
.env.production | 生产环境变量 |
.env.development | 开发环境变量 |
.eslintrc.json | ESLint 的配置文件 |
.gitignore | 要忽略的 Git 文件和文件夹 |
next-env.d.ts | Next.js 的 TypeScript 声明文件 |
tsconfig.json | TypeScript 的配置文件 |
jsconfig.json | JavaScript 的配置文件 |
路由文件
| 文件 | 扩展名 | 作用 |
|---|---|---|
layout | .js .jsx .tsx | Layout 布局 |
page | .js .jsx .tsx | Page 页面 |
loading | .js .jsx .tsx | Loading UI |
not-found | .js .jsx .tsx | Not found UI |
error | .js .jsx .tsx | Error UI |
global-error | .js .jsx .tsx | Global error UI |
route | .js .ts | API endpoint API 端点 |
template | .js .jsx .tsx | Re-rendered layout 重新渲染的布局 |
default | .js .jsx .tsx | Parallel route fallback page 并行路由回退页面 |
嵌套路由
| 文件夹 | 作用 |
|---|---|
folder | 路由段 |
folder/folder | 嵌套路由段 |
动态路由
| 文件夹 | 作用 |
|---|---|
[folder] | 动态路由段 |
[...folder] | 捕获所有路由段 |
[[...folder]] | 可选的全覆盖路由段 |
路由组和私有文件夹
| 文件夹 | 作用 |
|---|---|
(folder) | 不影响路由的分组路由 |
_folder | 文件夹和所有子段退出路由 |
平行路由和拦截路由
| 文件夹 | 作用 |
|---|---|
@folder | 命名槽 |
(.)folder | 拦截同级别 |
(..)folder | 拦截上一级 |
(..)(..)folder | 拦截两级以上 |
(...)folder | 从根目录拦截 |
元数据文件约定
App icons
| 文件 | 扩展名 | 作用 |
|---|---|---|
favicon | .ico | Favicon 文件 |
icon | .ico .jpg .jpeg .png .svg | App Icon 文件 |
icon | .js .ts .tsx | 生成的 App Icon |
apple-icon | .jpg .jpeg, .png | Apple App Icon 文件 |
apple-icon | .js .ts .tsx | 生成的 Apple App Icon |
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 | .js .ts | 生成的站点地图 |
robots | .txt | Robots 文件 |
robots | .js .ts | 生成的 Robots 文件 |
组织你的项目
Next.js 对于如何组织和托管项目文件并没有明确的要求 。但它确实提供了一些功能来帮助你组织项目
组件层次结构
特殊文件中定义的组件按照特定的层次结构进行渲染：
layout.jstemplate.jserror.js(React error boundary)loading.js(React suspense boundary)not-found.js(React error boundary)page.js或嵌套的layout.js
组件在嵌套路由中以递归方式呈现，这意味着路由段的组件将嵌套在其父段的组件内
安全地共置
在 app 目录中，嵌套文件夹定义了路由结构。每个文件夹代表一个路由段，该路由段映射到 URL 路径中的相应段
但是，即使通过文件夹定义路由结构，在将 page.js 或 route.js 文件添加到路由段之前，路由也是不可公开访问的
并且，即使路由公开可访问，也只有 page.js 或 route.js 返回的内容才会发送到客户端
这意味着项目文件可以安全地放置在 app 目录中的路由段内，而不会意外被路由
温馨提示：虽然可以将项目文件放在 app 下，但这并不是必须的。如果您愿意，也可以将它们放在 app 目录之外
私有文件夹
可以通过在文件夹前添加下划线来创建私人文件夹：_folderName
这表明该文件夹是私有的实现细节，不应被路由系统考虑，从而该文件夹及其所有子文件夹退出路由
由于默认情况下，app 目录中的文件可以安全地共置，因此私有文件夹并非共置的必需项。然而，它们在以下情况下很有用：
- 将 UI 逻辑与路由逻辑分离
- 在整个项目和 Next.js 生态系统中一致地组织内部文件
- 在代码编辑器中对文件进行排序和分组
- 避免与未来 Next.js 文件约定发生潜在的命名冲突
您可以通过在文件夹名称前加上 %5F（下划线的 URL 编码形式）来创建以下划线开头的 URL 段：%5FfolderName
路由组
可以通过将文件夹括在括号中来创建路由组：(folderName)
这表明该文件夹用于组织目的，不应包含在路由的 URL 路径中
路由组可用于：
- 按站点部分、意图或团队组织路由。例如营销页面、管理页面等
- 在同一路由段级别启用嵌套布局：
- 将布局添加到公共路由中的路由子集
要将特定路由页面使用不同的布局，请创建一个新的路线组（例如 (shop)），并将共享相同布局的路由（例如 account 和 cart）移入该组。组外的路由将不会使用布局（例如 checkout）
除了 layout.js，loading.js 等也同理
- 在同一段中创建多个嵌套布局，包括多个根布局
要创建多个根布局，请移除顶层的 layout.js 文件，并在每个路由组内添加一个 layout.js 文件。这对于将应用程序划分为具有完全不同 UI 或体验的部分非常有用。每个根布局都需要添加 <html> 和 <body> 标签
在上面的例子中， (marketing) 和 (shop) 都有自己的根布局
src 文件夹
Next.js 支持将应用程序代码（包括 app）存储在可选的 src 文件夹中。这将应用程序代码与项目配置文件（主要位于项目的根目录中）分开