Next.js App Router 專家
概述
針對 Next.js App Router 開發的專業指南,包括頁面建立、動態路由、巢狀佈局、伺服器/客戶端元件最佳化,以及 ERP 角色型儀表板。
核心能力
1. 頁面建立(/app/.../page.tsx)
規則:
- 預設使用伺服器元件(不使用 'use client' 指令)
- 使用
fetch()或 ORM 查詢直接進行非同步資料擷取 - 初始資料載入不使用
useEffect - 使用
Suspense邊界處理載入狀態 - 透過
generateMetadata()設定 SEO 元資料
範本:
// app/dashboard/page.tsx
import { Suspense } from 'react';
import { TaskList } from '@/components/TaskList';
import { TaskListSkeleton } from '@/components/TaskListSkeleton';
export const metadata = {
title: '儀表板',
description: '您的任務管理儀表板',
};
export default async function DashboardPage() {
const tasks = await fetchTasks();
return (
<main className="p-4">
<h1>儀表板</h1>
<Suspense fallback={<TaskListSkeleton />}>
<TaskList initialTasks={tasks} />
</Suspense>
</main>
);
}
2. 動態路由([slug]/page.tsx)
使用時機:
- 學生個人檔案:
app/students/[studentId]/page.tsx - 任務詳細資料:
app/tasks/[taskId]/page.tsx - 課程頁面:
app/courses/[courseId]/page.tsx
規則:
- 從
params屬性(唯讀)中提取參數 - 使用
generateMetadata()進行 SEO - 使用
not-found.tsx處理 404
範本:
// app/students/[studentId]/page.tsx
import { notFound } from 'next/navigation';
type Params = Promise<{ studentId: string }>;
export async function generateMetadata({ params }: { params: Params }) {
const { studentId } = await params;
const student = await getStudent(studentId);
if (!student) return { title: '找不到學生' };
return {
title: `${student.name} - 學生個人檔案`,
};
}
export default async function StudentProfile({ params }: { params: Params }) {
const { studentId } = await params;
const student = await getStudent(studentId);
if (!student) notFound();
return <StudentProfileView student={student} />;
}
3. 平行路由(@folder)
使用時機:
- 儀表板變體:
app/dashboard@(admin|teacher)/page.tsx - 分割佈局:
app/settings@(user|organization)/layout.tsx
範本:
// app/dashboard/@admin/page.tsx - 管理員儀表板
export default function AdminDashboard() {
return <AdminPanel />;
}
// app/dashboard/@teacher/page.tsx - 教師儀表板
export default function TeacherDashboard() {
return <TeacherPanel />;
}
4. 佈局與模板
根佈局(app/layout.tsx):
import { Providers } from '@/components/Providers';
import './globals.css';
export const metadata = {
title: 'Todo Evolution',
description: '教育用任務管理',
};
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="zh-TW">
<body>
<Providers>{children}</Providers>
</body>
</html>
);
}
巢狀佈局(app/dashboard/layout.tsx):
import { DashboardNav } from '@/components/DashboardNav';
export default function DashboardLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<div className="flex min-h-screen">
<DashboardNav />
<main className="flex-1 p-6">{children}</main>
</div>
);
}
模板(app/tasks/template.tsx):
// 導航時重新執行,保留表單狀態
export default function TasksTemplate({ children }: { children: React.ReactNode }) {
return (
<div className="bg-gray-50 min-h-screen">
<header className="bg-white shadow">
<h1>任務</h1>
</header>
{children}
</div>
);
}
5. 伺服器元件 vs 客戶端元件
伺服器元件用於:
- 資料擷取
- 直接資料庫查詢
- 靜態內容
- 僅限伺服器的操作
客戶端元件('use client')用於:
- 瀏覽器 API(
window、localStorage) - 事件處理器(
onClick、onSubmit) - React 鉤子(
useState、useEffect) - 狀態管理(Zustand、Redux)
- 互動性
// 伺服器元件(預設)
export default async function TaskList() {
const tasks = await fetchTasks(); // 直接資料庫查詢
return <div>{tasks.map(/* ... */)}</div>;
}
// 客戶端元件
'use client';
import { useTaskStore } from '@/store/tasks';
export function TaskFilter() {
const { filter, setFilter } = useTaskStore();
return <button onClick={() => setFilter('all')}>所有任務</button>;
}
6. ERP 角色型頁面
角色守衛:
// app/admin/page.tsx
import { requireRole } from '@/lib/auth';
import { redirect } from 'next/navigation';
export default async function AdminPage() {
const session = await getSession();
if (session?.role !== 'admin') {
redirect('/unauthorized');
}
return <AdminDashboard />;
}
KPI 儀表板(Recharts):
'use client';
import { BarChart, Bar, XAxis, YAxis, Tooltip } from 'recharts';
export function TaskKPIChart({ data }: { data: TaskStats[] }) {
return (
<BarChart width={600} height={300} data={data}>
<XAxis dataKey="date" />
<YAxis />
<Tooltip />
<Bar dataKey="completed" fill="#22c55e" />
</BarChart>
);
}
7. 錯誤與載入狀態
錯誤邊界(error.tsx):
'use client';
export default function Error({
error,
reset,
}: {
error: Error & { digest?: string };
reset: () => void;
}) {
return (
<div>
<h2>發生錯誤!</h2>
<button onClick={reset}>重試</button>
</div>
);
}
載入狀態(loading.tsx):
export default function Loading() {
return <div className="animate-pulse">載入中...</div>;
}
// 或搭配 Suspense:
export default async function Page() {
return (
<Suspense fallback={<Loading />}>
<Content />
</Suspense>
);
}
8. shadcn/ui 整合
安裝:
npx shadcn@latest add button card input dialog
在伺服器元件中使用:
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader } from '@/components/ui/card';
export default async function TaskPage() {
const tasks = await getTasks();
return (
<Card>
<CardHeader>任務</CardHeader>
<CardContent>
{tasks.map(task => (
<div key={task.id}>{task.title}</div>
))}
</CardContent>
</Card>
);
}
工作流程決策樹
使用者請求 → 分析 → 實作路徑
-
「建立儀表板/管理員頁面」 → 使用
page.tsx的伺服器元件 → 非同步資料擷取 → 如需導航則加入layout.tsx -
「動態學生個人檔案」 → 建立
[studentId]/page.tsx→ 提取參數 → 加入generateMetadata()→ 如有需要建立not-found.tsx -
「加入共用佈局」 → 在目標資料夾中建立
layout.tsx→ 如有需要以 Provider 包裹 → 保留 children 渲染 -
「加入表單」 → 使用
'use client'元件 → 使用 useState 處理表單資料 → 使用伺服器動作或 API 路由提交 -
「KPI 圖表/分析」 → 使用
'use client'搭配 Recharts → 父層使用伺服器元件並擷取資料 → 將資料作為 props 傳遞
品質檢查清單
在標記任務完成前:
- TypeScript 嚴格模式已啟用
- 預設使用伺服器元件
- 僅在必要時使用
'use client' - 使用
generateMetadata()進行 SEO - 為非同步資料使用 Suspense 邊界
- 在需要的地方設有錯誤邊界(
error.tsx) - 無水合不匹配
- 效能最佳化(無阻塞渲染)
- 行動裝置優先的響應式設計
- 無障礙(ARIA 標籤、鍵盤導航)
常見模式
模式 1:伺服器元件與客戶端元件混合
// 伺服器元件
export default async function Page() {
const tasks = await fetchTasks();
return <TaskList tasks={tasks} />; // 客戶端元件提供互動性
}
'use client';
function TaskList({ tasks }: { tasks: Task[] }) {
const [filter, setFilter] = useState('all');
const filtered = tasks.filter(/* ... */);
return <div>{filtered.map(/* ... */)}</div>;
}
模式 2:用於組織的路由群組
app/
(marketing)/ # 群組:無 URL 區段
about/page.tsx
contact/page.tsx
(dashboard)/ # 群組:無 URL 區段
layout.tsx
page.tsx
模式 3:API 路由(路由處理器)
// app/api/tasks/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
const tasks = await db.query.tasks.findMany();
return NextResponse.json(tasks);
}
export async function POST(request: Request) {
const body = await request.json();
const task = await createTask(body);
return NextResponse.json(task, { status: 201 });
}
觸發範例
- 「建立儀表板頁面」→ 產生
app/dashboard/page.tsx並使用伺服器元件 - 「動態學生個人檔案路由」→
app/students/[studentId]/page.tsx搭配 params 與 metadata - 「加入共用佈局」→
app/dashboard/layout.tsx並搭配 children - 「包含圖表的管理員面板」→ 伺服器元件 + 客戶端圖表元件
- 「建立登入頁面」→
'use client'表單元件 + API 路由 - 「自訂 404 頁面」→
app/not-found.tsx - 「處理錯誤」→
app/dashboard/error.tsx
參考資料
進階模式請參閱 references/app-router-patterns.md,路由處理器範例請參閱 references/api-routes.md。