React Server Functions（简称 RSF）是 React 19+与 React Server Components（RSC）架构深度集成的核心特性，通过**"use server"指令**标记的异步函数，让客户端组件能像调用本地函数一样安全地执行服务器端逻辑，彻底简化了前后端交互模式，是构建现代全栈 React 应用的关键工具。

---

一、核心定义与定位

1.1 什么是 React Server Functions？

• 本质：通过"use server"指令标记的异步函数，仅在服务器执行，客户端通过 RPC（远程过程调用）方式调用
• 分类：
  • 当传递给表单action属性或从 action 内部调用时，称为Server Actions（服务器操作）
  • 其他场景下的通用服务器函数，统一称为Server Functions
• 核心价值：消除手动编写 API 端点的繁琐，实现前后端逻辑无缝衔接，同时保证安全性与性能优化

1.2 与 Server Components 的关系（关键区别）

特性	React Server Functions	React Server Components
本质	可远程调用的服务器函数	仅在服务器渲染的组件
执行时机	按需调用（客户端触发）	渲染时自动执行
标记方式	'use server'指令	默认（无需标记）
客户端交互	支持（通过函数调用）	不支持（无交互能力）
用途	数据突变、表单处理、服务器计算	数据获取、静态 UI 渲染
序列化	函数引用可跨边界传递	组件本身不可传递，仅传递渲染结果

核心联系：Server Functions 通常在 Server Components 中定义，再传递给 Client Components 使用，形成完整的前后端协作链路。

---

二、底层工作原理（Mermaid 可视化）

2.1 完整执行流程

修正语法后可正常渲染，问题是括号标签格式冲突，调整写法：

2.2 关键技术细节

1. 函数序列化：React 不会传递函数本身，而是生成唯一标识符，客户端通过标识符发起请求
2. 自动 RPC：框架自动处理网络请求、参数序列化、响应解析，开发者无需编写 fetch 代码
3. 加密闭包：函数中的闭包变量会被加密传输，防止敏感信息泄露
4. 批处理优化：React 19+会自动批处理多个 Server Function 调用，减少网络请求次数

---

三、基础用法与 API 详解

3.1 定义 Server Function（三种方式）

方式 1：在 Server Component 中内联定义

// Server Component（无'use server'标记）
import ClientButton from './ClientButton'

async function createPost(formData) {
  'use server' // 必须放在函数体第一行

  // 服务器端逻辑：访问数据库、验证权限等
  const title = formData.get('title')
  const content = formData.get('content')
  await db.posts.create({ title, content })

  return { success: true }
}

export default function NewPostPage() {
  return <ClientButton onCreatePost={createPost} />
}

方式 2：独立模块定义（推荐）

// actions.js（纯服务器模块）
'use server' // 模块级标记，所有导出函数均为Server Functions

export async function updateUser(userId, data) {
  // 服务器端逻辑
  await db.users.update(userId, data)
  return { updated: true }
}

export async function deleteComment(commentId) {
  // 服务器端逻辑
  await db.comments.delete(commentId)
  return { deleted: true }
}

方式 3：表单 action 直接使用（Server Actions）

// Client Component
'use client'
import { updateName } from './actions'

function ProfileEditor() {
  return (
    <form action={updateName}>
      <input type="text" name="name" />
      <button type="submit">更新名称</button>
    </form>
  )
}

3.2 核心 API 与钩子

useActionState：管理 Server Action 状态

'use client'
import { useActionState } from 'react'
import { submitForm } from './actions'

function Form() {
  // 初始状态、Server Function、持久化状态键
  const [state, formAction] = useActionState(
    submitForm,
    {
      message: '',
      errors: {},
    },
    'form-key'
  )

  return (
    <form action={formAction}>
      <input type="text" name="email" />
      {state.errors.email && <p>{state.errors.email}</p>}
      <button type="submit">提交</button>
      {state.message && <p>{state.message}</p>}
    </form>
  )
}

useFormStatus：获取表单提交状态

'use client'
import { useFormStatus } from 'react-dom'

function SubmitButton() {
  const { pending } = useFormStatus()

  return (
    <button type="submit" disabled={pending}>
      {pending ? '提交中...' : '提交'}
    </button>
  )
}

---

四、React 19+专属优化与特性

4.1 自动错误处理与重试

React 19+会自动捕获 Server Function 执行中的错误，并提供重试机制：

async function submitPayment(formData) {
  'use server'
  try {
    await paymentService.process(formData)
    return { success: true }
  } catch (error) {
    // 错误会自动传递给客户端
    return { success: false, error: error.message }
  }
}

4.2 与并发渲染深度集成

Server Functions 与 React 19 并发特性完美配合，自动在transition中处理异步操作：

'use client'
import { useTransition } from 'react'
import { fetchData } from './actions'

function DataDashboard() {
  const [isPending, startTransition] = useTransition()
  const [data, setData] = useState(null)

  const loadData = async () => {
    startTransition(async () => {
      // Server Function调用会自动在过渡中处理
      const result = await fetchData()
      setData(result)
    })
  }

  return (
    <div>
      <button onClick={loadData} disabled={isPending}>
        {isPending ? '加载中...' : '加载数据'}
      </button>
      {data && <DataView data={data} />}
    </div>
  )
}

4.3 流式响应与 Suspense 集成

React 19+支持 Server Functions 返回流式响应，配合 Suspense 实现渐进式 UI 更新：

// Server Function
async function fetchLargeDataset() {
  'use server'
  // 返回可读流
  return db.largeData.stream()
}

// Client Component
;('use client')
import { Suspense } from 'react'

function LargeDataView() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <DataStreamer fetchData={fetchLargeDataset} />
    </Suspense>
  )
}

---

五、安全最佳实践

5.1 输入验证（必须）

async function createUser(formData) {
  'use server'
  // 服务器端严格验证
  const email = formData.get('email')
  const password = formData.get('password')

  if (!validateEmail(email)) {
    throw new Error('无效的邮箱格式')
  }
  if (password.length < 8) {
    throw new Error('密码必须至少8位')
  }

  await db.users.create({ email, password: hashPassword(password) })
}

5.2 权限控制

async function deletePost(postId, userId) {
  'use server'
  // 验证用户权限
  const post = await db.posts.findUnique({ where: { id: postId } })
  if (post.authorId !== userId) {
    throw new Error('无权删除此文章')
  }
  await db.posts.delete({ where: { id: postId } })
}

5.3 防 CSRF 攻击

React Server Functions 默认包含 CSRF 保护机制：

• 自动生成并验证 CSRF 令牌
• 限制请求来源（Host/Origin 验证）
• 推荐使用表单提交（自动携带令牌）而非手动 fetch 调用

---

六、常见使用场景

6.1 表单处理（Server Actions）

// Server Component
import { saveContact } from './actions';
import ContactForm from './ContactForm';

export default function ContactPage() {
  return <ContactForm action={saveContact} />;
}

// Client Component
'use client';
export default function ContactForm({ action }) {
  return (
    <form action={action}>
      <input type="text" name="name" required />
      <input type="email" name="email" required />
      <textarea name="message" required></textarea>
      <button type="submit">发送</button>
    </form>
  );
}

6.2 数据突变（增删改）

// actions.js
'use server'
export async function addToCart(productId, quantity) {
  // 服务器端购物车逻辑
  const cart = await db.cart.findOrCreate({ userId: session.userId })
  await db.cartItem.upsert({
    where: { cartId_productId: { cartId: cart.id, productId } },
    update: { quantity: { increment: quantity } },
    create: { cartId: cart.id, productId, quantity },
  })
  return { success: true }
}

6.3 服务器计算（复杂逻辑）

// actions.js
'use server'
export async function calculateShipping(zipCode, items) {
  // 复杂计算逻辑，避免在客户端执行
  const location = await geocodeService.getLocation(zipCode)
  const weight = items.reduce(
    (sum, item) => sum + item.weight * item.quantity,
    0
  )
  const shippingCost = await shippingService.calculate(location, weight)
  return { shippingCost }
}

---

七、框架支持与实现差异

框架	支持情况	特殊实现
Next.js 14+	✅ 完全支持	App Router 原生集成，自动处理路由
Remix	✅ 支持	通过 loader/actions 实现类似功能
Gatsby	⚠️ 部分支持	需插件配合，主要用于数据预取
React Server	✅ 原生支持	官方实验性框架，完整 RSC 实现

---

八、总结：React Server Functions 的革命性意义

React Server Functions 是 React 全栈开发的里程碑式特性，它带来了三大核心变革：

1. 开发模式革新：消除前后端边界，前端开发者可直接编写服务器逻辑，无需学习额外后端框架
2. 性能提升：减少网络请求次数，自动批处理，流式响应，配合 Suspense 实现最优加载体验
3. 安全性增强：敏感逻辑全部在服务器执行，内置 CSRF 保护，加密闭包，严格输入验证

核心建议：

• 新项目优先采用 RSC 架构+Server Functions，大幅提升开发效率
• 现有项目逐步迁移，先从表单处理等简单场景入手
• 始终遵循安全最佳实践，避免在客户端暴露敏感信息