Next.js 中文文档

外观

服务器操作和变更

耶和博

4809字约16分钟

2024-08-10

服务器操作和变更

服务器操作是在服务器上执行的异步函数。它们可以在服务器组件和客户端组件中调用,用于处理 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/ui/button.tsx
'use client'
 
import { create } from '@/app/actions'
 
export function Button() {
  return <Button onClick={create} />
}

将操作作为 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 插件实际上并不知道它是接收服务器操作还是普通函数。运行时类型检查仍然会确保您不会意外地将函数传递给客户端组件。 通常,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>
}

提示

传递额外参数

您可以使用 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.js
'use server'
 
export async function updateUser(userId, 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 钩子向用户显示消息。

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

提示

这些示例使用了 React 的 useActionState 钩子,该钩子在 React 19 RC 中可用。如果您使用的是早期版本的 React,请使用 useFormState 代替。有关更多信息,请参阅 React 文档。

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 钩子,并使用返回的 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] = 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>Sign up</button>
    </form>
  )
}

提示

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

待定状态

useActionState 钩子公开了一个 pending 状态,可用于在执行操作时显示加载指示器,而不是等待响应。

app/submit-button.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" className="sr-only">
        {state?.message}
      </p>
      <button aria-disabled={pending} type="submit">
        {pending ? 'Submitting...' : 'Sign up'}
      </button>
    </form>
  )
}

提示

另一种选择是还可以使用 useFormStatus 钩子为特定表单显示待定状态。

乐观更新

您可以使用 React useOptimistic 钩子在操作完成执行之前优先更新 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) => {
    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 钩子在组件挂载或依赖项更改时调用服务器操作。这在需要依赖全局事件或需要自动触发的变更时非常有用。例如,onKeyDown 用于应用程序快捷方式,交叉观察器钩子用于无限滚动,或者在组件挂载时更新查看计数:

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 进行处理。

例如,您的服务器操作可能会在创建新项目时处理错误,并返回一条消息:

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

提示

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

重新验证数据

您可以使用 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')
}

重定向

如果您希望在服务器操作完成后将用户重定向到不同的路由,您可以使用 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 来 get、set 和 delete cookies:

app/actions.ts
'use server'
 
import { cookies } from 'next/headers'
 
export async function exampleAction() {
  // Get cookie
  const value = cookies().get('name')?.value
 
  // Set cookie
  cookies().set('name', 'Delba')
 
  // Delete cookie
  cookies().delete('name')
}

请参阅其他示例以了解从服务器操作中删除 cookies 的示例。

安全

身份验证和授权

您应将服务器操作视为公开的 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')
  }
 
  // ...
}

闭包和加密

在组件内定义服务器操作会创建一个闭包,其中操作可以访问外部函数的作用域。例如,publish 操作可以访问 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)非常有用,以便在以后调用操作时使用。

但是,为了捕获这些变量,它们会随着操作一起发送到客户端,然后再发送回服务器。为了防止敏感数据泄露到客户端,Next.js 会自动加密闭包变量。每次构建 Next.js 应用程序时,都会生成一个新的私钥,这意味着操作只能在特定构建中调用。

提示

我们不建议仅依赖加密来防止敏感值泄露到客户端。相反,您应使用 React 的污点 API 主动防止特定数据传递给客户端。

覆盖加密密钥(高级)

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

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

这是一个高级用例,当应用程序在多个部署中的一致加密行为对您的应用程序至关重要时,这是必要的。您应考虑标准的安全实践,如密钥轮换和签名。

提示

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

允许的来源(高级)

由于服务器操作可以在 <form> 元素中调用,这使它们容易受到 CSRF 攻击的影响。

在幕后,服务器操作使用 POST 方法,并且只有这种 HTTP 方法可以调用它们。这在现代浏览器中防止了大多数 CSRF 漏洞,特别是当使用SameSite cookies 作为默认值时。

作为额外的保护措施,Next.js 中的服务器操作还会将 Origin 头与 Host 头 (或 X-Forwarded-Host)进行比较。如果它们不匹配,请求将被中止。换句话说,服务器操作只能在与托管它的页面相同的主机上调用。

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

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

了解更多关于安全和服务器操作的信息。

其他资源

有关服务器操作的更多信息,请查看以下 React 文档: