服务器行为和突变

服务器行为是在服务器上执行的异步函数。它们可以在服务器和客户端组件中调用，以处理 Next.js 应用程序中的表单提交和数据突变。

🎥 观看： 了解有关使用服务器行为进行突变的更多信息 → YouTube (10 分钟)。

约定

可以使用 React "use server" 指令定义服务器行为。你可以将指令放在 async 函数的顶部以将该函数标记为服务器行为，或者放在单独文件的顶部以将该文件的所有导出标记为服务器行为。

服务器组件

服务器组件可以使用内联函数级别或模块级别的 "use server" 指令。要内联服务器行为，请将 "use server" 添加到函数体的顶部

app/page.tsx

export default function Page() {
  // Server Action
  async function create() {
    'use server'
    // Mutate data
  }
 
  return '...'
}

客户端组件

要在客户端组件中调用服务器行为，请创建一个新文件并在其顶部添加 "use server" 指令。文件中的所有导出函数都将被标记为服务器行为，可以在客户端和服务器组件中重复使用

app/actions.ts

'use server'
 
export async function create() {}

app/button.tsx

'use client'
 
import { create } from './actions'
 
export function Button() {
  return <button onClick={() => create()}>Create</button>
}

将行为作为 props 传递

你也可以将服务器行为作为 prop 传递给客户端组件

<ClientComponent updateItemAction={updateItem} />

app/client-component.tsx

'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 尚未加载时将提交排队，优先进行客户端水合。
- 水合后，浏览器在表单提交时不会刷新。
服务器行为不限于 <form>，可以从事件处理程序、useEffect、第三方库和其他表单元素（如 <button>）调用。
服务器行为与 Next.js 缓存和重新验证架构集成。当调用行为时，Next.js 可以在单个服务器往返中返回更新的 UI 和新数据。
在幕后，行为使用 POST 方法，只有此 HTTP 方法可以调用它们。
服务器行为的参数和返回值必须可由 React 序列化。有关可序列化参数和值的列表，请参阅 React 文档可序列化参数和值。
服务器行为是函数。这意味着它们可以在应用程序中的任何位置重复使用。
服务器行为继承它们所在的页面或布局的运行时。
服务器行为继承它们所在的页面或布局的路由段配置，包括 maxDuration 等字段。

示例

表单

React 扩展了 HTML <form> 元素，以允许使用 action prop 调用服务器行为。

当在表单中调用时，行为会自动接收 FormData 对象。你无需使用 React useState 来管理字段，而是可以使用原生 FormData 方法来提取数据

app/invoices/page.tsx

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 方法将额外的参数传递给服务器行为。

app/client-component.tsx

'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 参数，以及表单数据

app/actions.ts

'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 事件

app/entry.tsx

'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 这样的库来在突变数据之前验证表单字段

app/actions.ts

'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，因此必须在客户端组件中使用。

app/actions.ts

'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 来显示错误消息。

app/ui/signup.tsx

'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 时，你需要创建一个单独的组件来渲染加载指示器。例如，在行为待处理时禁用按钮

app/ui/button.tsx

'use client'
 
import { useFormStatus } from 'react-dom'
 
export function SubmitButton() {
  const { pending } = useFormStatus()
 
  return (
    <button disabled={pending} type="submit">
      Sign Up
    </button>
  )
}

然后，你可以将 SubmitButton 组件嵌套在表单内部

app/ui/signup.tsx

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，而不是等待响应

app/page.tsx

'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）调用它们。例如，要增加点赞计数

app/like-button.tsx

'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

app/ui/edit-post.tsx

'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 在组件挂载或依赖项更改时调用服务器行为。这对于依赖于全局事件或需要自动触发的突变非常有用。例如，用于应用快捷键的 onKeyDown、用于无限滚动的 intersection observer hook，或者在组件挂载时更新视图计数

app/view-count.tsx

'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 在 Server Actions 中重新验证 Next.js 缓存

app/actions.ts

'use server'
 
import { revalidatePath } from 'next/cache'
 
export async function createPost() {
  try {
    // ...
  } catch (error) {
    // ...
  }
 
  revalidatePath('/posts')
}

或者使用 revalidateTag 使带有缓存标签的特定数据获取失效

app/actions.ts

