專案結構與組織

本頁面提供 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`	佈局 (Layout)
`page`	`.js` `.jsx` `.tsx`	頁面 (Page)
`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`	從根層級攔截

元資料檔案慣例

應用圖示


`favicon`	`.ico`	網站圖示檔案
`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

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

共置 (Colocation)

在 app 目錄中，巢狀資料夾定義了路由結構。每個資料夾代表一個路由區段，對應到 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 特殊檔案約定有助於避免意外的命名衝突。