useActionState 是 React 19 管理 Server Actions 表單狀態的 Hook,一次拿到回傳結果、交給 <form action> 的函式與 isPending。本篇說明 Server Actions 的運作方式,示範驗證失敗時保留欄位、用 useFormStatus 顯示送出狀態,並整理 redirect() 與資安問題。
想看樂觀更新與失敗回滾,請看延伸篇:React 19 useOptimistic 樂觀更新:Server Action 失敗自動回滾與 Transition 呼叫方式。
常見問題(Q&A)與程式碼範本快速跳轉
- 範本:useActionState 權限校驗與驗證失敗保留欄位的表單
- Q1:驗證失敗時表單欄位為什麼被清空?
- Q2:有了 isPending 為什麼還需要 useFormStatus?
- Q3:redirect() 為什麼掉進 try / catch?
- Q4:
"use server"函式會進客戶端 Bundle 嗎?
一、 為什麼需要 React 19 Server Actions?
1. 傳統客戶端資料異動的三個問題
1. 手動維護多個狀態與競態條件:要宣告 isLoading、error、data 三個 useState 手動切換;連續送出時舊請求可能比新請求晚回來、覆蓋畫面,漏寫 finally 時按鈕會卡在 Loading。
2. 把 "use server" 當成私有函式:React 官方文件指出 Server Functions 是對外公開的伺服器端點。以 Next.js 為例,建置時會把客戶端 Bundle 裡的函式實作換成 Action ID 參照,任何人送出相同的 HTTP POST 請求就能直接呼叫。函式內沒有檢查 Session 與資料擁有權、沒用 Zod 等工具驗證參數時,攻擊者可以直接構造請求越權修改(IDOR)。

圖:"use server" 函式可被直接以 HTTP POST 呼叫,函式內沒有檢查 Session 與參數型別就會引發越權風險
3. 驗證失敗時表單被自動清空:把函式傳給 <form action> 時,Action 執行完成後 React 會重置表單內的非受控欄位。回傳 { success: false } 也算執行完成,使用者剛填的內容會被清空,要用 useActionState 回傳 state.fields 綁到 defaultValue 才能保留。

圖:React 19 原生 <form action> 在 Action 完成後預設自動重置表單,若驗證失敗未回傳欄位快照將導致使用者輸入遺失
2. 傳統 API Route vs. React 19 Server Actions 對照

