專案組織與檔案共置
除了路由資料夾與檔案慣例外,Next.js 對於專案檔案組織與共置方式採取非強制性立場。
本頁分享預設行為與可用於組織專案的功能。
預設安全共置
在 app
目錄中,巢狀資料夾層級結構定義了路由結構。
每個資料夾代表對應 URL 路徑中的路由區段。
然而,即使路由結構是透過資料夾定義,路由區段必須包含 page.js
或 route.js
檔案才會公開可存取。

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

這表示專案檔案可以安全地共置於 app
目錄的路由區段中,而不會意外成為可存取路由。

須知:
- 這與
pages
目錄不同,pages
中的任何檔案都會被視為路由。- 雖然您可以將專案檔案共置於
app
中,但並非必須。若您偏好,可以將它們保留在app
目錄外。
專案組織功能
Next.js 提供多項功能協助您組織專案。
私有資料夾
可透過在資料夾名稱前加底線來建立私有資料夾:_folderName
這表示該資料夾是私有實作細節,不應被路由系統考慮,從而將該資料夾及其所有子資料夾排除在路由外。

由於 app
目錄中的檔案可預設安全共置,私有資料夾並非共置的必要條件。但它們可用於:
- 將 UI 邏輯與路由邏輯分離。
- 在專案與 Next.js 生態系統中一致地組織內部檔案。
- 在程式碼編輯器中排序與分組檔案。
- 避免與未來 Next.js 檔案慣例的命名衝突。
須知
- 雖然不是框架慣例,您也可以考慮使用相同底線模式標記私有資料夾外的檔案為「私有」。
- 可透過在資料夾名稱前加
%5F
(底線的 URL 編碼形式) 來建立以底線開頭的 URL 區段:%5FfolderName
。- 若不使用私有資料夾,了解 Next.js 特殊檔案慣例有助於避免意外命名衝突。
路由群組
可透過將資料夾用括號包裹來建立路由群組:(folderName)
這表示該資料夾僅用於組織目的,不應包含在路由的 URL 路徑中。

路由群組適用於:
- 將路由分組組織,例如按網站區段、用途或團隊。
- 在同一路由區段層級啟用巢狀佈局:
src
目錄
Next.js 支援將應用程式碼 (包括 app
) 儲存在可選的 src
目錄中。這可將應用程式碼與主要位於專案根目錄的專案設定檔分離。

模組路徑別名
Next.js 支援模組路徑別名,讓深度巢狀的專案檔案中的導入更易讀與維護。
// 之前
import { Button } from '../../../components/button'
// 之後
import { Button } from '@/components/button'
專案組織策略
Next.js 專案中組織檔案與資料夾沒有「正確」或「錯誤」的方式。
以下部分列出常見策略的高層次概述。最簡單的原則是選擇適合您與團隊的策略,並在整個專案中保持一致。
須知:在下方範例中,我們使用
components
和lib
資料夾作為通用佔位符,其命名沒有特殊框架意義,您的專案可能使用其他資料夾如ui
、utils
、hooks
、styles
等。
將專案檔案儲存在 app
外
此策略將所有應用程式碼儲存在專案根目錄的共用資料夾中,並保持 app
目錄純粹用於路由目的。

將專案檔案儲存在 app
內的頂層資料夾
此策略將所有應用程式碼儲存在 app
目錄根目錄的共用資料夾中。

按功能或路由拆分專案檔案
此策略將全域共用的應用程式碼儲存在 app
根目錄,並將更特定的應用程式碼拆分到使用它們的路由區段中。
