服务器行为和突变
服务器行为 是在服务器上执行的异步函数。它们可以在服务器和客户端组件中调用,以处理 Next.js 应用程序中的表单提交和数据突变。
🎥 观看: 了解更多关于服务器行为的突变 → YouTube (10 分钟)。
约定
可以使用 React "use server"
指令定义服务器行为。你可以将指令放在 async
函数的顶部,以将该函数标记为服务器行为,或放在单独文件的顶部,以将该文件的所有导出标记为服务器行为。
服务器组件
服务器组件可以使用内联函数级别或模块级别的 "use server"
指令。要内联服务器行为,请将 "use server"
添加到函数体的顶部
export default function Page() {
// Server Action
async function create() {
'use server'
// Mutate data
}
return '...'
}
客户端组件
要在客户端组件中调用服务器行为,请创建一个新文件并在其顶部添加 "use server"
指令。文件中的所有导出函数都将被标记为服务器行为,可以在客户端和服务器组件中重复使用
'use server'
export async function create() {}
'use client'
import { create } from './actions'
export function Button() {
return <button onClick={() => create()}>Create</button>
}
将行为作为 props 传递
你也可以将服务器行为作为 prop 传递给客户端组件
<ClientComponent updateItemAction={updateItem} />
'use client'
export default function ClientComponent({
updateItemAction,
}: {
updateItemAction: (formData: FormData) => void
}) {
return <form action={updateItemAction}>{/* ... */}</form>
}
通常,Next.js TypeScript 插件会标记 client-component.tsx
中的 updateItemAction
,因为它是一个函数,通常无法在客户端-服务器边界之间序列化。但是,名为 action
或以 Action
结尾的 props 被假定为接收服务器行为。这只是一种启发式方法,因为 TypeScript 插件实际上并不知道它接收的是服务器行为还是普通函数。运行时类型检查仍将确保你不会意外地将函数传递给客户端组件。
行为
- 可以使用
<form>
元素中的action
属性调用服务器行为- 服务器组件默认支持渐进增强,这意味着即使 JavaScript 尚未加载或被禁用,表单也会被提交。
- 在客户端组件中,调用服务器行为的表单会在 JavaScript 尚未加载时将提交排队,优先考虑客户端 hydration。
- Hydration 后,浏览器不会在表单提交时刷新。
- 服务器行为不限于
<form>
,可以从事件处理程序、useEffect
、第三方库和其他表单元素(如<button>
)调用。 - 服务器行为与 Next.js 缓存和重新验证架构集成。当调用行为时,Next.js 可以在单个服务器往返中返回更新后的 UI 和新数据。
- 在幕后,行为使用
POST
方法,只有此 HTTP 方法可以调用它们。 - 服务器行为的参数和返回值必须可由 React 序列化。有关可序列化的参数和值的列表,请参阅 React 文档 可序列化的参数和值。
- 服务器行为是函数。这意味着它们可以在应用程序中的任何位置重复使用。
- 服务器行为从它们所在的页面或布局继承运行时。
- 服务器行为从它们所在的页面或布局继承路由段配置,包括像
maxDuration
这样的字段。
示例
表单
React 扩展了 HTML <form>
元素,允许使用 action
prop 调用服务器行为。
在表单中调用时,行为会自动接收 FormData
对象。你无需使用 React useState
来管理字段,而是可以使用原生 FormData
方法 提取数据
export default function Page() {
async function createInvoice(formData: FormData) {
'use server'
const rawFormData = {
customerId: formData.get('customerId'),
amount: formData.get('amount'),
status: formData.get('status'),
}
// mutate data
// revalidate cache
}
return <form action={createInvoice}>...</form>
}
须知
- 示例:具有加载和错误状态的表单
- 当处理具有许多字段的表单时,你可能需要考虑使用
entries()
方法与 JavaScript 的Object.fromEntries()
。例如:const rawFormData = Object.fromEntries(formData)
。需要注意的一点是,formData
将包含额外的$ACTION_
属性。- 请参阅 React
<form>
文档 以了解更多信息。
传递额外的参数
你可以使用 JavaScript bind
方法将额外的参数传递给服务器行为。
'use client'
import { updateUser } from './actions'
export function UserProfile({ userId }: { userId: string }) {
const updateUserWithId = updateUser.bind(null, userId)
return (
<form action={updateUserWithId}>
<input type="text" name="name" />
<button type="submit">Update User Name</button>
</form>
)
}
除了表单数据外,服务器行为还将接收 userId
参数
'use server'
export async function updateUser(userId: string, formData: FormData) {}
须知:
- 另一种方法是将参数作为表单中的隐藏输入字段传递(例如
<input type="hidden" name="userId" value={userId} />
)。但是,该值将成为渲染 HTML 的一部分,并且不会被编码。.bind
在服务器和客户端组件中都有效。它也支持渐进增强。
嵌套的表单元素
你还可以在嵌套在 <form>
内的元素(如 <button>
、<input type="submit">
和 <input type="image">
)中调用服务器行为。这些元素接受 formAction
prop 或 事件处理程序。
这在你想要在一个表单中调用多个服务器行为的情况下很有用。例如,除了发布帖子外,你还可以创建一个特定的 <button>
元素来保存帖子草稿。有关更多信息,请参阅 React <form>
文档。
程序化表单提交
你可以使用 requestSubmit()
方法以编程方式触发表单提交。例如,当用户使用 ⌘
+ Enter
键盘快捷键提交表单时,你可以监听 onKeyDown
事件
'use client'
export function Entry() {
const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
if (
(e.ctrlKey || e.metaKey) &&
(e.key === 'Enter' || e.key === 'NumpadEnter')
) {
e.preventDefault()
e.currentTarget.form?.requestSubmit()
}
}
return (
<div>
<textarea name="entry" rows={20} required onKeyDown={handleKeyDown} />
</div>
)
}
这将触发最近的 <form>
祖先的提交,这将调用服务器行为。
服务器端表单验证
你可以使用 HTML 属性(如 required
和 type="email"
)进行基本的客户端表单验证。
对于更高级的服务器端验证,你可以使用像 zod 这样的库在更改数据之前验证表单字段
'use server'
import { z } from 'zod'
const schema = z.object({
email: z.string({
invalid_type_error: 'Invalid Email',
}),
})
export default async function createUser(formData: FormData) {
const validatedFields = schema.safeParse({
email: formData.get('email'),
})
// Return early if the form data is invalid
if (!validatedFields.success) {
return {
errors: validatedFields.error.flatten().fieldErrors,
}
}
// Mutate data
}
一旦在服务器上验证了字段,你就可以在你的行为中返回一个可序列化的对象,并使用 React useActionState
hook 向用户显示消息。
- 通过将行为传递给
useActionState
,行为的函数签名会更改为接收一个新的prevState
或initialState
参数作为其第一个参数。 useActionState
是一个 React hook,因此必须在客户端组件中使用。
'use server'
import { redirect } from 'next/navigation'
export async function createUser(prevState: any, formData: FormData) {
const res = await fetch('https://...')
const json = await res.json()
if (!res.ok) {
return { message: 'Please enter a valid email' }
}
redirect('/dashboard')
}
然后,你可以将你的行为传递给 useActionState
hook,并使用返回的 state
来显示错误消息。
'use client'
import { useActionState } from 'react'
import { createUser } from '@/app/actions'
const initialState = {
message: '',
}
export function Signup() {
const [state, formAction, pending] = useActionState(createUser, initialState)
return (
<form action={formAction}>
<label htmlFor="email">Email</label>
<input type="text" id="email" name="email" required />
{/* ... */}
<p aria-live="polite">{state?.message}</p>
<button disabled={pending}>Sign up</button>
</form>
)
}
挂起状态
useActionState
hook 公开了一个 pending
布尔值,可用于在执行行为时显示加载指示器。
或者,你可以使用 useFormStatus
hook 在执行行为时显示加载指示器。当使用此 hook 时,你需要创建一个单独的组件来渲染加载指示器。例如,在行为挂起时禁用按钮
'use client'
import { useFormStatus } from 'react-dom'
export function SubmitButton() {
const { pending } = useFormStatus()
return (
<button disabled={pending} type="submit">
Sign Up
</button>
)
}
然后,你可以将 SubmitButton
组件嵌套在表单中
import { SubmitButton } from './button'
import { createUser } from '@/app/actions'
export function Signup() {
return (
<form action={createUser}>
{/* Other form elements */}
<SubmitButton />
</form>
)
}
须知: 在 React 19 中,
useFormStatus
在返回的对象中包含额外的键,例如 data、method 和 action。如果你未使用 React 19,则只有pending
键可用。
乐观更新
你可以使用 React useOptimistic
hook 在服务器行为完成执行之前乐观地更新 UI,而不是等待响应
'use client'
import { useOptimistic } from 'react'
import { send } from './actions'
type Message = {
message: string
}
export function Thread({ messages }: { messages: Message[] }) {
const [optimisticMessages, addOptimisticMessage] = useOptimistic<
Message[],
string
>(messages, (state, newMessage) => [...state, { message: newMessage }])
const formAction = async (formData: FormData) => {
const message = formData.get('message') as string
addOptimisticMessage(message)
await send(message)
}
return (
<div>
{optimisticMessages.map((m, i) => (
<div key={i}>{m.message}</div>
))}
<form action={formAction}>
<input type="text" name="message" />
<button type="submit">Send</button>
</form>
</div>
)
}
事件处理程序
虽然在 <form>
元素中使用服务器操作很常见,但它们也可以通过事件处理程序(如 onClick
)调用。例如,要增加点赞计数
'use client'
import { incrementLike } from './actions'
import { useState } from 'react'
export default function LikeButton({ initialLikes }: { initialLikes: number }) {
const [likes, setLikes] = useState(initialLikes)
return (
<>
<p>Total Likes: {likes}</p>
<button
onClick={async () => {
const updatedLikes = await incrementLike()
setLikes(updatedLikes)
}}
>
Like
</button>
</>
)
}
您还可以向表单元素添加事件处理程序,例如,使用 onChange
保存表单字段
'use client'
import { publishPost, saveDraft } from './actions'
export default function EditPost() {
return (
<form action={publishPost}>
<textarea
name="content"
onChange={async (e) => {
await saveDraft(e.target.value)
}}
/>
<button type="submit">Publish</button>
</form>
)
}
对于这种情况,可能会快速连续触发多个事件,我们建议进行防抖,以防止不必要的服务器操作调用。
useEffect
您可以使用 React useEffect
hook,以便在组件挂载或依赖项更改时调用服务器操作。这对于依赖于全局事件或需要自动触发的 mutation 非常有用。例如,用于应用快捷键的 onKeyDown
、用于无限滚动的 intersection observer hook,或者在组件挂载时更新视图计数
'use client'
import { incrementViews } from './actions'
import { useState, useEffect } from 'react'
export default function ViewCount({ initialViews }: { initialViews: number }) {
const [views, setViews] = useState(initialViews)
useEffect(() => {
const updateViews = async () => {
const updatedViews = await incrementViews()
setViews(updatedViews)
}
updateViews()
}, [])
return <p>Total Views: {views}</p>
}
请记住考虑 useEffect
的行为和注意事项。
错误处理
当抛出错误时,它将被客户端上最近的 error.js
或 <Suspense>
边界捕获。有关更多信息,请参阅错误处理。
须知
- 除了抛出错误之外,您还可以返回一个对象,以便由
useActionState
处理。请参阅服务器端验证和错误处理。
重新验证数据
您可以使用 revalidatePath
API 在服务器操作中重新验证 Next.js 缓存
'use server'
import { revalidatePath } from 'next/cache'
export async function createPost() {
try {
// ...
} catch (error) {
// ...
}
revalidatePath('/posts')
}
或者使用 revalidateTag
使带有缓存标记的特定数据获取失效
'use server'
import { revalidateTag } from 'next/cache'
export async function createPost() {
try {
// ...
} catch (error) {
// ...
}
revalidateTag('posts')
}
重定向
如果您希望在服务器操作完成后将用户重定向到不同的路由,可以使用 redirect
API。 redirect
需要在 try/catch
块之外调用
'use server'
import { redirect } from 'next/navigation'
import { revalidateTag } from 'next/cache'
export async function createPost(id: string) {
try {
// ...
} catch (error) {
// ...
}
revalidateTag('posts') // Update cached posts
redirect(`/post/${id}`) // Navigate to the new post page
}
Cookie
您可以使用 cookies
API 在服务器操作中 get
、set
和 delete
Cookie
'use server'
import { cookies } from 'next/headers'
export async function exampleAction() {
const cookieStore = await cookies()
// Get cookie
cookieStore.get('name')?.value
// Set cookie
cookieStore.set('name', 'Delba')
// Delete cookie
cookieStore.delete('name')
}
请参阅更多示例,了解如何从服务器操作中删除 Cookie。
安全性
默认情况下,当创建并导出服务器操作时,它会创建一个公共 HTTP 端点,应采用相同的安全假设和授权检查来对待它。这意味着,即使服务器操作或实用程序函数未在代码的其他位置导入,它仍然可以公开访问。
为了提高安全性,Next.js 具有以下内置功能
- 安全操作 ID: Next.js 创建加密的、非确定性的 ID,以允许客户端引用和调用服务器操作。这些 ID 会在构建之间定期重新计算,以增强安全性。
- 死代码消除: 未使用的服务器操作(通过其 ID 引用)将从客户端包中删除,以避免第三方公开访问。
须知:
ID 在编译期间创建,并最多缓存 14 天。当启动新构建或构建缓存失效时,它们将被重新生成。这种安全改进降低了在缺少身份验证层的情况下的风险。但是,您仍然应该将服务器操作视为公共 HTTP 端点。
// app/actions.js
'use server'
// This action **is** used in our application, so Next.js
// will create a secure ID to allow the client to reference
// and call the Server Action.
export async function updateUserAction(formData) {}
// This action **is not** used in our application, so Next.js
// will automatically remove this code during `next build`
// and will not create a public endpoint.
export async function deleteUserAction(formData) {}
身份验证和授权
您应确保用户有权执行该操作。例如
'use server'
import { auth } from './lib'
export function addItem() {
const { user } = auth()
if (!user) {
throw new Error('You must be signed in to perform this action')
}
// ...
}
闭包和加密
在组件内部定义服务器操作会创建一个闭包,其中该操作可以访问外部函数的作用域。例如,publish
操作可以访问 publishVersion
变量
export default async function Page() {
const publishVersion = await getLatestVersion();
async function publish() {
"use server";
if (publishVersion !== await getLatestVersion()) {
throw new Error('The version has changed since pressing publish');
}
...
}
return (
<form>
<button formAction={publish}>Publish</button>
</form>
);
}
当您需要在渲染时捕获数据快照(例如 publishVersion
)时,闭包非常有用,以便在稍后调用操作时可以使用它。
但是,为了实现这一点,捕获的变量会发送到客户端,并在调用操作时返回到服务器。为了防止敏感数据暴露给客户端,Next.js 会自动加密闭包变量。每次构建 Next.js 应用程序时,都会为每个操作生成一个新的私钥。这意味着操作只能针对特定构建调用。
须知: 我们不建议仅依赖加密来防止敏感值暴露在客户端上。相反,您应该使用 React taint API 主动防止特定数据发送到客户端。
覆盖加密密钥(高级)
当跨多个服务器自托管 Next.js 应用程序时,每个服务器实例最终可能会使用不同的加密密钥,从而导致潜在的不一致。
为了缓解这种情况,您可以使用 process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
环境变量覆盖加密密钥。指定此变量可确保您的加密密钥在构建之间保持持久,并且所有服务器实例都使用相同的密钥。此变量必须是 AES-GCM 加密的。
这是一个高级用例,其中跨多个部署的一致加密行为对于您的应用程序至关重要。您应考虑密钥轮换和签名等标准安全实践。
须知: 部署到 Vercel 的 Next.js 应用程序会自动处理此问题。
允许的来源(高级)
由于服务器操作可以在 <form>
元素中调用,因此它们可能会受到 CSRF 攻击。
在幕后,服务器操作使用 POST
方法,并且仅允许此 HTTP 方法调用它们。这可以防止现代浏览器中的大多数 CSRF 漏洞,特别是对于默认的 SameSite Cookie。
作为额外的保护,Next.js 中的服务器操作还会将 Origin header 与 Host header(或 X-Forwarded-Host
)进行比较。如果它们不匹配,则请求将被中止。换句话说,服务器操作只能在与其所在页面相同的主机上调用。
对于使用反向代理或多层后端架构(其中服务器 API 与生产域不同)的大型应用程序,建议使用配置选项 serverActions.allowedOrigins
选项来指定安全来源的列表。该选项接受字符串数组。
/** @type {import('next').NextConfig} */
module.exports = {
experimental: {
serverActions: {
allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
},
},
}
了解有关 安全性和服务器操作的更多信息。
其他资源
有关更多信息,请查看以下 React 文档
这有帮助吗?