圖:傳統 CSR 需手動維護狀態並經歷二次網路往返;Server Actions 在符合條件時可用單次往返完成寫入與畫面更新
| 比較維度 | 傳統 onSubmit + fetch | Server Actions(<form action> + useActionState) |
|---|---|---|
| API 端點 | 手動建立 API 路由 | 函式換成 Action ID 參照、以 POST 呼叫(Next.js 會加密 Action ID、隨建置重新產生);端點仍公開,權限要在函式內檢查 |
| 狀態管理 | 手動維護 isLoading、error、data | const [state, formAction, isPending] = useActionState(fn, init) |
| 網路往返 | 通常 2 次(POST 寫入再 GET) | Next.js 中,Action 內呼叫 revalidatePath、updateTag 或 refresh 時,同一個回應會帶回 Action 回傳值與重新渲染的 RSC Payload |
| 漸進式增強 | Hydration 後才能送出 | Server Function 傳給 <form action> 時,表單可在 JavaScript 載入前送出;Next.js 的 Client Component 會先把 Hydration 前的送出排隊 |
| 型別安全 | 前後端手動同步型別 | 前端直接引用 Server Function 的型別簽章 |
二、 關鍵機制:Server Functions、useActionState 與 useFormStatus
1. Server Functions 與 Server Actions 的差別
- Server Functions:在檔案頂部(或非同步函式本體第一行)標記
"use server"的非同步函式。框架會建立函式參照傳給 Client Component,客戶端呼叫時由 React 對伺服器發出請求;Next.js 編譯時把客戶端 Bundle 中的實作換成「Action ID 加上派送器」的參照,實作程式碼留在伺服器端。 - Server Actions:Server Function 傳給
action或formAction屬性,或在startTransition內呼叫時的稱呼(2024 年 9 月以前,所有 Server Functions 都叫 Server Actions)。
使用者送出表單時,React 把欄位封裝成 FormData,連同 Action ID 以 HTTP POST 送到伺服器,再把回傳值(以及可選的 RSC 重繪結果)傳回客戶端更新狀態。
2. useActionState 與 useFormStatus 職責對照
useActionState 從 'react' 匯入(Canary 版叫 ReactDOM.useFormState,React 19 改名並移到 react,useFormState 已棄用);useFormStatus 從 'react-dom' 匯入:
| Hook 與匯入來源 | 呼叫位置 | 簽章與回傳值 | 職責 |
|---|---|---|---|
useActionState('react') | 渲染 <form> 的元件 | const [state, formAction, isPending] = useActionState(fn, initialState, permalink?) | 管理回傳結果(state.errors、state.fields)與 isPending;目標函式第一個參數變成 prevState,第二個才是 formData。 |
useFormStatus('react-dom') | <form> 內部的子元件(不能在宣告 <form> 的同一個元件讀取) | const { pending, data, method, action } = useFormStatus() | 讓 <SubmitButton> 等共用元件不用傳 props 就讀到父層 <form> 的送出狀態與 FormData。 |
在 Action 進行中先顯示預期結果的 useOptimistic,見開頭的延伸篇。
三、 實作範本
範本:整合 useActionState 三元組、權限校驗與驗證失敗欄位保留的完整表單
範本在 "use server" 函式內檢查 Session 與欄位格式;驗證失敗時回傳 fields 綁到 defaultValue;表單元件用 isPending,按鈕元件用 useFormStatus。
// 檔案 1:app/actions/feedback.ts
"use server";
import { revalidatePath } from "next/cache";
export interface FeedbackActionState {
success: boolean;
message: string;
errors?: {
email?: string;
content?: string;
};
// 驗證失敗時回傳使用者已填寫的內容,防止原生 <form> 自動重置清空輸入框
fields?: {
email: string;
content: string;
};
}
// 模擬伺服器端 Session 驗證與資料庫寫入
async function getAuthenticatedUser() {
// 實務上請從 HttpOnly Cookie / NextAuth / Lucia 驗證當前登入者
return { id: "usr_9821", role: "member" };
}
export async function submitFeedbackAction(
prevState: FeedbackActionState,
formData: FormData
): Promise<FeedbackActionState> {
// 1. 強制驗證身分權限(每個 "use server" 匯出函式皆為公開 POST 端點)
const user = await getAuthenticatedUser();
if (!user) {
return {
success: false,
message: "您的登入工作階段已過期,請重新登入後再試。",
};
}
// 2. 安全提取並正規化 FormData 欄位(注意 formData.get 可能回傳 File 或 null)
const rawEmail = formData.get("email");
const rawContent = formData.get("content");
const email = typeof rawEmail === "string" ? rawEmail.trim() : "";
const content = typeof rawContent === "string" ? rawContent.trim() : "";
// 3. 伺服器端結構化欄位驗證(實務專案可搭配 Zod safeParse)
const errors: NonNullable<FeedbackActionState["errors"]> = {};
if (!email || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
errors.email = "請輸入有效的聯絡電子郵件地址。";
}
if (content.length < 10 || content.length > 500) {
errors.content = "問題描述長度需介於 10 至 500 個字元之間。";
}
// 若驗證未通過,回傳 errors 並附帶 fields 快照保留使用者剛才輸入的內容
if (Object.keys(errors).length > 0) {
return {
success: false,
message: "部分欄位格式不符,請修正後重新送出。",
errors,
fields: { email, content },
};
}
// 4. 寫入資料庫並觸發頁面快取重新驗證
await new Promise((resolve) => setTimeout(resolve, 600));
revalidatePath("/support/feedback");
// 5. 成功時清空 fields,讓 React 19 原生表單自動重置為空白狀態
return {
success: true,
message: "感謝您的回饋!我們已收到您的技術回報單。",
};
}
// 檔案 2:app/support/FeedbackForm.tsx
"use client";
import { useActionState } from "react";
import { useFormStatus } from "react-dom";
import {
submitFeedbackAction,
type FeedbackActionState,
} from "../actions/feedback";
const initialState: FeedbackActionState = {
success: false,
message: "",
};
/**
* 共用設計系統提交按鈕:
* 位於 <form> 內部,透過 useFormStatus 自動感知父表單提交狀態,無須傳遞 props
*/
function SubmitButton() {
const { pending, data } = useFormStatus();
const submittingEmail = data?.get("email");
return (
<button
type="submit"
disabled={pending}
aria-disabled={pending}
className="px-4 py-2 rounded bg-blue-600 text-white disabled:opacity-50"
>
{pending
? `正在送出 (${typeof submittingEmail === "string" ? submittingEmail : "..."})...`
: "送出技術回饋"}
</button>
);
}
export default function FeedbackForm() {
// React 19 useActionState 回傳三元組:[state, formAction, isPending]
const [state, formAction, isPending] = useActionState(
submitFeedbackAction,
initialState
);
return (
<form action={formAction} noValidate aria-busy={isPending} className="space-y-4">
<div>
<label htmlFor="feedback-email" className="block font-medium mb-1">
聯絡信箱
</label>
<input
id="feedback-email"
name="email"
type="email"
required
defaultValue={state.fields?.email ?? ""}
aria-invalid={Boolean(state.errors?.email)}
aria-describedby={state.errors?.email ? "email-error" : undefined}
className="w-full border rounded px-3 py-2"
/>
{state.errors?.email && (
<p id="email-error" role="alert" className="text-red-600 text-sm mt-1">
{state.errors.email}
</p>
)}
</div>
<div>
<label htmlFor="feedback-content" className="block font-medium mb-1">
問題描述(10 ~ 500 字)
</label>
<textarea
id="feedback-content"
name="content"
rows={4}
required
defaultValue={state.fields?.content ?? ""}
aria-invalid={Boolean(state.errors?.content)}
aria-describedby={state.errors?.content ? "content-error" : undefined}
className="w-full border rounded px-3 py-2"
/>
{state.errors?.content && (
<p id="content-error" role="alert" className="text-red-600 text-sm mt-1">
{state.errors.content}
</p>
)}
</div>
{state.message && (
<div
role="status"
aria-live="polite"
className={`p-3 rounded text-sm ${
state.success
? "bg-green-50 text-green-800 border border-green-300"
: "bg-amber-50 text-amber-800 border border-amber-300"
}`}
>
{state.message}
</div>
)}
<div className="flex items-center gap-3">
<SubmitButton />
{isPending && (
<span className="text-xs text-slate-500">
伺服器正在驗證並寫入紀錄...
</span>
)}
</div>
</form>
);
}
在 Next.js 16.4.3(React 19.3.0)專案執行,送出格式錯誤的資料後,錯誤訊息出現在欄位下方,輸入的 bad-email 與 short 仍留著:

