# 【Treeman】React 開發 # 【NextJS】相關 # 【Next.js】建立新專案 ```shell # npx create-next-app 建立新專案 $npx create-next-app Need to install the following packages: create-next-app@15.4.3 Ok to proceed? (y) y ✔ What is your project named? … demo-next ✔ Would you like to use TypeScript? … No / Yes #Yes ✔ Would you like to use ESLint? … No / Yes #Yes ✔ Would you like to use Tailwind CSS? … No / Yes #Yes ✔ Would you like your code inside a `src/` directory? … No / Yes #Yes ✔ Would you like to use App Router? (recommended) … No / Yes #Yes ✔ Would you like to use Turbopack for `next dev`? … No / Yes #No ✔ Would you like to customize the import alias (`@/*` by default)? … No / Yes #Yes ✔ What import alias would you like configured? … @/* Creating a new Next.js app in /Users/srou/Documents/vscode_workspace/demo/nextjs-demo/demo-next. Using npm. Initializing project with template: app-tw Installing dependencies: - react - react-dom - next Installing devDependencies: - typescript - @types/node - @types/react - @types/react-dom - @tailwindcss/postcss - tailwindcss added 59 packages, and audited 60 packages in 20s 11 packages are looking for funding run `npm fund` for details found 0 vulnerabilities Initialized a git repository. Success! Created demo-next at /Users/srou/Documents/vscode_workspace/demo/nextjs-demo/demo-next ``` ```shell # 啟動專案 npm run dev $npm run dev > demo-next@0.1.0 dev > next dev ⚠ Warning: Found multiple lockfiles. Selecting /Users/srou/Documents/vscode_workspace/yarn.lock. Consider removing the lockfiles at: * /Users/srou/Documents/vscode_workspace/demo/demo-next/package-lock.json ▲ Next.js 15.4.3 - Local: http://localhost:3000 - Network: http://192.168.1.1:3000 ✓ Starting... ✓ Ready in 2.1s ``` 當你使用 `npx create-next-app` 建立 Next.js 專案時，CLI 會引導你一步一步選擇要開啟哪些功能。以下是每一個步驟的說明，以及如果最後選擇 **不設定 import alias（例如 `@/*`）**，日後如何補上設定。 --- ## 🧱 建立 Next.js 專案步驟說明 ### 1. `What is your project named?` > 輸入專案資料夾名稱，例如 `demo-next`。 ### 2. `Would you like to use TypeScript?` > 是否使用 TypeScript（推薦選 Yes，提供型別安全）。 - 選 Yes → 自動生成 `tsconfig.json` - 選 No → 使用 JavaScript + `jsconfig.json` --- ### 3. `Would you like to use ESLint?` > 是否啟用 [ESLint](https://eslint.org/) 做程式碼檢查。 - 選 Yes → 建立 `.eslintrc.json` 等設定，避免潛在錯誤。 --- ### 4. `Would you like to use Tailwind CSS?` > 是否加入 [Tailwind CSS](https://tailwindcss.com/) 做 UI 樣式設計。 --- ### 5. `Would you like your code inside a src/ directory?` > 是否將程式碼放入 `src/` 子資料夾中。 - 選 Yes → 專案結構更清晰，建議開啟。 --- ### 6. `Would you like to use App Router? (recommended)` > 啟用 Next.js 13+ 的新 **App Router** 架構（基於 `app/` 資料夾）。 - 選 Yes → 使用新路由系統，支援 Server Components 等現代功能。 --- ### 7. `Would you like to use Turbopack for next dev?` > 是否使用新一代 Turbopack 開發模式（取代 Webpack 開發時編譯器）。 - 只會影響 `npm run dev` 時的速度 - 生產環境仍使用 Webpack --- ### 8. `Would you like to customize the import alias (@/* by default)?` > 是否要自訂 **import 路徑別名 alias**？ #### ✅ 選 Yes： - CLI 會再問你輸入別名（例如 `@/*`）， - 會幫你自動建立 `paths` 設定（在 `tsconfig.json` 或 `jsconfig.json`） #### ❌ 選 No： - 不會設定別名，之後你手動寫 `../../components/...` 等麻煩路徑。 --- ## 🔧 若選擇 "No"，之後如何補上 import alias？ ### ▶ 1. 找出設定檔 如果你是： - 用 TypeScript → 修改 `tsconfig.json` - 用 JavaScript → 修改 `jsconfig.json` ### ▶ 2. 修改範例如下（代表 `@` 指向 `src` 資料夾）： ```jsonc { "compilerOptions": { "baseUrl": ".", // 專案根目錄 "paths": { "@/*": ["src/*"] } } } ``` ### ▶ 3. 如果你沒使用 `src/`，就寫： ```jsonc { "compilerOptions": { "baseUrl": ".", "paths": { "@/*": ["*"] } } } ``` --- ### 📁 目錄結構對照範例 若你有勾選使用 `src/`，專案結構可能如下： ``` demo-next/ ├── src/ │ ├── app/ │ ├── components/ │ └── ... ├── tsconfig.json ``` 則你就能寫這樣的路徑： ```ts import { Header } from '@/components/Header' ``` --- ## ✅ 總結：建立流程與 alias 設定對照
功能說明
是否設定 alias (`@`)`create-next-app` 最後一個選項
若選否，日後可透過 `ts/jsconfig` 設定✅ 很簡單，加一段 `"paths"` 即可
是否需要設定 `next.config.js`通常不需要（除非使用 webpack plugin）
--- # 【Next.js】專案結構與檔案說明 以下是根據你提供的 Next.js 專案結構，整理出各資料夾與檔案的用途與說明： --- ### 📁 專案結構與說明表格
路徑 / 檔案類型說明
`.next/`資料夾Next.js **build 輸出資料夾**，會在 `next build` 時產生。內含編譯後的 server 與靜態資源。可部署至伺服器。
├── `server/`資料夾Server-side compiled files（如 SSR 頁面、API Routes）。
├── `static/`資料夾靜態產出資源（例如圖片、CSS、JS 等）。
├── `cache/`資料夾編譯過程中的 cache，提高二次編譯速度。
├── `build-manifest.json`JSON 檔案描述每個頁面對應的 JS chunk，供 runtime 載入使用。
├── `routes-manifest.json`JSON 檔案儲存頁面與路由資訊的映射表。
├── `prerender-manifest.json`JSON 檔案與預先產生的頁面（SSG）有關，例如 `getStaticProps` 結果。
`node_modules/`資料夾安裝的 npm 套件。
`public/`資料夾放置**靜態資源**（如圖片、SVG），透過 `/` 路徑對外公開，例如：`public/globe.svg` → `/globe.svg`。
`src/app/`資料夾使用 **App Router 架構** 的主要入口，代表新架構（取代 `pages/` 目錄）。
├── `layout.tsx`React 元件每個 route 的共同 Layout 元件。App Router 中不可或缺。
├── `page.tsx`React 元件對應 `/` 路由的頁面內容（Home）。
├── `globals.css`CSS 檔案全域 CSS，需在 `layout.tsx` 中引入。
`favicon.ico`圖示檔案網站 favicon，會自動用在 `` 中。
`.gitignore`設定檔Git 忽略檔案清單。通常會包含 `.next/`、`node_modules/`。
`next-env.d.ts`TS 宣告Next.js 產生的 type 設定檔，自動加入必要的 TypeScript 型別。
`next.config.ts`設定檔Next.js 專案設定檔，支援自訂建置、路徑、Plugin 等功能。
`package.json` / `package-lock.json`設定檔npm 套件定義與鎖定檔。記錄所有依賴與版本。
`postcss.config.mjs`設定檔PostCSS 設定，通常與 TailwindCSS 搭配使用。
`README.md`說明檔專案說明、安裝方式、開發資訊等。
`tsconfig.json`設定檔TypeScript 專案設定，例如路徑 alias、編譯選項等。
--- ### 📌 重點說明
分類重點
**重要目錄**`src/app/`（使用 App Router 架構）、`public/`（靜態資源）、`.next/`（build 輸出）
**重要設定檔**`next.config.ts`、`tsconfig.json`、`postcss.config.mjs`
**App Router 必備**`layout.tsx` 是必要頁面組件，類似傳統 `_app.tsx + _document.tsx`
**部署時可忽略**`node_modules/`、`.next/cache`、`.gitignore`
--- ## 說明layout.tsx 與 page.tsx 關係 `layout.tsx` 與 `page.tsx` 是 Next.js 13+（App Router 架構）中，兩個**核心檔案**，分別扮演不同但互補的角色。 --- ## 🧱 簡單說明
檔案用途載入頻率比喻
`layout.tsx`定義頁面結構與共用 UI（像是外框）只載入一次（不會重複重建）「建築物的骨架」
`page.tsx`定義實際頁面內容每個頁面都會重新載入「房間的內容、家具、住戶」
--- ## 🧭 目錄架構範例 ```bash app/ ├── layout.tsx # 所有頁面的共用 Layout ├── page.tsx # / 路徑的首頁內容 ├── about/ │ ├── layout.tsx # 僅 /about 使用的 layout │ └── page.tsx # /about 的內容 ``` --- ## 🧩 關係與行為 1. **一個 layout 對應多個 page** - 例如 `app/layout.tsx` 包住所有頁面：`/`, `/about`, `/contact` 2. **嵌套 layout** - 子資料夾可有自己的 `layout.tsx`，會**包在上層 layout 裡** 3. **layout 不會因為切換 page 被卸載** - 可以放在 `Header`, `Sidebar`, `Footer` 等共用 UI 元件，效能更佳 4. **page.tsx 是實際的頁面入口** - 每個 URL 都需要一個 `page.tsx` 來當作入口點 --- ## 📦 實際範例 ### `app/layout.tsx` ```tsx export default function RootLayout({ children }: { children: React.ReactNode }) { return (
共用導覽列
{children}
) } ``` ### `app/page.tsx` ```tsx export default function HomePage() { return

這是首頁內容

} ``` 👉 此時 `HomePage` 內容會被注入進 `layout.tsx` 的 `{children}` 中。 --- ## 🔁 一圖總結 ``` layout.tsx ├── Header ├──
│ └── page.tsx 的內容 └── Footer ``` --- ## ✅ 補充：layout.tsx 特性
特性是否支援備註
支援 `loading.tsx`✅當子頁面在載入時顯示 loading UI
支援 `error.tsx`✅包裹此 layout 的錯誤畫面
支援 `metadata` 設定✅可以定義 title、description 等
自動 caching✅layout 有自動快取，非動態頁效能極佳
--- 需要我幫你畫出 layout/page 的巢狀結構流程圖或建立範本專案也可以說一聲。 # 【Next.js】路由機制 Next.js 使用檔案結構（**File System Routing**）搭配 `page.tsx`（或 `page.jsx`）自動產生路由，這是 Next.js 的一大特色，讓你**不需手動寫 route config**，只要建立檔案與資料夾就能對應 URL。 --- ## 🗂️ Next.js App Router 的路由機制（以 `app/` 為根） ```bash app/ ├── page.tsx → / ├── about/ │ └── page.tsx → /about ├── blog/ │ ├── page.tsx → /blog │ └── [slug]/ │ └── page.tsx → /blog/hello、/blog/123 ├── dashboard/ │ ├── layout.tsx → 包住 dashboard 所有子路由 │ ├── page.tsx → /dashboard │ └── settings/ │ └── page.tsx → /dashboard/settings ``` --- ## 🔑 路由對應邏輯
檔案名稱對應路徑 (URL)說明
`app/page.tsx``/`首頁
`app/about/page.tsx``/about`靜態路由
`app/blog/[slug]/page.tsx``/blog/:slug`動態路由
`app/dashboard/page.tsx``/dashboard`支援巢狀路由
`app/dashboard/settings/page.tsx``/dashboard/settings`巢狀子頁面
--- ## 📌 動態路由（Dynamic Routes） ### 範例： ```bash app/product/[id]/page.tsx ``` 訪問 `/product/123`、`/product/abc` 都會進到這個頁面。 ### 如何在 component 中取得參數： ```tsx import { useParams } from 'next/navigation' export default function ProductPage() { const params = useParams() return
商品 ID：{params.id}
} ``` --- ## ⛓️ 巢狀路由與 Layout 配合 ```bash app/ ├── layout.tsx // 全站 layout ├── dashboard/ │ ├── layout.tsx // dashboard 專屬 layout │ └── settings/ │ └── page.tsx // 會套用兩層 layout ``` ➡ 這樣 `/dashboard/settings` 的畫面會被兩層 layout 包起來。 --- ## 🚫 注意事項
限制說明
`page.tsx` 為必要頁面進入點每個路由至少需要一個 `page.tsx`
不支援動態 catch-all `*`請使用 `[...slug]`
`app/` 下不能使用 `pages/`App Router 與 Pages Router 不能共存
--- ## ✨ 小技巧
目的實作方式
動態路由（product/:id）`app/product/[id]/page.tsx`
可選參數（可有可無）`app/product/[[id]]/page.tsx`
Catch-all 路由`app/docs/[...slug]/page.tsx`
自定 metadata（如 title）使用 `export const metadata`
--- ## ✅ 結論 Next.js 的路由系統基於檔案結構： - **目錄名代表 URL 路徑** - **`page.tsx` 是每個路由的「入口」** - **巢狀結構代表巢狀路由** - **使用 `[]` 定義動態路由** --- 如果你有具體的頁面結構想設計，我可以幫你列出完整檔案路徑與對應 URL 對照表。 # 【Next.js】路由機制(動態) 在 Next.js 中，\*\*Dynamic Routes（動態路由）\*\*允許你根據 URL 中的參數來動態建立頁面，這對於像是部落格文章、使用者頁面、商品詳細頁等非常有用。 --- ## 🗂️ 基本概念 在 Next.js 中，**每個檔案都對應一個路由**。當你在 `app/` 或 `pages/` 目錄中使用 **方括號（\[param\]）** 定義檔案名稱時，就代表建立了一個動態路由。 例如： ``` pages/ └── blog/ └── [slug].tsx ``` 這樣的結構可以對應： - `/blog/hello-world` - `/blog/my-second-post` 在 `app/` 目錄中則會是： ``` app/ └── blog/ └── [slug]/ └── page.tsx ``` --- ## 💡 Dynamic Routes 實作（`app/`） ### 1️⃣ 建立檔案：`app/post/[id]/page.tsx` ```JavaScript interface PageProps { params: { id: string } } export default function Post({ params }: PageProps) { return

