Server Actions
優先級:P1(高)
[!WARNING] 如果專案使用
pages/目錄而非 App Router,請忽略此技能。
處理表單提交與突變,無需建立 API 端點。
實作指南
-
指令:始終以
'use server'開頭開始檔案或函式。使用formData.get('title')存取型別化的表單欄位。匯出非同步函式以進行突變。 -
表單處理:使用
<form>的actionprop 透過action={createPost}觸發動作。使用useFormStatus()處理pending狀態 — 在按鈕上使用disabled={pending}。使用useActionState(React 19/Next.js 15)搭配<form action={action}>處理表單狀態。 -
資料刷新:在成功的突變後,使用
revalidatePath('/')或revalidateTag('tag-name')觸發 UI 更新。 -
互動性:對於非表單觸發,使用
useTransitionHook 來處理載入 UI 並防止頁面阻塞。 -
樂觀更新:使用
useOptimistic在伺服器確認突變之前立即顯示預期的 UI 狀態。 -
安全性:清理所有來自
FormData的輸入。在每個動作內執行 身份驗證檢查(await auth())。限制檔案上傳的大小和 MIME 類型。 -
表單:
<form action={createPost}>(漸進增強在無 JS 時也能運作)。 -
事件處理器:
onClick={() => createPost(data)}。 -
等待狀態:使用
useFormStatusHook(必須在表單內渲染的元件中使用)。
P1:運算標準
1. 安全與驗證
始終使用 z.object({ 架構和 safeParse 驗證輸入,然後再進行處理。在動作內部檢查授權。請參閱安全動作範例。
2. 等待狀態
使用 useActionState(React 19/Next.js 15+)處理狀態,並使用 useFormStatus 處理按鈕載入狀態。
限制條件
- 閉包:避免在元件內部定義動作,以防止隱藏的閉包加密開銷和序列化錯誤。
- 重新導向:使用
redirect()進行成功導航;它會拋出一個 Next.js 捕獲的錯誤來處理重新導向。
反模式
- 未經驗證的 Server Action 輸入:始終在處理前使用 Zod 進行驗證。
- 跳過身份驗證檢查:在每個動作內部驗證 session/使用者,而不僅僅是中介軟體。
- 在元件內部定義動作:在
actions.ts中定義以避免閉包錯誤。 - 在 try/catch 中使用
redirect():redirect()會拋出錯誤;捕獲它會抑制重新導向。