Server Actions 原理

学习目标

理解 use server 标记的函数的调用链路
掌握 Server Action 的参数序列化边界
理解它与 useActionState / useOptimistic / useFormStatus 的衔接

什么是 Server Action

被 'use server' 标记的函数运行在服务端，但可以被客户端组件像普通异步函数一样调用：

jsx

'use server';
export async function saveName(formData: FormData) {
  const name = formData.get('name');
  await db.user.update({ name });
  return { ok: true };
}

当客户端调用 saveName 时，React 框架会把它转成一个网络请求（而非本地执行），服务端执行后把返回值序列化回客户端。它本身是 React 的模型，具体传输由 Next.js 等框架落地。

参数序列化边界

传给 Server Action 的参数必须可序列化：支持基本类型、可序列化对象、FormData，以及被特殊标记的「可序列化函数」（如把客户端回调传给服务端 Action 的场景）。无法序列化的内容（如 window、class 实例、函数闭包）不能直接传入。

与表单 / Actions Hook 的衔接

React 19 的 Actions 体系围绕 Server Action 展开：

<form action={saveName}>：表单提交直接触发 Server Action，formData 自动传入；
useActionState(action, initialState)：维护 Action 的返回值与 isPending；
useOptimistic(state, fn)：请求未完成前展示乐观结果；
useFormStatus()：在 <form> 子组件读取 pending 状态，无需透传 props。

jsx

function Form() {
  const [state, action, pending] = useActionState(saveName, { ok: false });
  return <form action={action}>{/* ... */}<button disabled={pending}>提交</button></form>;
}

与 RSC 的关系

Server Actions 与 19-React Server Components 原理共用「服务端边界」心智：'use server' 与 'use client' 互为镜像，前者把函数暴露给客户端调用，后者把组件暴露给服务端引用。二者都由框架在打包阶段切分边界。

总结

Server Actions 让「提交表单 = 调用服务端函数」成为原生能力，配合 useActionState 等 Hook 把 pending / error / 乐观更新收敛为声明式 API，是 React 19 数据变更原生化的重要一环。