紀錄工作經驗、相關知識,解決技術相關問題。

React, 網站相關, 資訊相關

React 19 useActionState 教學:Server Actions 表單驗證、保留欄位與 useFormStatus 送出狀態

React 19 useActionState 教學:Server Actions 表單驗證、保留欄位與 useFormStatus 送出狀態 特色圖片

useActionState 是 React 19 管理 Server Actions 表單狀態的 Hook,一次拿到回傳結果、交給 <form action> 的函式與 isPending。本篇說明 Server Actions 的運作方式,示範驗證失敗時保留欄位、用 useFormStatus 顯示送出狀態,並整理 redirect() 與資安問題。

想看樂觀更新與失敗回滾,請看延伸篇:React 19 useOptimistic 樂觀更新:Server Action 失敗自動回滾與 Transition 呼叫方式。


常見問題(Q&A)與程式碼範本快速跳轉


一、 為什麼需要 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 視為內部私有函式導致公開 POST 端點越權風險流程圖

圖:"use server" 函式可被直接以 HTTP POST 呼叫,函式內沒有檢查 Session 與參數型別就會引發越權風險

3. 驗證失敗時表單被自動清空:把函式傳給 <form action> 時,Action 執行完成後 React 會重置表單內的非受控欄位。回傳 { success: false } 也算執行完成,使用者剛填的內容會被清空,要用 useActionState 回傳 state.fields 綁到 defaultValue 才能保留。

驗證失敗時原生 form 自動重置清空欄位流程圖

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


2. 傳統 API Route vs. React 19 Server Actions 對照

傳統 CSR 表單提交流程與 React 19 Server Actions 整合生命週期對照圖

圖:傳統 CSR 需手動維護狀態並經歷二次網路往返;Server Actions 在符合條件時可用單次往返完成寫入與畫面更新

比較維度傳統 onSubmit + fetchServer Actions(<form action> + useActionState)
API 端點手動建立 API 路由函式換成 Action ID 參照、以 POST 呼叫(Next.js 會加密 Action ID、隨建置重新產生);端點仍公開,權限要在函式內檢查
狀態管理手動維護 isLoading、error、dataconst [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 的差別

  1. Server Functions:在檔案頂部(或非同步函式本體第一行)標記 "use server" 的非同步函式。框架會建立函式參照傳給 Client Component,客戶端呼叫時由 React 對伺服器發出請求;Next.js 編譯時把客戶端 Bundle 中的實作換成「Action ID 加上派送器」的參照,實作程式碼留在伺服器端。
  2. 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 時,驗證失敗後輸入被清空

圖:欄位未綁定 defaultValue 的對照組,驗證失敗後輸入框被重置為空白(Next.js 16.4.3、React 19.3.0、Chrome 156 無頭模式執行畫面)

解法:

  1. 用 useActionState 回傳欄位快照(範本的做法):驗證失敗時把輸入放進 state.fields,在 <input> 綁定 defaultValue={state.fields?.fieldName ?? ''}。
  2. 改由 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。

解法:

  1. 按鈕和 useActionState 在同一個元件:直接用 isPending。
  2. 全站共用的按鈕或欄位元件:在子元件內呼叫 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。

站內系列文章與官方規範延伸閱讀

發佈留言