Server Actions and Mutations

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

🎥 观看：通过Server Actions学习有关表单和变更的更多信息 → YouTube（10分钟）。

约定

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

Server Components

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

app/page.tsx

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

Client Components

Client Components只能导入使用模块级别"use server"指令的操作。

要在Client Component中调用Server Action，请创建一个新文件，并在其顶部添加"use server"指令。文件中的所有函数都将被标记为Server Actions，可以在Client和Server Components中重复使用：

app/actions.ts

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

app/ui/button.tsx

import { create } from '@/app/actions'
 
export function Button() {
  return (
    // ...
  )
}

您还可以将Server Action作为prop传递给Client Component：

<ClientComponent updateItem={updateItem} />

app/client-component.jsx

'use client'
 
export default function ClientComponent({ updateItem }) {
  return <form action={updateItem}>{/* ... */}</form>
}

行为

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

示例

表单

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

在表单中调用时，action会自动接收 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>
}

需要注意的是：

示例：带有加载和错误状态的表单
在处理具有许多字段的表单时，您可能希望考虑使用JavaScript的Object.fromEntries()方法。例如：const rawFormData = Object.fromEntries(formData.entries())
有关更多信息，请参阅React <form>文档。

传递额外参数

您可以使用JavaScript的bind方法将额外参数传递给Server Action。

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

Server Action将接收userId参数，除了表单数据：

app/actions.js

'use server'
 
export async function updateUser(userId, formData) {
  // ...
}

需要注意的是：

作为替代方案，可以在表单中将参数作为隐藏的输入字段传递（例如<input type="hidden" name="userId" value={userId} />）。但是，该值将成为渲染的HTML的一部分，不会被编码。
.bind在Server和Client Components中都可以工作。它还支持渐进增强。

待定状态

您可以使用React的useFormStatus hook在表单提交时显示待定状态。

useFormStatus为特定的<form>返回状态，因此必须将其定义为<form>元素的子元素。
useFormStatus是一个React hook，因此必须在Client Component中使用。

app/submit-button.tsx

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

<SubmitButton />然后可以嵌套在任何表单中：

app/page.tsx

import { SubmitButton } from '@/app/submit-button'
import { createItem } from '@/app/actions'
 
// Server Component
export default async function Home() {
  return (
    <form action={createItem}>
      <input type="text" name="field-name" />
      <SubmitButton />
    </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'),
  })
 
  // 如果表单数据无效，请提前返回
  if (!validatedFields.success) {
    return {
      errors: validatedFields.error.flatten().fieldErrors,
    }
  }
 
  // Mutate data
}

一旦在服务器上验证了字段，您就可以在操作中返回可序列化的对象，并使用React的useFormState hook来向用户显示消息。

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

app/actions.ts

'use server'
 
export async function createUser(prevState: any, formData: FormData) {
  // ...
  return {
    message: 'Please enter a valid email',
  }
}

然后，您可以将操作传递给useFormState hook，并使用返回的状态来显示错误消息。

app/ui/signup.tsx

'use client'
 
import { useFormState } from 'react-dom'
import { createUser } from '@/app/actions'
 
const initialState = {
  message: null,
}
 
export function Signup() {
  const [state, formAction] = useFormState(createUser, initialState)
 
  return (
    <form action={formAction}>
      <label htmlFor="email">Email</label>
      <input type="text" id="email" name="email" required />
      {/* ... */}
      <p aria-live="polite" className="sr-only">
        {state?.message}
      </p>
      <button>Sign up</button>
    </form>
  )
}

需要注意的是：

在变异数据之前，您应始终确保用户还被授权执行该操作。请参阅身份验证和授权。

乐观更新

您可以使用React的useOptimistic hook在Server Action完成之前乐观地更新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[]>(
    messages,
    (state: Message[], newMessage: string) => [
      ...state,
      { message: newMessage },
    ]
  )
 
  return (
    <div>
      {optimisticMessages.map((m, k) => (
        <div key={k}>{m.message}</div>
      ))}
      <form
        action={async (formData: FormData) => {
          const message = formData.get('message')
          addOptimisticMessage(message)
          await send(message)
        }}
      >
        <input type="text" name="message" />
        <button type="submit">Send</button>
      </form>
    </div>
  )
}

嵌套元素

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

这在您想要在一个表单中调用多个服务器操作的情况下很有用。例如，您可以为保存文章草稿和发布文章分别创建一个特定的<button>元素。有关更多信息，请参阅React <form>文档。

