Geruyang/agent-skills-library

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 了解：

• 導航鉤子：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 Component vs Server Action vs Route Handler
• 避免資料瀑布（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 字型、本地字型
• Tailwind CSS 整合
• 預載子集

打包

參閱 bundling.md 了解：

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

指令碼

參閱 scripts.md 了解：

• next/script vs 原生 script 標籤
• 內聯指令碼需要 id
• 載入策略
• 搭配 @next/third-parties 使用 Google Analytics

水合錯誤

參閱 hydration-error.md 了解：

• 常見原因（瀏覽器 API、日期、無效的 HTML）
• 使用錯誤疊加層除錯
• 每種原因的修正方法

Suspense 邊界

參閱 suspense-boundaries.md 了解：

• 使用 useSearchParams 和 usePathname 時的 CSR 退出
• 哪些鉤子需要 Suspense 邊界

平行與攔截路由

參閱 parallel-routes.md 了解：

• 使用 @slot 和 (.) 攔截器的 Modal 模式
• 用於備用方案的 default.tsx
• 使用 router.back() 正確關閉 Modal

自架設

參閱 self-hosting.md 了解：

• 用於 Docker 的 output: 'standalone'
• 用於多執行個體 ISR 的快取處理器
• 哪些功能可行 vs 需要額外設定

除錯技巧

參閱 debug-tricks.md 了解：

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