Next.js 專案結構與檔案慣例

當你建立了一個 Next.js 專案後，理解目錄結構與「檔案慣例 (File Conventions)」是開發的第一步。Next.js 是一個約定大於配置 (Convention over Configuration) 的框架，特定的檔名代表了特定的功能。

核心目錄說明

一個典型的 Next.js (App Router) 專案包含以下主要目錄：

`app/` 目錄

這是 Next.js 最核心的地方。所有的路由 (Routes)、佈局 (Layouts) 和組合元件 (Components) 都會放在這裡。

在 App Router 中，資料夾的層級代表了 URL 的路徑。
只有資料夾內特定的檔案（如 page.tsx）會被公開為路由。

`public/` 目錄

放置靜態資源，例如圖片 (.png, .svg)、字體或 favicon.ico。

這裡的檔案可以透過根路徑 / 直接存取。例如 public/logo.png 在程式碼中可以用 /logo.png 引用。

各種設定檔

next.config.mjs：Next.js 的自定義設定檔，例如設定圖片來源域名、環境變數等。
package.json：定義專案依賴套件與執行的 Scripts 指令。
tsconfig.json：TypeScript 的編譯設定。
.env 系列檔案：存放機密的環境變數。

App 目錄下的特殊檔案

在 app/ 目錄中，有一些具有特殊意義的檔名，它們被稱為「檔案慣例」：

檔名	說明	用途
`layout.tsx`	佈局 (Layout)	該路徑及其子路徑共用的 UI。狀態會被保留且不會重新渲染。
`page.tsx`	頁面 (Page)	路由的唯一 UI 介面，讓該路徑可以被公開存取。
`loading.tsx`	載入中 (Loading)	配合 React Suspense，在頁面內容載入時顯示的 Loading 畫面。
`error.tsx`	錯誤處理 (Error)	配合 Error Boundary，當該路由發生運行錯誤時顯示的畫面。
`not-found.tsx`	404 頁面	當路徑不存在或主動呼叫 `notFound()` 時顯示的畫面。
`template.tsx`	模板 (Template)	與 Layout 類似，但每次切換路由時都會重新掛載 (Remount)。

檔案組織建議 (Colocation)

在 Next.js 中，官方鼓勵將「與頁面相關的檔案」放在同一個路由資料夾下。這被稱為 Colocation（同地協作）。

例如，你可以在 app/dashboard/ 資料夾中放置：

page.tsx：Dashboard 首頁。
Charts.tsx：僅用於 Dashboard 的元件。
utils.ts：僅用於 Dashboard 的輔助函式。
styles.module.css：該頁面的 CSS Modules。

這些額外的檔案（如 Charts.tsx）不會變成路由，因為它們的檔名不是 page.tsx、layout.tsx 等特殊檔名。只有 page.tsx 會對應到 /dashboard URL。

根佈局 (Root Layout)

在 app/layout.tsx 是所謂的 Root Layout，它是必備的，且適用於所有路由。它負責定義整站的 <html> 和 <body> 標籤。

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh-Hant">
      <body>
        <header>這是全站導覽列</header>
        <main>{children}</main>
        <footer>這是全站頁腳</footer>
      </body>
    </html>
  );
}

children 屬性代表目前正在瀏覽的子頁面或子佈局內容。
你可以在這裡引入 Google Fonts 或設定全站的全域樣式。

理解了這些結構，我們就可以開始動手設計網頁的樣式。