專案結構與組織

本頁面概述 Next.js 中的資料夾和檔案慣例，以及組織專案的提示。

資料夾和檔案慣例

頂層資料夾

頂層資料夾用於組織應用程式的程式碼和靜態資源。


`app`	App Router
`pages`	Pages Router
`public`	要提供的靜態資源
`src`	可選的應用程式原始碼資料夾

頂層檔案

頂層檔案用於設定應用程式、管理依賴項、執行中介軟體、整合監控工具，以及定義環境變數。


Next.js
`next.config.js`	Next.js 的設定檔
`package.json`	專案依賴項和腳本
`instrumentation.ts`	OpenTelemetry 和儀器化檔案
`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`	版面配置
`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`	平行路由回退頁面

巢狀路由


`folder`	路由區段
`folder/folder`	巢狀路由區段

動態路由


`[folder]`	動態路由區段
`[...folder]`	全域捕捉路由區段
`[[...folder]]`	可選的全域捕捉路由區段

路由群組和私有資料夾


`(folder)`	群組路由，但不影響路由
`_folder`	選擇退出路由的資料夾及其所有子區段

平行和攔截路由


`@folder`	命名插槽
`(.)folder`	攔截同一層級
`(..)folder`	攔截上一層級
`(..)(..)folder`	攔截上兩層級
`(...)folder`	從根目錄攔截

Metadata 檔案慣例

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`	`.js` `.ts`	產生的網站地圖
`robots`	`.txt`	Robots 檔案
`robots`	`.js` `.ts`	產生的 Robots 檔案

元件階層

在路由區段的特殊檔案中定義的 React 元件，會以特定的階層結構渲染

layout.js
template.js
error.js (React 錯誤邊界)
loading.js (React Suspense 邊界)
not-found.js (React 錯誤邊界)
page.js 或巢狀 layout.js

Component Hierarchy for File Conventions

在巢狀路由中，區段的元件將會巢狀在父區段的元件內部。

Nested File Conventions Component Hierarchy

組織您的專案

除了資料夾和檔案慣例，Next.js 對於您如何組織和並置專案檔案是沒有既定想法的。但它確實提供了一些功能來協助您組織專案。

並置

在 app 目錄中，巢狀資料夾定義路由結構。每個資料夾代表一個路由區段，該區段會對應到 URL 路徑中的對應區段。

然而，即使路由結構是透過資料夾定義的，但在將 page.js 或 route.js 檔案新增至路由區段之前，路由不會公開存取。

A diagram showing how a route is not publicly accessible until a page.js or route.js file is added to a route segment.

而且，即使路由已公開存取，也只有 page.js 或 route.js 傳回的內容會傳送至用戶端。

A diagram showing how page.js and route.js files make routes publicly accessible.

這表示專案檔案可以安全地並置在 app 目錄中的路由區段內，而不會意外地變成可路由的。

A diagram showing colocated project files are not routable even when a segment contains a page.js or route.js file.

小提示:

雖然您可以在 app 中並置專案檔案，但您不一定要這麼做。如果您願意，您可以將它們保留在 app 目錄外部。

私有資料夾

私有資料夾可以透過在資料夾前加上底線來建立：_folderName

這表示資料夾是私有實作細節，不應被路由系統考量，因此選擇退出路由的資料夾及其所有子資料夾。

An example folder structure using private folders

由於 app 目錄中的檔案預設可以安全地並置，因此並置不需要私有資料夾。但是，它們對於以下情況可能很有用：

將 UI 邏輯與路由邏輯分離。
一致地組織專案和 Next.js 生態系統中的內部檔案。
在程式碼編輯器中排序和群組檔案。
避免與未來 Next.js 檔案慣例發生潛在的命名衝突。

小提示:

雖然不是框架慣例，您也可以考慮使用相同的底線模式將私有資料夾外部的檔案標記為「私有」。

您可以透過在資料夾名稱前加上 %5F（底線的 URL 編碼形式）來建立以底線開頭的 URL 區段：%5FfolderName。

如果您不使用私有資料夾，那麼了解 Next.js 特殊檔案慣例，以防止意外的命名衝突會很有幫助。