Next.js 16 應用程式
以正確的方式建構具有獨特設計的 Next.js 16 應用程式。
重大變更(Next.js 16)
1. params 與 searchParams 現在是 Promise
這是最常見的錯誤。
// 錯誤 - Next.js 15 模式(將會失敗)
export default function Page({ params }: { params: { id: string } }) {
return <div>ID: {params.id}</div>
}
// 正確 - Next.js 16 模式
export default async function Page({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
return <div>ID: {id}</div>
}
2. 客戶端元件需要使用 use() Hook
"use client"
import { use } from "react"
export default function ClientPage({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = use(params)
return <div>ID: {id}</div>
}
3. searchParams 也是非同步的
export default async function Page({
searchParams,
}: {
searchParams: Promise<{ page?: string }>
}) {
const { page } = await searchParams
return <div>Page: {page ?? "1"}</div>
}
核心模式
專案設定
npx create-next-app@latest my-app --typescript --tailwind --eslint
cd my-app
# 新增 shadcn/ui
npx shadcn@latest init
npx shadcn@latest add button form dialog table sidebar
App Router 佈局
// app/layout.tsx
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body className="min-h-screen">
{children}
</body>
</html>
)
}
動態路由
// app/tasks/[id]/page.tsx
export default async function TaskPage({
params,
}: {
params: Promise<{ id: string }>
}) {
const { id } = await params
const task = await getTask(id)
return (
<main>
<h1>{task.title}</h1>
</main>
)
}
伺服器操作(Server Actions)
// app/actions.ts
"use server"
import { revalidatePath } from "next/cache"
export async function createTask(formData: FormData) {
const title = formData.get("title") as string
await db.insert(tasks).values({ title })
revalidatePath("/tasks")
}
// 在元件中使用
<form action={createTask}>
<input name="title" />
<button type="submit">Create</button>
</form>
API 路由
// app/api/tasks/route.ts
import { NextResponse } from "next/server"
export async function GET() {
const tasks = await db.select().from(tasksTable)
return NextResponse.json(tasks)
}
export async function POST(request: Request) {
const body = await request.json()
const task = await db.insert(tasksTable).values(body).returning()
return NextResponse.json(task, { status: 201 })
}
Middleware → proxy.ts
// proxy.ts(在 Next.js 16 中取代 middleware.ts)
import { NextRequest } from "next/server"
export function proxy(request: NextRequest) {
// 驗證檢查
const token = request.cookies.get("token")
if (!token && request.nextUrl.pathname.startsWith("/dashboard")) {
return Response.redirect(new URL("/login", request.url))
}
}
export const config = {
matcher: ["/dashboard/:path*"],
}
資料獲取
伺服器元件(預設)
// 在伺服器端執行 - 可以直接使用 async/await
async function TaskList() {
const tasks = await fetch("https://api.example.com/tasks", {
cache: "no-store", // SSR,或是
// next: { revalidate: 60 } // ISR
}).then(r => r.json())
return (
<ul>
{tasks.map(task => <li key={task.id}>{task.title}</li>)}
</ul>
)
}
客戶端元件
"use client"
import useSWR from "swr"
const fetcher = (url: string) => fetch(url).then(r => r.json())
export function ClientTaskList() {
const { data, error, isLoading } = useSWR("/api/tasks", fetcher)
if (isLoading) return <div>Loading...</div>
if (error) return <div>Error loading tasks</div>
return (
<ul>
{data.map(task => <li key={task.id}>{task.title}</li>)}
</ul>
)
}
專案結構
app/
├── layout.tsx # 根佈局
├── page.tsx # 首頁
├── globals.css # 全域樣式
├── api/ # API 路由
│ └── tasks/route.ts
├── tasks/
│ ├── page.tsx # /tasks
│ └── [id]/page.tsx # /tasks/:id
├── actions.ts # 伺服器操作
└── proxy.ts # 請求代理(middleware)
components/
├── ui/ # shadcn/ui 元件
└── task-list.tsx # 應用程式元件
lib/
├── db.ts # 資料庫連線
└── utils.ts # 工具函式
Next.js DevTools MCP
使用 next-devtools-mcp 伺服器進行執行時期診斷與開發自動化。
設定
claude mcp add next-devtools npx next-devtools-mcp@latest
或者是在 settings.json 中:
{
"mcpServers": {
"next-devtools": {
"type": "stdio",
"command": "npx",
"args": ["next-devtools-mcp@latest"]
}
}
}
可用的工具
| 工具 | 用途 |
|---|---|
init | 建立可用工具與最佳實務的上下文 |
nextjs_docs | 搜尋並擷取官方 Next.js 文件 |
browser_eval | 使用 Playwright 自動化瀏覽器測試 |
nextjs_index | 探索正在執行的 Next.js 開發伺服器 |
nextjs_call | 在正在執行的開發伺服器上執行 MCP 工具 |
upgrade_nextjs_16 | 使用 codemods 進行自動化升級 |
enable_cache_components | 為 Next.js 16 設定快取元件 |
主要使用案例
1. 取得即時錯誤
"我的 Next.js 應用程式中有哪些建置錯誤?"
"顯示目前專案中的 TypeScript 錯誤"
2. 除錯執行時期問題
"檢查開發伺服器的日誌以取得錯誤資訊"
"儀表板頁面上發生了哪些執行時期錯誤?"
3. 升級協助
"將此專案升級到 Next.js 16"
"為此應用程式啟用快取元件"
4. 文件查詢
"如何在 Next.js 16 中使用 Image 元件?"
"處理動態路由的正確方法是什麼?"
Next.js 16 MCP 端點
Next.js 16+ 在 http://localhost:3000/_next/mcp(或您的開發伺服器連接埠)公開了一個內建的 MCP 端點。devtools MCP 會自動發現並連接到正在執行的伺服器。
驗證
執行:python3 scripts/verify.py
預期結果:✓ building-nextjs-apps skill ready
如果驗證失敗
- 檢查:references/ 資料夾中是否有 nextjs-16-patterns.md
- 如果仍然失敗,請停止並回報
相關技能
- styling-with-shadcn - Next.js 應用程式的 UI 元件
- fetching-library-docs - 最新的 Next.js 文件:
--library-id /vercel/next.js --topic routing - configuring-better-auth - Next.js 應用程式的 OAuth/SSO
參考資料
- references/nextjs-16-patterns.md - 完整的 Next.js 16 模式
- references/frontend-design.md - 獨特 UI 的美學指南
- references/datetime-patterns.md - datetime-local 輸入的 UTC/時區處理