Post ID: {params.id}

} // { params }: PageProps // { params } => 解構，取出物件的 params 屬性 // :PageProps typescript宣告型別 // 直接簡化成 { params }: { params: { id: string } } ``` --- ## 🔁 多層動態路由 支援巢狀結構，例如： ``` app/ └── user/ └── [userId]/ └── post/ └── [postId]/ └── page.tsx ``` 訪問路徑 `/user/1/post/10` 對應的 `params` 為： ```ts params: { userId: '1', postId: '10' } ``` --- ## ✅ Catch-all 路由（捕捉所有） 你可以使用 `[...slug]` 來捕捉多層級路徑： - `app/products/[...slug].tsx` 會匹配 `/products/a`、`/products/a/b/c` ```tsx interface PageProps { params: { slug?: string[]; }; } export default function ProductPage({ params }: PageProps) { return (

Products Page

{JSON.stringify(params.slug)}
); } ``` 如果要可選，可用 `[[...slug]]` 表示非必要。 --- ## 📌 小結
類型說明範例
`[param]`基本動態路由`/post/1` → `[id].tsx`
`[...param]`捕捉多層路徑（Catch-all）`/docs/a/b` → `[...slug].tsx`
`[[...param]]`可選 catch-all（Optional）`/docs` or `/docs/a`
--- 若你想看實際範例或搭配 `getStaticPaths`、`generateStaticParams` 使用，也可以提出，我可以補上。需要嗎？ # 【Next.js】not-found (404) 在 Next.js 中，`not-found` 頁面是用來顯示 **404 頁面**（找不到頁面）用的。從 Next.js 13（App Router）開始，你可以更靈活地**自訂與觸發 not-found**。 --- ## 🧭 `not-found` 頁面用途
功能說明
預設 404 頁面訪問不存在的路由時自動顯示
自訂 not-found你可以定義自訂的樣式與內容
手動觸發 404在伺服器邏輯中，條件不符時主動觸發 `notFound()`
--- ## 📁 App Router (`app/` 目錄) 中的使用方式 ### 📌 1. 建立 `not-found.tsx` 頁面 放在你想處理的路由資料夾中，例如： ``` app/ ├── blog/ │ ├── [slug]/ │ │ ├── page.tsx │ │ └── not-found.tsx 👈 對應 `/blog/[slug]` 找不到時 ``` ### 📦 `app/blog/[slug]/not-found.tsx` ```tsx export default function NotFound() { return (

這篇文章不存在

回首頁
); } ``` --- ### 📌 2. 在 `page.tsx` 中觸發 `notFound()` ```tsx import { notFound } from 'next/navigation'; export default function BlogPost({ params }: { params: { slug: string } }) { const validSlugs = ['a', 'b', 'c']; if (!validSlugs.includes(params.slug)) { notFound(); // 👈 主動觸發 404 頁面 } return

Blog: {params.slug}

; } ``` --- ## 📁 Global Not Found Page 如果你在 `app/not-found.tsx` 建立，這就是全站共用的 404 頁面。 ``` app/ ├── not-found.tsx 👈 對應任何未定義頁面 ``` --- ## 📦 `app/not-found.tsx` 範例 ```tsx export default function GlobalNotFound() { return (

404 - 頁面找不到

您訪問的頁面可能已被移除或從未存在。

回首頁
); } ``` --- ## 🧪 測試方式
測試路徑預期結果
`/blog/xxx`若 `xxx` 不存在 → 觸發 `notFound()`
`/some/random/page`找不到任何匹配路由 → global 404
--- ## ✅ 小結
功能用法
定義 not-found 頁面在 `app/***/not-found.tsx` 中建立
全域 fallback 頁面在 `app/not-found.tsx`
手動觸發 404使用 `notFound()` 函式
# 【Next.js】Private Folders 在 Next.js 中，\*\*Private Folders（私有資料夾）\*\*是指： > 🔒 **不會被當作路由、自動產生頁面或靜態資源的資料夾**。 > 這些資料夾的名稱 **開頭是底線 `_` 或雙底線 `__`**，也就是說： ### ✅ 資料夾名稱開頭為 `_` 或 `__` ⇒ Next.js 會自動忽略它 --- ## 🔍 什麼是 Private Folders？ 這是 Next.js 的一項慣例（convention），用來 **隔離你不想當作頁面處理的輔助程式碼或元件檔案**。 --- ## 📁 使用範例 假設你有以下結構： ``` app/ ├── page.tsx ├── _utils/ ← ✅ 不會當成路由 │ └── formatter.ts ├── __tests__/ ← ✅ 不會當成路由 │ └── page.test.tsx ``` 這些 `_utils/`、`__tests__/` 都是 **Private Folders**： - **不會產生 `/utils` 路由** - **不會被包含在 build 出來的頁面中** - **適合放測試、工具、常數、hooks 等程式碼** --- ## ✅ 實用用途
資料夾名稱用途範例
`_utils/`放工具函式（e.g. dateFormat）
`_hooks/`放自訂 React Hook
`__tests__/`放單元測試
`__mocks__/`放 Jest mock 資料
--- ## 🧠 注意事項
行為說明
✅ 允許 `import` 使用Private folders 裡的檔案仍然可以被引用
❌ 不會產生 URL不會出現像 `/__tests__` 這種頁面
✅ 適用於 `pages/` 與 `app/` 架構兩種路由系統都支援
⚠️ 無法自訂規則Next.js 只會根據 `_` 或 `__` 開頭自動判斷
--- ## 📝 範例：使用 `_utils/format.ts` ```ts // app/_utils/format.ts export function formatCurrency(amount: number) { return `$${amount.toFixed(2)}` } ``` ```tsx // app/products/page.tsx import { formatCurrency } from '../_utils/format' export default function ProductPage() { return

{formatCurrency(123.456)}

} ``` --- ## ✅ 小結
項目說明
命名規則資料夾名稱開頭為 `_` 或 `__`
功能不產生頁面、不加入 build 路由
適合用途工具、hook、測試、mock、常數
是否能 import✅ 可以被引用使用
--- 這是一個非常好也非常細緻的問題，牽涉到 JavaScript / TypeScript 社群和工具生態中的 **命名慣例（naming conventions）**，並不是 Next.js 特有的規定，而是社群共識。 --- ## 🔍 TL;DR 結論
命名形式用途 / 慣例來源
`_folder`🔒 私有資料夾，Next.js 慣例（前綴式）Next.js、社群通用慣例
`__tests__`✅ 測試資料夾，Jest 標準結構（雙底線前後）[Jest 官方](https://jestjs.io/docs/structure)
`__mocks__`✅ Mock 資料夾，Jest 標準Jest
`_filename.ts`私有或輔助用檔案（非主模組）Node / TypeScript 社群
--- ## ✅ 單底線 `_`：**一般表示私有或特殊用途** - `_utils/`、`_hooks/`、`_internal/` - 表示：**這不是一個路由，也不是 API 端點，只是輔助邏輯用** 這種用法來自許多框架（Django、Rails、Node.js）與社群習慣。 --- ## ✅ 雙底線 `__`：**通常是工具/測試框架的保留命名** 來自 **Jest、React Native、Metro Bundler 等工具**： - `__tests__` → Jest 會自動找出來執行單元測試 - `__mocks__` → Jest 用來定義自動 mock 資料 - `__snapshots__` → Jest 的 snapshot 測試檔案 👉 **雙底線前後一致**，通常代表「這是特殊目的目錄」，會被工具偵測與處理。 --- ## 🧠 命名語意總整理
命名語意常見用途
`_名稱`私有 / 忽略 / 特殊用途（Next.js 慣例）`_utils`, `_internal`, `_api`
`__名稱__`測試工具專用`__tests__`, `__mocks__`
無底線公開模組 / 頁面 / API 等`products`, `user`, `api`
--- ## ✅ Next.js 怎麼處理這些命名？
資料夾名稱是否會轉成路由？用途建議
`products/`✅ 是頁面
`_products/`❌ 否工具 / 非頁面模組
`__tests__/`❌ 否單元測試、快照測試用
--- ## 📌 延伸知識：為何不是 `_tests/` 而是 `__tests__`？ 這來自 **Unix / Bash 與正規表達式處理的傳統**： - `__tests__` 這種明確結構更容易在工具中用 glob 匹配，如： ```bash find . -name '__tests__' jest "**/__tests__/**/*.test.tsx" ``` 這是 Jest 與 Babel 的官方推薦格式。 --- ## ✅ 總結
命名類型意圖 / 工具支援
`_xxx/`Next.js 私有目錄，僅開頭底線
`__xxx__/`Jest 風格目錄，工具自動識別處理
`_xxx.ts`單一檔案私有語意
--- ## 此外通常utils 其他分類資料夾只要不在app 下就不會產生路由，也是一種常用的方法 [![image-1753426662774.png](https://bookstack.treemanou.com/uploads/images/gallery/2025-07/scaled-1680-/WjkEchrWj4prc83H-image-1753426662774.png)](https://bookstack.treemanou.com/uploads/images/gallery/2025-07/WjkEchrWj4prc83H-image-1753426662774.png) # 【Next.js】Route Groups 在 Next.js 的 **App Router** 架構中，`Route Groups` 是一個非常實用的功能，用來： > ✅ **分組路由檔案，但不會影響 URL 路徑或頁面路由**。 --- ## 🗂️ Route Groups 是什麼？ **語法：用括號 () 包住資料夾名稱** 例如： ``` app/ ├── (dashboard)/ │ └── analytics/ │ └── page.tsx ← URL: /analytics（不會變成 /dashboard/analytics） ``` ### ✅ 路徑中的 `(dashboard)` 不會出現在網址上 但它**可以讓你組織頁面、套用 layout**。 --- ## 📌 使用場景
使用目的說明
**組織頁面結構**讓你的 app 資料夾更乾淨、更有結構
**不同區段共用不同 layout**例如 (marketing)、(admin)、(auth) 區塊使用不同 layout
**不污染 URL**URL 不包含 group 名稱，例如 `(admin)/users` → `/users`
--- ## ✅ 範例 1：基本 Route Group ``` app/ ├── (marketing)/ │ └── home/ │ └── page.tsx ``` **訪問路徑：** `/home` ✅ **不會是：** `/marketing/home` ❌ --- ## ✅ 範例 2：共用 layout 的 Route Group ``` app/ ├── (auth)/ │ ├── layout.tsx ← auth 區塊專用 layout │ ├── login/ │ │ └── page.tsx ← `/login` │ └── register/ │ └── page.tsx ← `/register` ``` 👉 `/login` 和 `/register` 頁面都會套用 `(auth)/layout.tsx` --- ## ✅ 範例 3：巢狀 Route Groups ``` app/ ├── (admin)/ │ ├── layout.tsx │ └── users/ │ └── page.tsx ← `/users` ├── (marketing)/ │ └── about/ │ └── page.tsx ← `/about` ``` 每個 group 都可以有自己專屬的 `layout.tsx`，但網址仍保持扁平化。 --- ## 💡 搭配 `not-found.tsx`、`error.tsx`、`loading.tsx` 你可以在 group 中設： ``` app/ ├── (admin)/ │ ├── layout.tsx │ ├── not-found.tsx │ ├── error.tsx │ └── dashboard/ │ └── page.tsx ``` 這樣 group 中的所有路由都會共用這些錯誤/狀態處理頁。 --- ## 🚫 Route Groups 的注意事項
問題說明
Group 名稱不能用 `/` 或 `-`只能用括號與英文小寫（無實際路徑名稱）
不能與實體 URL 混用`app/(admin)/users` 是 `/users`，**不是** `/admin/users`
沒有 `generateStaticParams()`Route Group 自身不是 route，不能設 `page.tsx`
--- ## ✅ 小結
特性說明
語法`(group-name)/`
是否會影響 URL？❌ 不會，純粹是分組與結構管理用途
支援 layout 嗎？✅ 支援，可針對 group 套用專屬 layout
適合什麼用途？管理大型專案，區分功能區域（如 admin/auth/marketing）
--- # 【Next.js】Layout 太好了！以下是為「Next.js 初學者」量身打造的教學文章，主題為： # 🔍 Next.js App Router 中 `layout.tsx`、`page.tsx`、`children` 的邏輯與實作 --- ## 🧠 為什麼要了解這三個東西？ 在 Next.js 的 App Router 架構中，整個畫面的內容是由許多層「外殼（layout）」與「內頁（page）」所組合而成。而這個組合的核心，就是這三個角色： - `layout.tsx`：整體框架的「容器」 - `page.tsx`：實際對應到網址的「頁面內容」 - `children`：layout 內部接收的下一層內容（可能是 page，也可能是下一層 layout） --- ## 🔧 這三者的關係是什麼？ 你可以想像畫面組成就像是便當盒： - `layout.tsx` 就是便當盒（框架） - `page.tsx` 是便當裡的菜色（內容） - `children` 是 layout.tsx 中的佔位符，用來「放內容的地方」 👉 換句話說： > **page.tsx 的畫面內容，會自動傳給上層 layout.tsx 中的 `children` 來顯示** --- ## 🧱 結構範例 ```txt app/ ├── layout.tsx ← 全站框架 Layout ├── page.tsx ← 首頁 `/` ├── about/ │ └── page.tsx ← `/about` 頁面 ``` --- ## 📦 layout.tsx 實際程式碼 ```tsx export default function RootLayout({ children }: { children: React.ReactNode }) { return (
這是全站共用的 Header
{children}
{/* 這裡會被 page.tsx 的內容填進來 */} ); } ``` --- ## 📦 page.tsx 實際程式碼 ```tsx export default function HomePage() { return
這是首頁的內容
; } ``` --- ## 💡 瀏覽 `/` 時會發生什麼事？ 1. Next.js 根據 URL `/` 找到 `app/page.tsx` 2. 找到對應的 `layout.tsx` 作為頁面外框 3. 把 `page.tsx` 的內容當作 `children` 傳給 `layout.tsx` 4. 畫面最終呈現： ```html
這是全站共用的 Header
這是首頁的內容
``` --- ## 🔁 多層 layout 怎麼辦？ 可以有巢狀 layout 結構，例如： ```txt app/ ├── layout.tsx ← 全站 layout ├── (admin)/ │ ├── layout.tsx ← admin 專區 layout │ └── dashboard/ │ └── page.tsx ← `/dashboard` 頁面 ``` 流程如下： 1. `dashboard/page.tsx` 被載入 2. 它被傳給 `admin/layout.tsx` 的 `children` 3. 然後再傳到最外層 `app/layout.tsx` 的 `children` 4. 最終包成一整頁畫面 --- ## ✅ 重點整理
元素說明
`layout.tsx`定義頁面外框、接收 `children`
`page.tsx`對應 URL 的實際頁面內容
`children`layout.tsx 的佔位符，用來顯示下層內容
傳遞邏輯順序`page.tsx` → 傳給 → `layout.tsx` → 再往上層
--- ## 📌 初學者常見疑問 ### ❓ Q1: `children` 是誰傳給 layout.tsx 的？ A: 是 Next.js 自動傳進來的，不需要自己傳。 --- ### ❓ Q2: 可以有多個 layout.tsx 嗎？ A: 可以。每一層目錄都可以定義自己的 layout.tsx，形成巢狀包裝結構。 --- ### ❓ Q3: 如果我不寫 layout.tsx 會怎樣？ A: 畫面會照樣顯示，但你就無法包共用的元件（像是 Header、Footer、Provider）。 --- ## ✅ 建議實作順序 1. 建立 `app/layout.tsx`：放 header/footer 2. 建立 `app/page.tsx`：顯示首頁 3. 建立 `app/about/page.tsx`：新增新頁面 4. 觀察 `children` 如何把 page 內容塞進 layout --- 以下是這篇教學的視覺化圖解，讓初學者更清楚了解 `layout.tsx`、`page.tsx`、`children` 在 Next.js App Router 中是如何串接的。 --- ## 🖼️ 圖解：`layout.tsx` 如何包住 `page.tsx` ``` Next.js 組合畫面邏輯流程 ┌─────────────────────────────┐ │ app/layout.tsx │ │ ┌─────────────────────────┐ │ │ │ │ │ │ │ │ │ │ │ ┌───────────────┐ │ │ │ │ │
│ │ │ │ │ └───────────────┘ │ │ │ │ ┌───────────────┐ │ │ │ │ │ {children} │◄────┼─┐ ← 自動注入 │ │ └───────────────┘ │ │ │ │ ┌───────────────┐ │ │ │ │ │