Server Actions 与数据变更
Server Actions 在 Next.js 中的工作方式,包括单次往返响应模型、顺序派发、安全性以及与缓存的集成。
Server Action 是通过 React 的 action 机制调用的 React Server Function,例如 <form action>、<button formAction> 或客户端 transition。
你可以通过添加 'use server' 指令来创建它,然后从表单中调用它,或者从包裹在 startTransition 中的事件处理器或 useEffect 调用它。有关创建和调用 Server Functions 的基础知识,请参阅变更数据和表单指南。
本页介绍 Server Actions 中特定于 Next.js 的部分:它们通常如何映射到数据变更、响应如何同时携带返回的数据和重新渲染的 UI、客户端如何派发它们、框架强制执行的安全边界,以及可用的配置。
客户端上的顺序派发#
Next.js 对每个客户端一次只派发一个 Server Action。如果用户快速连续触发三个 action,第二个会等待第一个完成,然后第三个等待第二个。这使重新渲染的服务器树与产生它的 action 结果保持一致。
因此,不要依赖 Promise.all 从客户端并行化 Server Actions。如果需要并行工作,请在单个 Server Action 内完成,从 Server Component 并行获取数据,或对非变更请求使用 Route Handler。
小知识: 这是客户端派发器的特性,而非 Server Functions 的普遍特性。服务器不会对 Server Actions 排队。每个 action 都会在到达时在其自己的请求中运行,并且可以执行异步函数所能执行的任何操作。
单个响应同时携带数据和 UI#
当 Server Action 触发立即重新验证时,Next.js 会在一个 HTTP 请求内完成工作:它运行该 action,然后在服务端重新渲染当前路由。返回的响应在同一个 Flight 流中包含两部分:
- action 的返回值,由
useActionState或客户端上被 await 的 promise 消费。 - 当前路由新渲染的 RSC Payload,客户端将其作为种子导航提交。
你的应用代码无需额外的后续 fetch 即可看到当前页面更新后的 UI。
当 action 执行以下任一操作时,同一响应中会包含重新渲染:
- 调用
updateTag或revalidatePath立即使缓存数据失效。 - 调用
revalidateTag,使用解析为expire: 0的配置,包括{ expire: 0 }。 - 调用
refresh重新获取当前路由的 RSC Payload。 - 通过
cookies()修改 cookie。设置或删除 cookie 会自动重新渲染当前页面,使 UI 反映新值。 - 调用
redirect。响应会导航路由器并流式传输目标路由的 RSC Payload。
'use server'
import { revalidatePath } from 'next/cache'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'
export async function createPost(formData: FormData) {
const session = await auth()
if (!session?.user) throw new Error('Unauthorized')
await db.post.create({
data: {
title: String(formData.get('title')),
authorId: session.user.id,
},
})
revalidatePath('/posts')
}数据变更、缓存失效和页面重新渲染都在单次往返中完成。由于 redirect 会抛出控制流异常,其后的任何代码都不会运行。如果目标路由需要新数据,请在 redirect 之前调用重新验证。
revalidateTag 使用 stale-while-revalidate 配置时是个例外:它会将标签标记为后台刷新,并且不会在 action 响应中包含重新渲染。页面会在之后的读取中反映更改。一个未执行上述任何操作的 action 只携带其返回值,当前路由不会重新渲染。
安全性#
Server Action 作为针对调用它的页面的 POST 请求运行。在构建时,'use server' 指令告诉编译器在客户端 bundle 中将该函数的实现替换为一个引用(action ID 加上派发器),该引用会 POST 回服务器。实现保留在服务器上,但任何能发送相同 POST 的请求的人都可以访问该路由。请将每个 action 都视为不受信任的入口点。
Next.js 强制执行以下框架级保护措施:
- CSRF 检查。 请求的
Origin与Host(或X-Forwarded-Host)进行比较。不匹配会被拒绝。为代理或 CDN 域名配置experimental.serverActions.allowedOrigins。 - 请求体大小限制。 action 请求默认上限为 1MB。接受更大的 payload 时,请配置
experimental.serverActions.bodySizeLimit。 - 加密的 action ID 和死代码消除。 action 引用在构建时加密,未使用的 Server Functions 会从客户端 bundle 中剥离,因此它们没有公开端点。请参阅 Server Actions 内置安全功能。
- 闭包变量加密。 内联 action 捕获的变量在发送到客户端之前会被加密。对于多实例和自托管部署,请将
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY设置为在各实例之间共享的稳定密钥。请参阅闭包与加密。
框架级保护不能替代应用层的检查。在每个 action 内部:
- 身份验证与授权。 渲染时门控(仅在已认证页面渲染表单)不是安全边界,因为请求可以绕过 UI 直接发送。
- 校验输入。 将
FormData、查询参数和请求头视为不受信任。 - 约束返回值。 action 的返回值会被序列化到客户端。应按 UI 需要渲染的内容来构造它们,而非原始数据库记录。
有关包含数据访问层、返回值污染和速率限制的端到端模式,请参阅数据安全指南。
诸如删除之类的破坏性操作可能需要更强的处理方式,例如提升会话检查强度或重新认证,并在这些检查未通过时明确失败。
'use server'
import { auth } from '@/lib/auth'
export async function deletePost(postId: string) {
const session = await auth()
if (!session?.user) throw new Error('Unauthorized')
if (!(await canDelete(session.user, postId))) throw new Error('Forbidden')
await db.post.delete({ where: { id: postId } })
}如果你启用了实验性的 authInterrupts 标志,你可以改为从 next/navigation 抛出 unauthorized() 和 forbidden(),这样 Next.js 会自动渲染相应的 unauthorized.tsx / forbidden.tsx UI 段。
例如,客户端可以合法地告诉服务器要操作哪个条目,但不应提供该行的内容或所有权。发送一个引用(通常是 ID)加上用户的更改,然后使用会话从受信任的来源重新读取其余内容。Schema 校验(zod 或类似工具)只检查输入的形状。一个格式正确的 Item 对象仍可能指向调用方并不拥有的行。
'use server'
import { auth } from '@/lib/auth'
import { db } from '@/lib/db'
// 不安全:没有身份验证,也没有所有权检查。整个条目(包括其 id)都来自
// 客户端,因此任何能在此 POST 的人都可以将任意条目标记为已完成。
export async function completeItemUnsafe(item: Item) {
await db.item.update({ where: { id: item.id }, data: { completed: true } })
}
// 安全:只接收更改,从会话中推导身份,并按所有权查找。
export async function completeItem(itemId: string) {
const session = await auth()
if (!session?.user) return
const item = await db.item.findFirst({
where: { id: itemId, ownerId: session.user.id },
})
if (!item) return
await db.item.update({ where: { id: item.id }, data: { completed: true } })
}选择缓存更新方式#
变更数据后,按需重新验证会更新服务器缓存、客户端路由器,或两者。根据都需要更改的内容来选择:
updateTag:立即让某个标签失效。下一次读取(包括随 action 响应一起发送的路由重新渲染)会等待新数据。当 action 需要读己所写以便用户立即看到其更改时使用。仅限 Server Actions。revalidateTag:使用诸如'max'之类的缓存生命周期配置对标签进行 stale-while-revalidate 刷新。后续读取会获得过期值,同时后台进行新数据的获取。该调用不会触发立即重新渲染。有关立即失效的配置,请参阅客户端缓存行为。revalidatePath:按 URL 路径失效。当只有一个路由受影响且打标签过于繁琐时使用。refresh:重新获取当前路由的 RSC Payload,而不使缓存数据失效。当视图依赖于缓存之外、action 刚刚更改的状态时使用。
当 updateTag、revalidatePath 或 refresh 运行时,Next.js 会在服务端重新渲染当前路由,并在 action 的响应中包含新渲染的 RSC Payload,因此页面会在同一次往返中反映更改。revalidateTag 使用 stale-while-revalidate 配置时会有意跳过该立即重新渲染。
与 redirect 不同,这些操作都不会抛错,因此 action 可以调用它们并仍然向调用方返回值。有关底层模型,请参阅重新验证的工作原理。
配置#
next.config.js 中的 experimental.serverActions 选项控制框架级行为:
/** @type {import('next').NextConfig} */
module.exports = {
experimental: {
serverActions: {
allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
bodySizeLimit: '2mb',
},
},
}小知识: Server Actions 已稳定,并在 Next.js 14 及更高版本中默认启用。
experimental.serverActions下的配置 API 仍为实验性。
关于闭包加密密钥,请在部署环境中设置 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY。有关特定于部署的指导,请参阅自托管:Server Functions 加密密钥。
部署注意事项#
每个 Server Action 都由其构建产物中的 action ID 标识。新的部署通常会生成新的 ID(即使源码未变,Next.js 最多每 14 天轮换一次),因此仍在运行旧构建的客户端可能会调用一个已不存在的 action ID。错误表现为“找不到 Server Action”。
要最大限度地减少中断:
- 当活跃用户可能正处于数据变更过程中时,优先采用滚动部署而非突然切换。
- 在各实例之间保持
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY稳定,使 action 引用在任何地方都可解密。 - 在 UI 中将该错误作为重试路径呈现,而非硬性失败,这样刷新即可帮助用户恢复。