next-safe-action
概述
next-safe-action 為 Next.js 的 Server Actions 加入型別安全、輸入驗證與中介層功能。與其手動解析 FormData 並處理錯誤,只需定義 Zod 架構,就能獲得經過驗證且帶有型別的輸入,並自動處理錯誤。
使用說明
第一步:設定
npm install next-safe-action zod
// lib/safe-action.ts — 包含認證中介層的動作客戶端
import { createSafeActionClient } from 'next-safe-action'
import { auth } from '@/auth'
// 公開動作(無需認證)
export const publicAction = createSafeActionClient()
// 已認證的動作
export const authAction = createSafeActionClient({
async middleware() {
const session = await auth()
if (!session?.user) throw new Error('Not authenticated')
return { user: session.user }
},
})
第二步:定義動作
// actions/projects.ts — 型別安全的伺服器動作
'use server'
import { authAction } from '@/lib/safe-action'
import { z } from 'zod'
import { prisma } from '@/lib/db'
import { revalidatePath } from 'next/cache'
const createProjectSchema = z.object({
name: z.string().min(1).max(100),
description: z.string().max(500).optional(),
})
export const createProject = authAction
.schema(createProjectSchema)
.action(async ({ parsedInput, ctx }) => {
const project = await prisma.project.create({
data: {
...parsedInput,
ownerId: ctx.user.id,
},
})
revalidatePath('/dashboard')
return { project }
})
const updateProjectSchema = z.object({
id: z.string().uuid(),
name: z.string().min(1).max(100).optional(),
description: z.string().max(500).optional(),
status: z.enum(['active', 'archived']).optional(),
})
export const updateProject = authAction
.schema(updateProjectSchema)
.action(async ({ parsedInput, ctx }) => {
const { id, ...data } = parsedInput
// 驗證所有權
const project = await prisma.project.findFirst({
where: { id, ownerId: ctx.user.id },
})
if (!project) throw new Error('Project not found')
const updated = await prisma.project.update({
where: { id },
data,
})
revalidatePath(`/projects/${id}`)
return { project: updated }
})
第三步:在元件中使用
// components/CreateProjectForm.tsx — 搭配安全動作的表單
'use client'
import { useAction } from 'next-safe-action/hooks'
import { createProject } from '@/actions/projects'
export function CreateProjectForm() {
const { execute, result, isExecuting } = useAction(createProject)
return (
<form action={execute}>
<input name="name" placeholder="專案名稱" required />
<textarea name="description" placeholder="描述(選填)" />
{result.validationErrors && (
<div className="errors">
{Object.entries(result.validationErrors).map(([field, errors]) => (
<p key={field}>{field}: {errors?.join(', ')}</p>
))}
</div>
)}
{result.serverError && (
<p className="error">{result.serverError}</p>
)}
<button disabled={isExecuting}>
{isExecuting ? '建立中...' : '建立專案'}
</button>
</form>
)
}
指導原則
- 務必使用 Zod 架構進行輸入驗證 — 絕不接受未經伺服器驗證的客戶端資料。
- 使用中介層進行認證 — 在鏈中的每個動作執行前運行。
useActionhook 提供isExecuting、result與自動錯誤處理功能。- 搭配
useOptimisticAction使用,可實現即時 UI 回饋。 - 在資料異動後重新驗證路徑/標籤,確保 UI 與資料庫狀態同步。