next-best-practices

Next.js 最佳實務

撰寫或審查 Next.js 程式碼時，請套用以下規則。

檔案慣例

請參閱 file-conventions.md 了解：

• 專案結構與特殊檔案
• 路由區段（動態、全部捕獲、群組）
• 平行與攔截路由
• v16 中介軟體更名（middleware → proxy）

RSC 邊界

偵測無效的 React Server Component 模式。

請參閱 rsc-boundaries.md 了解：

• 非同步客戶端元件偵測（無效）
• 不可序列化 props 偵測
• Server Action 例外

非同步模式

Next.js 15+ 非同步 API 變更。

請參閱 async-patterns.md 了解：

• 非同步 params 與 searchParams
• 非同步 cookies() 與 headers()
• 遷移 codemod

執行環境選擇

請參閱 runtime-selection.md 了解：

• 預設使用 Node.js 執行環境
• 何時適合使用 Edge 執行環境

指令

請參閱 directives.md 了解：

• 'use client'、'use server'（React）
• 'use cache'（Next.js）

函式

請參閱 functions.md 了解：

• 導航 hooks：useRouter、usePathname、useSearchParams、useParams
• 伺服器函式：cookies、headers、draftMode、after
• 產生函式：generateStaticParams、generateMetadata

錯誤處理

請參閱 error-handling.md 了解：

• error.tsx、global-error.tsx、not-found.tsx
• redirect、permanentRedirect、notFound
• forbidden、unauthorized（認證錯誤）
• unstable_rethrow 用於 catch 區塊

資料模式

請參閱 data-patterns.md 了解：

• Server Components vs Server Actions vs Route Handlers
• 避免資料瀑布（Promise.all、Suspense、preload）
• 客戶端元件資料擷取

路由處理器

請參閱 route-handlers.md 了解：

• route.ts 基礎
• GET 處理器與 page.tsx 的衝突
• 環境行為（無 React DOM）
• 何時使用 vs Server Actions

中繼資料與 OG 圖片

請參閱 metadata.md 了解：

• 靜態與動態中繼資料
• generateMetadata 函式
• 使用 next/og 產生 OG 圖片
• 基於檔案的中繼資料慣例

圖片最佳化

請參閱 image.md 了解：

• 一律使用 next/image 而非 <img>
• 遠端圖片設定
• 響應式 sizes 屬性
• 模糊佔位圖
• LCP 的優先載入

字型最佳化

請參閱 font.md 了解：

• next/font 設定
• Google Fonts、本機字型
• Tailwind CSS 整合
• 預載子集

打包

請參閱 bundling.md 了解：

• 與伺服器不相容的套件
• CSS 匯入（非 link 標籤）
• Polyfills（已包含）
• ESM/CommonJS 問題
• 打包分析

Scripts

請參閱 scripts.md 了解：

• next/script vs 原生 script 標籤
• 內嵌 script 需要 id
• 載入策略
• 使用 @next/third-parties 的 Google Analytics

水合錯誤

請參閱 hydration-error.md 了解：

• 常見原因（瀏覽器 API、日期、無效 HTML）
• 使用錯誤覆蓋層除錯
• 各原因的修正方式

Suspense 邊界

請參閱 suspense-boundaries.md 了解：

• 使用 useSearchParams 與 usePathname 時的 CSR 跳出
• 哪些 hooks 需要 Suspense 邊界

平行與攔截路由

請參閱 parallel-routes.md 了解：

• 使用 @slot 與 (.) 攔截器的 Modal 模式
• default.tsx 作為備用
• 使用 router.back() 正確關閉 Modal

自行託管

請參閱 self-hosting.md 了解：

• output: 'standalone' 用於 Docker
• 多實例 ISR 的快取處理器
• 哪些功能可直接使用，哪些需要額外設定

除錯技巧

請參閱 debug-tricks.md 了解：

• 用於 AI 輔助除錯的 MCP 端點
• 使用 --debug-build-paths 重建特定路由