優先級:P0(關鍵)
實作指南
路由架構
- 結構:使用
app/ 目錄。透過 app/dashboard/layout.tsx 定義路由,並回傳 {children};共享 UI 會自動嵌套在 app/layout.tsx 中。使用 loading.tsx、error.tsx 與 not-found.tsx 處理各狀態。
- 區段:使用路由群組(括號
(auth))組織功能,使其不影響 URL 路徑。使用動態路由(括號 [slug])並透過 generateStaticParams 定義靜態路徑。
- 特殊路由:使用平行路由(
@modal),將插槽加入父佈局並提供 default.tsx 作為備用。使用攔截路由((.)route)實現儀表板等進階佈局。
資料與函式
- Next.js 15+ 非同步:務必
await params: Promise、searchParams、cookies() 與 headers()。
- 安全性:使用
middleware.ts 進行邊緣端驗證與重新導向。確保所有**路由處理器(route.ts)**都已加入適當的驗證檢查。
- RSC:預設使用 React Server Components(RSC)。僅在葉節點使用
'use client' 以處理互動性(鉤子/事件)。
- 錯誤邊界:建立
app/dashboard/loading.tsx 自動將路由包裹在 Suspense 邊界中。在 error.tsx 中,使用 'use client' 並提供 reset: () => void 函式。
const theme = cookieStore.get('theme');
檔案慣例
- page.tsx:路由的 UI。
- layout.tsx:包裝子元件的共享 UI。在導航時保持持久。
- loading.tsx:用於載入狀態的 Suspense 邊界。
- error.tsx:錯誤邊界(必須是 Client Component)。
- route.ts:伺服器端 API 端點。
結構模式
- 路由群組:使用括號
(auth) 組織,不影響 URL 路徑。
- 私有資料夾:使用底線
_lib 排除在路由之外。
- 動態路由:使用括號
[slug] 或 [...slug](捕獲所有)。
最佳實踐
- RSC 邊界:確保傳遞給 Client Component 的 props 是可序列化的。請參閱 RSC 邊界與序列化。
- 平行路由(
@folder):在同一佈局中渲染多個頁面。使用 default.tsx 作為備用。
- 攔截路由(
(..)folder):在當前佈局上下文中載入路由。
- 同地放置:將元件檔案、樣式和測試保留在路由資料夾內。
- 佈局:使用根佈局(
app/layout.tsx)放置 <html> 和 <body> 標籤。
- 自託管標準
反模式
- 不要未 await 非同步 API:
params、cookies()、headers() 在 Next.js 15+ 中是 Promise;務必 await。
- 不要在樹根使用
'use client':將它放在葉節點;保持佈局和頁面為 Server Components。
- 不要在嵌套佈局中使用
<html>/<body>:只有 app/layout.tsx(根佈局)應包含它們。
- 不要遺漏
error.tsx:每個路由區段都需要一個 Client Component 錯誤邊界。