Next.js 最佳實踐
選擇性閱讀規則
從以下開始:
references/senior-master-standard.md
references/usage-routing.md
references/quality-checklist.md
然後僅載入與使用者實際任務相符的繼承文件、腳本、資產或範例。
Next.js App Router 開發原則。
1. 伺服器元件 vs 用戶端元件
決策樹
是否需要...?
│
├── useState、useEffect、事件處理函式
│ └── 用戶端元件('use client')
│
├── 直接資料擷取,無互動性
│ └── 伺服器元件(預設)
│
└── 兩者都需要?
└── 拆分:伺服器父元件 + 用戶端子元件
預設情況
| 類型 | 用途 |
|---|
| 伺服器 | 資料擷取、佈局、靜態內容 |
| 用戶端 | 表單、按鈕、互動式 UI |
2. 資料擷取模式
擷取策略
| 模式 | 用途 |
|---|
| 預設 | 靜態(在建置時快取) |
| 重新驗證 | ISR(基於時間的重新整理) |
| 不儲存 | 動態(每次請求) |
資料流
| 來源 | 模式 |
|---|
| 資料庫 | 伺服器元件擷取 |
| API | 使用快取的 fetch |
| 使用者輸入 | 用戶端狀態 + 伺服器操作 |
3. 路由原則
檔案慣例
| 檔案 | 用途 |
|---|
page.tsx | 路由 UI |
layout.tsx | 共用佈局 |
loading.tsx | 載入狀態 |
error.tsx | 錯誤邊界 |
not-found.tsx | 404 頁面 |
路由組織
| 模式 | 用途 |
|---|
路由群組 (name) | 組織但不影響 URL |
平行路由 @slot | 多個同層級頁面 |
攔截路由 (.) | 模態視窗覆蓋層 |
4. API 路由
路由處理常式
| 方法 | 用途 |
|---|
| GET | 讀取資料 |
| POST | 建立資料 |
| PUT/PATCH | 更新資料 |
| DELETE | 刪除資料 |
最佳實踐
- 使用 Zod 驗證輸入
- 回傳正確的狀態碼
- 優雅地處理錯誤
- 盡可能使用 Edge 執行時期
5. 效能原則
圖片最佳化
- 使用 next/image 元件
- 為摺疊以上內容設定優先權
- 提供模糊佔位圖
- 使用響應式尺寸
套件最佳化
- 對重量級元件使用動態導入
- 基於路由的程式碼分割(自動)
- 使用套件分析器進行分析
6. 中繼資料
靜態 vs 動態
| 類型 | 用途 |
|---|
| 靜態匯出 | 固定中繼資料 |
| generateMetadata | 每條路由動態產生 |
必要標籤
- title(50-60 字元)
- description(150-160 字元)
- Open Graph 圖片
- 標準網址 (Canonical URL)
7. 快取策略
快取層級
| 層級 | 控制 |
|---|
| 請求 | fetch 選項 |
| 資料 | revalidate / tags |
| 完整路由 | 路由設定 |
重新驗證
| 方法 | 用途 |
|---|
| 基於時間 | revalidate: 60 |
| 按需 | revalidatePath / revalidateTag |
| 無快取 | no-store |
8. 伺服器操作
使用案例
最佳實踐
- 標記為 'use server'
- 驗證所有輸入
- 回傳型別化的回應
- 處理錯誤
9. 反模式
| ❌ 避免 | ✅ 應採用 |
|---|
| 到處使用 'use client' | 預設使用伺服器元件 |
| 在用戶端元件中擷取資料 | 在伺服器元件中擷取 |
| 跳過載入狀態 | 使用 loading.tsx |
| 忽略錯誤邊界 | 使用 error.tsx |
| 大型用戶端套件 | 使用動態導入 |
10. 專案結構
app/
├── (marketing)/ # 路由群組
│ └── page.tsx
├── (dashboard)/
│ ├── layout.tsx # 儀表板佈局
│ └── page.tsx
├── api/
│ └── [resource]/
│ └── route.ts
└── components/
└── ui/
切記: 伺服器元件是預設選擇,原因在此。從伺服器元件開始,僅在需要時才加入用戶端元件。
使用時機
此技能適用於執行概述中所述的工作流程或動作。
限制
- 僅在任務明確符合上述範圍時使用此技能。
- 請勿將輸出視為環境特定驗證、測試或專家審查的替代方案。
- 如果缺少必要的輸入、權限、安全邊界或成功標準,請停止並要求釐清。