本页概述了 Next.js 中所有文件夹和文件约定，以及组织项目的建议

文件夹和文件约定

顶层文件夹

![[Pasted image 20250729173226.png]]

文件夹	作用
`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.js
template.js
error.js (React error boundary)
loading.js (React suspense boundary)
not-found.js (React error boundary)
page.js 或嵌套的 layout.js

![[Pasted image 20250729182021.png]]

组件在嵌套路由中以递归方式呈现，这意味着路由段的组件将嵌套在其父段的组件内

![[Pasted image 20250729182138.png]]

安全地共置

在 app 目录中，嵌套文件夹定义了路由结构。每个文件夹代表一个路由段，该路由段映射到 URL 路径中的相应段

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

![[Pasted image 20250729182405.png]]

并且，即使路由公开可访问，也只有 page.js 或 route.js 返回的内容才会发送到客户端

![[Pasted image 20250729182445.png]]

这意味着项目文件可以安全地放置在 app 目录中的路由段内，而不会意外被路由

![[Pasted image 20250729182532.png]]

温馨提示：虽然可以将项目文件放在 app 下，但这并不是必须的。如果您愿意，也可以将它们放在 app 目录之外

私有文件夹

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

这表明该文件夹是私有的实现细节，不应被路由系统考虑，从而该文件夹及其所有子文件夹退出路由

由于默认情况下，app 目录中的文件可以安全地共置，因此私有文件夹并非共置的必需项。然而，它们在以下情况下很有用：

将 UI 逻辑与路由逻辑分离
在整个项目和 Next.js 生态系统中一致地组织内部文件
在代码编辑器中对文件进行排序和分组
避免与未来 Next.js 文件约定发生潜在的命名冲突

您可以通过在文件夹名称前加上 %5F（下划线的 URL 编码形式）来创建以下划线开头的 URL 段：%5FfolderName

路由组

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

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

![[Pasted image 20250729185115.png]]

路由组可用于：

按站点部分、意图或团队组织路由。例如营销页面、管理页面等
在同一路由段级别启用嵌套布局：

将布局添加到公共路由中的路由子集

要将特定路由页面使用不同的布局，请创建一个新的路线组（例如 (shop)），并将共享相同布局的路由（例如 account 和 cart）移入该组。组外的路由将不会使用布局（例如 checkout）

![[Pasted image 20250729185842.png]]

除了 layout.js，loading.js 等也同理

在同一段中创建多个嵌套布局，包括多个根布局

要创建多个根布局，请移除顶层的 layout.js 文件，并在每个路由组内添加一个 layout.js 文件。这对于将应用程序划分为具有完全不同 UI 或体验的部分非常有用。每个根布局都需要添加 <html> 和 <body> 标签

![[Pasted image 20250730112859.png]]

在上面的例子中， (marketing) 和 (shop) 都有自己的根布局

`src` 文件夹

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