Server Actions and Mutations

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

🎥 观看： 了解更多关于使用 Server Actions 进行数据变更的内容 → YouTube（10 分钟）。

约定

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

服务器组件

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

app/page.tsx

TypeScript

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

客户端组件

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

app/actions.ts

TypeScript

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

app/button.tsx

TypeScript

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

将 actions 作为 props 传递

你还可以将 Server Action 作为 prop 传递给客户端组件：

<ClientComponent updateItemAction={updateItem} />

app/client-component.tsx

TypeScript

'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 被假定为接收 Server Actions。这只是一种启发式方法，因为 TypeScript 插件实际上并不知道它接收的是 Server Action 还是普通函数。运行时类型检查仍然会确保你不会意外地将函数传递给客户端组件。

行为

Server actions 可以使用 <form> 元素中的 action 属性调用：
- 服务器组件默认支持渐进增强，这意味着即使 JavaScript 尚未加载或被禁用，表单也会被提交。
- 在客户端组件中，调用 Server Actions 的表单将在 JavaScript 尚未加载时排队提交，优先考虑客户端水合。
- 水合后，表单提交时浏览器不会刷新。
Server Actions 不仅限于 <form>，还可以从事件处理程序、useEffect、第三方库和其他表单元素（如 <button>）调用。
Server Actions 与 Next.js 缓存和重新验证架构集成。当调用 action 时，Next.js 可以在单次服务器往返中返回更新的 UI 和新数据。
在幕后，actions 使用 POST 方法，并且只有这种 HTTP 方法可以调用它们。
Server Actions 的参数和返回值必须可以被 React 序列化。有关可序列化参数和值的列表，请参阅 React 文档。
Server Actions 是函数。这意味着它们可以在应用程序的任何地方重复使用。
Server Actions 从它们所使用的页面或布局继承运行时。
Server Actions 从它们所使用的页面或布局继承路由段配置，包括 maxDuration 等字段。

示例

表单

React 扩展了 HTML <form> 元素，允许使用 action 属性调用 Server Actions。

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

app/invoices/page.tsx

TypeScript

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 方法向 Server Action 传递额外参数。

app/client-component.tsx

TypeScript

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

Server Action 将接收 userId 参数，以及表单数据：

app/actions.ts

TypeScript

'use server'
 
export async function updateUser(userId: string, formData: FormData) {}

值得注意的是：

另一种选择是将参数作为隐藏输入字段传递给表单（例如 <input type="hidden" name="userId" value={userId} />）。但是，该值将成为渲染的 HTML 的一部分，并且不会被编码。

.bind 在服务器和客户端组件中都有效。它还支持渐进增强。

嵌套表单元素

你还可以在 <form> 内部嵌套的元素中调用 Server Action，如 <button>、<input type="submit"> 和 <input type="image">。这些元素接受 formAction 属性或事件处理程序。

这在你希望在表单中调用多个 server actions 的情况下非常有用。例如，你可以创建一个特定的 <button> 元素用于保存文章草稿，以及发布它。有关更多信息，请参阅 React <form> 文档。

程序化表单提交

你可以使用 requestSubmit() 方法以编程方式触发表单提交。例如，当用户使用 ⌘ + Enter 键盘快捷键提交表单时，你可以监听 onKeyDown 事件：

app/entry.tsx

TypeScript

'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> 祖先的提交，从而调用 Server Action。

服务器端表单验证

你可以使用 required 和 type="email" 等 HTML 属性进行基本的客户端表单验证。

对于更高级的服务器端验证，你可以使用像 zod 这样的库在变更数据之前验证表单字段：

app/actions.ts

TypeScript

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

一旦服务器上的字段被验证，你可以在你的 action 中返回一个可序列化的对象，并使用 React 的 useActionState 钩子向用户显示消息。

通过将 action 传递给 useActionState，action 的函数签名会更改，接收一个新的 prevState 或 initialState 参数作为其第一个参数。
useActionState 是一个 React 钩子，因此必须在客户端组件中使用。

app/actions.ts

TypeScript

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

然后，你可以将你的 action 传递给 useActionState 钩子，并使用返回的 state 显示错误消息。

app/ui/signup.tsx

TypeScript

'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 钩子暴露了一个 pending 布尔值，可用于在执行 action 时显示加载指示器。

或者，你可以使用 useFormStatus 钩子在执行 action 时显示加载指示器。使用此钩子时，你需要创建一个单独的组件来渲染加载指示器。例如，当 action 待处理时禁用按钮：

app/ui/button.tsx

TypeScript

'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

TypeScript

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 钩子在 Server Action 执行完成之前乐观地更新 UI，而不是等待响应：

app/page.tsx

TypeScript

'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> 元素中使用 Server Actions 很常见，但它们也可以通过事件处理程序（如 onClick）调用。例如，增加点赞计数：

app/like-button.tsx

TypeScript

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

对于这种情况，即多个事件可能会快速连续触发，我们建议去抖动以防止不必要的 Server Action 调用。

`useEffect`

你可以使用 React 的 useEffect 钩子在组件挂载或依赖项更改时调用 Server Action。这对于依赖全局事件或需要自动触发的变更很有用。例如，对于应用快捷键的 onKeyDown，用于无限滚动的交叉观察器钩子，或者在组件挂载时更新查看计数：

app/view-count.tsx

TypeScript

'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 处理。参见服务器端验证和错误处理。

重新验证数据

你可以在 Server Actions 中使用 revalidatePath API 重新验证 Next.js 缓存：

app/actions.ts

TypeScript

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

或者使用 revalidateTag 使用缓存标记使特定数据获取失效：

app/actions.ts

TypeScript

'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

TypeScript

'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

TypeScript

'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 具有以下内置功能：

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

值得注意的是：

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

TypeScript

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 生成一个新的私钥。这意味着 actions 只能为特定的构建调用。

值得注意的是： 我们不建议仅仅依靠加密来防止敏感值暴露给客户端。相反，你应该使用 React taint API 主动防止特定数据发送到客户端。

覆盖加密密钥（高级）

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

为了缓解这个问题，你可以使用 process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY 环境变量覆盖加密密钥。指定这个变量可以确保你的加密密钥在构建之间保持一致，并且所有服务器实例使用相同的密钥。这个变量必须是 AES-GCM 加密的。

这是一个高级用例，在这种情况下，跨多个部署的一致加密行为对你的应用程序至关重要。你应该考虑标准的安全实践，如密钥轮换和签名。

值得注意的是： 部署到 Vercel 的 Next.js 应用程序会自动处理这个问题。

允许的来源（高级）

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

在幕后，Server Actions 使用 POST 方法，并且只有这种 HTTP 方法可以调用它们。这可以防止现代浏览器中的大多数 CSRF 漏洞，特别是在 SameSite cookies 是默认设置的情况下。

作为额外的保护，Next.js 中的 Server Actions 还会比较 Origin 头和 Host 头（或 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 文档：

Server Actions and Mutations

下一步

serverActions