非表单元素

虽然在<form>元素中使用Server Actions很常见，但它们也可以从代码的其他部分调用，例如事件处理程序和useEffect。

事件处理程序

您可以从onClick等事件处理程序中调用Server Action，例如增加喜欢次数：

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

为了提高用户体验，我们建议使用其他React API，如useOptimistic和 useTransition，在服务器操作在服务器上执行之前更新UI，或者在展示待定状态时。

您还可以向表单元素添加事件处理程序，例如在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 hook在组件挂载时或依赖项更改时调用Server Action。这对于依赖于全局事件或需要自动触发的变异很有用。例如，用于应用程序快捷键的onKeyDown，用于无限滚动的交叉观察器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>边界捕获。我们建议使用try/catch将错误返回以由您的UI处理。

例如，您的Server Action可能会通过返回消息来处理创建新项目时的错误：

app/actions.ts

'use server'
 
export async function createTodo(prevState: any, formData: FormData) {
  try {
    // Mutate data
  } catch (e) {
    throw new Error('Failed to create task')
  }
}

值得知道：

除了抛出错误之外，您还可以返回一个对象，由useFormStatus处理。请参阅服务器端验证和错误处理。

重新验证数据

您可以在Server Actions中使用revalidatePath API重新验证 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') // 更新缓存的文章
  redirect(`/post/${id}`) // 转到新的文章页面
}

Cookies

您可以在Server Action中使用cookies API的get、set和deleteCookie：

app/actions.ts

'use server'
 
import { cookies } from 'next/headers'
 
export async function exampleAction() {
  // 获取Cookie
  const value = cookies().get('name')?.value
 
  // 设置Cookie
  cookies().set('name', 'Delba')
 
  // 删除Cookie
  cookies().delete('name')
}

请查看从Server Actions删除Cookie的其他示例。

安全性

身份验证和授权

您应该将Server Actions视为面向公共API端点的方式，并确保用户被授权执行操作。例如：

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会创建一个闭包，其中该动作可以访问外部函数范围的变量。例如，publish动作可以访问publishVersion变量：

app/page.tsx

export default function Page() {
  const publishVersion = await getLatestVersion();
 
  async function publish(formData: FormData) {
    "use server";
    if (publishVersion !== await getLatestVersion()) {
      throw new Error('The version has changed since pressing publish');
    }
    ...
  }
 
  return <button action={publish}>Publish</button>;
}

当您需要捕获数据快照（例如publishVersion）以便在调用动作时稍后使用时，闭包很有用。

然而，为了发生这种情况，捕获的变量在动作被调用时被发送到客户端，并在动作被调用时返回服务器。为防止将敏感数据暴露给客户端，Next.js会自动加密封闭的变量。每次构建Next.js应用程序时，都会为每个动作生成一个新的私钥。这意味着动作只能为特定构建调用。

note

我们不建议仅依赖加密防止将敏感值暴露给客户端。相反，您应该使用React污染API 主动阻止将特定数据发送到客户端。

覆盖加密密钥（高级）

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

为减轻这种情况，您可以使用process.env.NEXT_SERVER_ACTIONS_ENCRYPTION_KEY环境变量覆盖加密密钥。指定此变量确保您的加密密钥在构建之间保持一致，并且所有服务器实例都使用相同的密钥。

这是一个需要在应用程序中实现一致的加密行为的高级用例。您应该考虑采用标准的安全实践，如密钥轮换和签名。

值得知道：部署到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的更多信息。

其他资源

有关Server Actions的更多信息，请查阅以下React文档：

Server Actions and Mutations

约定​

Server Components​

Client Components​

行为​

示例​

表单​

传递额外参数​

待定状态​

服务器端验证和错误处理​

乐观更新​

嵌套元素​

非表单元素​

事件处理程序​

useEffect​

错误处理​

重新验证数据​

重定向​

Cookies​

安全性​

身份验证和授权​

闭包和加密​

覆盖加密密钥（高级）​

允许的来源（高级）​

其他资源​

约定

Server Components

Client Components

行为

示例

表单

传递额外参数

待定状态

服务器端验证和错误处理

乐观更新

嵌套元素

非表单元素

事件处理程序

`useEffect`

错误处理

重新验证数据

重定向

Cookies

安全性

身份验证和授权

闭包和加密

覆盖加密密钥（高级）

允许的来源（高级）

其他资源