專案組織與檔案共置

除了路由資料夾與檔案慣例外,Next.js 對於專案檔案組織與共置方式採取非強制性立場。

本頁分享預設行為與可用於組織專案的功能。

預設安全共置

app 目錄中,巢狀資料夾層級結構定義了路由結構。

每個資料夾代表對應 URL 路徑中的路由區段。

然而,即使路由結構是透過資料夾定義,路由區段必須包含 page.jsroute.js 檔案才會公開可存取

圖表展示路由區段需包含 page.js 或 route.js 檔案才會公開可存取

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

圖表展示 page.js 和 route.js 檔案如何使路由公開可存取

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

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

須知:

  • 這與 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 目錄中。這可將應用程式碼與主要位於專案根目錄的專案設定檔分離。

使用 `src` 目錄的範例資料夾結構

模組路徑別名

Next.js 支援模組路徑別名,讓深度巢狀的專案檔案中的導入更易讀與維護。

app/dashboard/settings/analytics/page.js
// 之前
import { Button } from '../../../components/button'

// 之後
import { Button } from '@/components/button'

專案組織策略

Next.js 專案中組織檔案與資料夾沒有「正確」或「錯誤」的方式。

以下部分列出常見策略的高層次概述。最簡單的原則是選擇適合您與團隊的策略,並在整個專案中保持一致。

須知:在下方範例中,我們使用 componentslib 資料夾作為通用佔位符,其命名沒有特殊框架意義,您的專案可能使用其他資料夾如 uiutilshooksstyles 等。

將專案檔案儲存在 app

此策略將所有應用程式碼儲存在專案根目錄的共用資料夾中,並保持 app 目錄純粹用於路由目的。

專案檔案儲存在 app 外的範例資料夾結構

將專案檔案儲存在 app 內的頂層資料夾

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

專案檔案儲存在 app 內的範例資料夾結構

按功能或路由拆分專案檔案

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

按功能或路由拆分專案檔案的範例資料夾結構