圖:範本一送出格式錯誤的資料後,欄位透過 state.fields 保留輸入(Next.js 16.4.3、React 19.3.0、Chrome 156 無頭模式執行畫面)
送出正確資料時,SubmitButton 用 useFormStatus 讀到 pending 與送出中的信箱並禁用,表單元件同時用 isPending 顯示提示:

圖:送出期間 useFormStatus 的 pending、data 與 useActionState 的 isPending 同時生效(Next.js 16.4.3、React 19.3.0、Chrome 156 無頭模式執行畫面)
四、 常見問題(Q&A)
Q1:為什麼 Server Action 驗證失敗回傳錯誤時,使用者剛填好的表單欄位全部被清空了?
原因:把函式傳給 <form action={formAction}> 時,只要 Action 函式成功執行完畢(沒有拋出例外),React 就會重置表單內所有非受控欄位。Server Action 回傳 { success: false },對 React 來說仍是一次成功的 Action。下圖是欄位沒綁定 state.fields 的對照組:

圖:欄位未綁定 defaultValue 的對照組,驗證失敗後輸入框被重置為空白(Next.js 16.4.3、React 19.3.0、Chrome 156 無頭模式執行畫面)
解法:
- 用
useActionState回傳欄位快照(範本的做法):驗證失敗時把輸入放進state.fields,在<input>綁定defaultValue={state.fields?.fieldName ?? ''}。 - 改由
onSubmit搭配startTransition呼叫:受控表單(如 React Hook Form)可在onSubmit呼叫e.preventDefault(),再於startTransition(() => formAction(new FormData(e.currentTarget)))內觸發 Action,略過自動重置。
Q2:既然 useActionState 第三個回傳值已經提供 isPending,為什麼還需要 useFormStatus?
原因:Canary 版的 ReactDOM.useFormState 只回傳 [state, formAction],改名為 useActionState 時才加入 pending,React 19 正式版已直接回傳 isPending。
解法:
- 按鈕和
useActionState在同一個元件:直接用isPending。 - 全站共用的按鈕或欄位元件:在子元件內呼叫
useFormStatus(),不必每頁傳 props。注意useFormStatus()不會回傳同一個元件所渲染的<form>狀態,必須放在<form>的子元件內。
Q3:在 Server Action 中呼叫 redirect() 為什麼會掉進 try / catch 的錯誤區塊?
原因:Next.js 的 redirect('/dashboard') 與 notFound() 是拋出由框架處理的控制流程例外(redirect() 拋出 NEXT_REDIRECT)來中斷執行,再由框架接手導向(JavaScript 可用時做客戶端導覽,漸進式增強的表單送出回應 303)。包在 try / catch 裡時,catch 會把它當一般錯誤攔下:在 Next.js 16.4.3 執行時,攔到的錯誤 message 與 digest 開頭都是 NEXT_REDIRECT,頁面停留在原網址。
解法:把 redirect() 移到 try / catch 外面的最後一行(在 try / catch 內完成寫入與錯誤回傳),或在 catch 的第一行呼叫 next/navigation 的 unstable_rethrow(err) 重新拋出框架的導向例外(名稱帶 unstable_ 前綴,官方標示為 Unstable)。
Q4:標記 "use server" 的函式會被打包進客戶端 JavaScript Bundle 嗎?有何資安風險?
原因:函式本體不會送到瀏覽器,但傳給它的資料會經過客戶端:.bind() 預先綁定的參數和一般參數一樣,都是客戶端送出、可被竄改的輸入;Server Component 內的內嵌 Server Action 捕獲的外層變數(Closure Variables)也會先送到客戶端,觸發時再隨 POST 送回。Next.js 會自動加密這些閉包變數,但官方不建議只靠加密避免敏感值外洩。
解法:金鑰不要進入閉包或 .bind() 參數,執行時直接從 process.env 讀取;每個 "use server" 匯出函式都當成公開 API 端點,開頭檢查 Session、權限與輸入 Schema(如 Zod),預期錯誤以物件回傳,不要拋出含資料庫結構的原始 Exception。
五、 總結與官方參考文獻
上線前核對:每個 "use server" 函式都檢查 Session、權限與參數型別;驗證失敗回傳 state.fields 綁定 defaultValue;驗證未過、權限不足等預期錯誤以回傳值交給 useActionState 渲染,未預期的錯誤才交給 Error Boundary。
站內系列文章與官方規範延伸閱讀
- HTML Form GET 與 POST 差異比較與常見使用場景解析
- React 事件處理器 (Event Handlers):常用事件速查表、SyntheticEvent 與傳參寫法
- React:'use server'
- React:Server Functions
- React v19 部落格
- React:useActionState
- React DOM:useFormStatus
- React DOM:form 元件
- Next.js:Mutating Data
- Next.js:Server Actions
- Next.js:Data Security
- Next.js:redirect
- Next.js:unstable_rethrow
發佈留言