'use server'
 
import { revalidateTag } from 'next/cache'
 
export async function createPost() {
  try {
    // ...
  } catch (error) {
    // ...
  }
 
  revalidateTag('posts')
}

重定向

如果您希望在 Server Action 完成后将用户重定向到不同的路由，则可以使用 redirect API。 redirect 需要在 try/catch 块之外调用

app/actions.ts

'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
}

Cookies

您可以使用 cookies API 在 Server Action 内部 get、set 和 delete cookies

app/actions.ts

'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')
}

有关从 Server Actions 中删除 cookies 的其他示例，请参阅。

安全性

默认情况下，当创建和导出 Server Action 时，它会创建一个公共 HTTP 端点，应采用相同的安全假设和授权检查来对待。这意味着，即使 Server Action 或实用程序函数未在代码的其他地方导入，它仍然是公开可访问的。

为了提高安全性，Next.js 具有以下内置功能

安全操作 ID： Next.js 创建加密的、非确定性的 ID，以允许客户端引用和调用 Server Action。这些 ID 会在构建之间定期重新计算，以增强安全性。
死代码消除： 未使用的 Server Actions（通过其 ID 引用）将从客户端 bundle 中删除，以避免第三方公开访问。

须知:

ID 在编译期间创建，并缓存最多 14 天。当启动新构建或构建缓存失效时，它们将被重新生成。这种安全改进降低了在缺少身份验证层的情况下的风险。但是，您仍然应该像对待公共 HTTP 端点一样对待 Server Actions。

// 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) {}

身份验证和授权

您应确保用户有权执行该操作。例如

app/actions.ts

'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')
  }
 
  // ...
}

闭包和加密

在组件内部定义 Server Action 会创建一个闭包，其中 action 可以访问外部函数的作用域。例如，publish action 可以访问 publishVersion 变量

app/page.tsx

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）以便稍后在调用 action 时使用时，闭包非常有用。

但是，为了实现这一点，捕获的变量会被发送到客户端，并在调用 action 时返回到服务器。为了防止敏感数据暴露给客户端，Next.js 会自动加密闭包变量。每次构建 Next.js 应用程序时，都会为每个 action 生成一个新的私钥。这意味着 action 只能针对特定构建调用。

须知： 我们不建议仅依赖加密来防止敏感值暴露在客户端。相反，您应该使用 React taint API 来主动防止特定数据发送到客户端。

覆盖加密密钥（高级）

当跨多个服务器自托管 Next.js 应用程序时，每个服务器实例最终可能会使用不同的加密密钥，从而导致潜在的不一致。

为了缓解这种情况，您可以使用 process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY 环境变量覆盖加密密钥。指定此变量可确保您的加密密钥在构建之间保持持久性，并且所有服务器实例都使用相同的密钥。此变量必须是 AES-GCM 加密的。

这是一个高级用例，其中跨多个部署的一致加密行为对于您的应用程序至关重要。您应该考虑密钥轮换和签名等标准安全实践。

须知： 部署到 Vercel 的 Next.js 应用程序会自动处理此问题。

允许的来源（高级）

由于可以在 <form> 元素中调用 Server Actions，因此它们容易受到 CSRF 攻击。

在幕后，Server Actions 使用 POST 方法，并且仅允许此 HTTP 方法调用它们。这可以防止现代浏览器中的大多数 CSRF 漏洞，特别是当 SameSite cookies 作为默认设置时。

作为额外的保护，Next.js 中的 Server Actions 还会将 Origin header 与 Host header（或 X-Forwarded-Host）进行比较。如果它们不匹配，请求将被中止。换句话说，Server Actions 只能在与托管它的页面相同的主机上调用。

对于使用反向代理或多层后端架构（其中服务器 API 与生产域不同）的大型应用程序，建议使用配置选项 serverActions.allowedOrigins 选项来指定安全来源列表。该选项接受字符串数组。

next.config.js

/** @type {import('next').NextConfig} */
module.exports = {
  experimental: {
    serverActions: {
      allowedOrigins: ['my-proxy.com', '*.my-proxy.com'],
    },
  },
}

了解有关安全性和 Server Actions的更多信息。

其他资源

有关更多信息，请查看以下 React 文档

服务器行为和突变

下一步

serverActions