專案結構與組織

本頁面提供 Next.js 中所有資料夾與檔案慣例的概述，以及組織專案的建議。

資料夾與檔案慣例

頂層資料夾

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


`app`	應用路由 (App Router)
`pages`	頁面路由 (Pages Router)
`public`	靜態資源檔案
`src`	可選的應用程式原始碼資料夾

頂層檔案

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


Next.js
`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`	載入 UI
`not-found`	`.js` `.jsx` `.tsx`	404 頁面
`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`	從根目錄攔截路由

元資料檔案慣例

應用圖示


`favicon`	`.ico`	Favicon 檔案
`icon`	`.ico` `.jpg` `.jpeg` `.png` `.svg`	應用圖示檔案
`icon`	`.js` `.ts` `.tsx`	生成的應用圖示
`apple-icon`	`.jpg` `.jpeg`, `.png`	Apple 應用圖示檔案
`apple-icon`	`.js` `.ts` `.tsx`	生成的 Apple 應用圖示

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 錯誤邊界)
loading.js (React suspense 邊界)
not-found.js (React 錯誤邊界)
page.js 或巢狀 layout.js

Component Hierarchy for File Conventions

這些元件會在巢狀路由中遞迴渲染，意味著路由區段的元件會嵌套在其父區段的元件內部。

Nested File Conventions Component Hierarchy

檔案共置 (Colocation)

在 app 目錄中，巢狀資料夾定義了路由結構。每個資料夾代表一個路由區段 (route segment)，對應到 URL 路徑中的相應區段。

然而，即使路由結構是透過資料夾定義的，除非在路由區段中添加 page.js 或 route.js 檔案，否則該路由不會公開可存取。

圖表顯示在路由區段添加 page.js 或 route.js 檔案前，路由不會公開可存取

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

這意味著專案檔案可以安全地共置於 app 目錄的路由區段中，而不會意外變成可路由的。

圖表顯示共置的專案檔案即使區段包含 page.js 或 route.js 也不會變成可路由

須知事項：雖然你可以將專案檔案共置於 app 目錄中，但這並非必要。如果你偏好，也可以將它們保留在 app 目錄外。

私有資料夾 (Private folders)

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

這表示該資料夾是私有實作細節，不應被路由系統考慮，從而將該資料夾及其所有子資料夾排除在路由之外。

由於 app 目錄中的檔案預設可以安全共置，私有資料夾並非共置的必要條件。但它們在以下情況很有用：

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

須知事項：

雖然這不是框架慣例，但你可能也會考慮使用相同的底線模式來標記私有資料夾外的檔案為「私有」。

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

如果不使用私有資料夾，了解 Next.js 的特殊檔案慣例有助於避免意外的命名衝突。