Next.js 項(xiàng)目結(jié)構(gòu)與組織：新手指南
文件夾和文件約定
本頁概述了 Next.js 中的文件夾和文件約定，以及組織項(xiàng)目的提示。
頂層文件夾
頂層文件夾用于組織應(yīng)用的代碼和靜態(tài)資源。
| 文件夾 | 用途 |
|---|---|
app |
App Router（應(yīng)用路由器） |
pages |
Pages Router（頁面路由器） |
public |
靜態(tài)資源服務(wù) |
src |
可選的應(yīng)用源文件夾 |
頂層文件
頂層文件用于配置應(yīng)用、管理依賴項(xiàng)、運(yùn)行中間件、集成監(jiān)控工具以及定義環(huán)境變量。
| Next.js | |
next.config.js |
Next.js 的配置文件 |
package.json |
項(xiàng)目依賴項(xiàng)和腳本 |
instrumentation.ts |
OpenTelemetry 和 Instrumentation 文件 |
middleware.ts |
Next.js請求中間件 |
.env |
環(huán)境變量 |
.env.local |
本地環(huán)境變量 |
.env.production |
生產(chǎn)環(huán)境變量 |
.env.development |
開發(fā)環(huán)境變量 |
.eslintrc.json |
ESLint 的配置文件 |
.gitignore |
要忽略的 Git 文件和文件夾 |
next-env.d.ts |
Next.js 的 TypeScript 聲明文件 |
tsconfig.json |
TypeScript 的配置文件 |
jsconfig.json |
JavaScript 的配置文件 |
路由文件
layout |
.js .jsx .tsx |
布局 |
page |
.js .jsx .tsx |
頁 |
loading |
.js .jsx .tsx |
加載 UI |
not-found |
.js .jsx .tsx |
未找到 UI |
error |
.js .jsx .tsx |
錯(cuò)誤 UI |
global-error |
.js .jsx .tsx |
全局錯(cuò)誤 UI |
route |
.js .ts |
API 終端節(jié)點(diǎn) |
template |
.js .jsx .tsx |
重新渲染的布局 |
default |
.js .jsx .tsx |
Parallel route fallback 頁面 |
嵌套路由
| 文件夾結(jié)構(gòu) | 路由段 |
|---|---|
folder |
路由段 |
folder/folder |
嵌套路由段 |
動(dòng)態(tài)路由
[folder\] |
動(dòng)態(tài)路由段 |
[...folder\] |
Catch-all 路由段 |
[[...folder\]] |
可選的 catch-all 路由段 |
路由組和私有文件夾
| 文件夾結(jié)構(gòu) | 用途 |
|---|---|
(folder) |
分組路由而不影響路由 |
_folder |
選擇文件夾及其所有子段退出路由 |
并行和攔截路由
@folder |
命名槽 |
(.)folder |
截距相同級別 |
(..)folder |
截距 1 級以上 |
(..)(..)folder |
截距以上兩級 |
(...)folder |
從 root 截距 |
元數(shù)據(jù)文件約定
應(yīng)用圖標(biāo)
| 文件名 | 擴(kuò)展名 | 用途 |
|---|---|---|
favicon |
.ico |
Favicon 文件 |
icon |
.ico .jpg .jpeg .png .svg |
應(yīng)用圖標(biāo)文件 |
icon |
.js .ts .tsx |
生成的應(yīng)用圖標(biāo) |
apple-icon |
.jpg .jpeg .png |
Apple 應(yīng)用圖標(biāo)文件 |
apple-icon |
.js .ts .tsx |
生成的 Apple 應(yīng)用圖標(biāo) |
Open Graph 和 Twitter 圖像
opengraph-image |
.jpg .jpeg .png .gif |
打開 Graph 圖像文件 |
opengraph-image |
.js .ts .tsx |
生成的 Open Graph 圖像 |
twitter-image |
.jpg .jpeg .png .gif |
Twitter 圖片文件 |
twitter-image |
.js .ts .tsx |
生成的 Twitter 圖像 |
SEO（搜索引擎優(yōu)化）
sitemap |
.xml |
站點(diǎn)地圖文件 |
sitemap |
.js .ts |
生成的站點(diǎn)地圖 |
robots |
.txt |
Robots 文件 |
robots |
.js .ts |
生成的 Robots 文件 |
組件層次結(jié)構(gòu)
在路由段的特殊文件中定義的 React 組件按照特定層次結(jié)構(gòu)渲染：
layout.jstemplate.jserror.js（React 錯(cuò)誤邊界）loading.js（React 懸停邊界）not-found.js（React 錯(cuò)誤邊界）page.js或嵌套的layout.js
在嵌套路由中，子段的組件將嵌套在父段組件的內(nèi)部。
組織項(xiàng)目
除了文件夾和文件約定外，Next.js 對如何組織和共置項(xiàng)目文件沒有固定意見。但它確實(shí)提供了一些功能來幫助你組織項(xiàng)目。
共置
在 app 目錄中，嵌套文件夾定義路由結(jié)構(gòu)。每個(gè)文件夾代表一個(gè)路由段，映射到 URL 路徑中的相應(yīng)段。
然而，盡管路由結(jié)構(gòu)是通過文件夾定義的，但只有在路由段中添加了 page.js 或 route.js 文件后，路由才對外公開訪問。
而且，即使路由對外公開訪問，只有 page.js 或 route.js 返回的內(nèi)容才會(huì)發(fā)送到客戶端。
這意味著項(xiàng)目文件可以安全地在 app 目錄中的路由段內(nèi)共置，而不會(huì)意外地成為可路由的。
小貼士：
- 雖然你可以在app中共置項(xiàng)目文件，但你不必這么做。如果你愿意，你可以將它們放在app目錄之外。
私有文件夾
可以通過在文件夾名稱前加上下劃線前綴來創(chuàng)建私有文件夾：_folderName
這表明該文件夾是私有實(shí)現(xiàn)細(xì)節(jié)，不應(yīng)被路由系統(tǒng)考慮，從而將該文件夾及其所有子文件夾退出路由。
由于 app 目錄中的文件默認(rèn)可以安全地共置，因此私有文件夾對于共置并不是必需的。然而，它們對于以下目的可能很有用：
- 將 UI 邏輯與路由邏輯分開。
- 在整個(gè)項(xiàng)目和 Next.js 生態(tài)系統(tǒng)中一致地組織內(nèi)部文件。
- 在代碼編輯器中對文件進(jìn)行排序和分組。
- 避免與未來 Next.js 文件約定的潛在命名沖突。
小貼士：
- 雖然這不是框架約定，但你也可以考慮使用相同的下劃線模式標(biāo)記私有文件夾之外的文件為“私有”。
- 你可以通過在文件夾名稱前加上%5F（下劃線的 URL 編碼形式）來創(chuàng)建以_開頭的 URL 段：%5FfolderName。
- 如果你不使用私有文件夾，了解 Next.js 的特殊文件約定將有助于避免意外的命名沖突。
路由組
可以通過將文件夾用括號括起來來創(chuàng)建路由組：(folderName)
這表明該文件夾是用于組織目的，不應(yīng)包含在路由的 URL 路徑中。
路由組對于以下目的很有用：
- 將路由按組組織，例如按站點(diǎn)部分、意圖或團(tuán)隊(duì)。
- 在同一路由段級別啟用嵌套布局：
- 在同一段中創(chuàng)建多個(gè)嵌套布局，包括多個(gè)根布局
- 為常見段中的一組路由添加布局
src 目錄
Next.js 支持將應(yīng)用代碼（包括 app）存儲在可選的 src 目錄中。這將應(yīng)用代碼與大多位于項(xiàng)目根目錄的項(xiàng)目配置文件分開。
常見策略
以下部分列出了常見策略的非常高層次概述。最簡單的收獲是選擇一個(gè)適合你和你的團(tuán)隊(duì)的策略，并在整個(gè)項(xiàng)目中保持一致。
小貼士：在下面的例子中，我們使用
components和lib文件夾作為通用占位符，它們的命名沒有特殊的框架意義，你的項(xiàng)目可能會(huì)使用其他文件夾，如ui、utils、hooks、styles等。
將項(xiàng)目文件存儲在 app 目錄之外
此策略將所有應(yīng)用代碼存儲在項(xiàng)目根目錄的共享文件夾中，并保持 app 目錄僅用于路由目的。
將項(xiàng)目文件存儲在 app 目錄內(nèi)的頂層文件夾中
此策略將所有應(yīng)用代碼存儲在app 目錄根目錄的共享文件夾中。
按功能或路由拆分項(xiàng)目文件
此策略將全局共享的應(yīng)用代碼存儲在根 app 目錄中，并將更具體的應(yīng)用代碼拆分到使用它們的路由段中。
更多建議：