name: react-19 description: React 19开发指南，涵盖Actions、Server Components和新的hooks。用于构建React 19应用、表单处理、乐观更新和迁移。

React 19

React 19（自2024年12月稳定发布）简化了异步操作，改进了SSR，并借助Actions、Server Components和新的hooks提升了开发体验（DX）。

使用场景

构建React 19应用
异步表单处理，自动处理等待/错误状态
用于SSR的Server Components
乐观UI更新
从React 18迁移
用于全栈表单的Server Actions

安装

npm install react@19.2.1 react-dom@19.2.1
npm install --save-dev @types/react@19.0.0 @types/react-dom@19.0.0

必需： 在tsconfig.json中启用现代JSX转换：

{ "compilerOptions": { "jsx": "react-jsx" } }

核心概念

执行边界

类型	运行位置	状态	访问权限
Server Component	服务器	无	数据库、文件系统、密钥
Client Component	浏览器	有	DOM、浏览器API
Server Action	服务器	无	数据库、API

约定

"use server" = Server Action
"use client" = Client Component
无指令 = Server Component（在RSC环境中）
async组件 = 自动挂起

基本模式

1. 使用useActionState的表单

'use client';
import { useActionState } from 'react';

function SignupForm() {
  const [state, formAction, isPending] = useActionState(
    async (prev, formData) => {
      const error = await createUser(formData.get('email'));
      return error ? { error } : null;
    },
    { error: null }
  );

  return (
    <form action={formAction}>
      <input type="email" name="email" required />
      <button disabled={isPending}>
        {isPending ? '注册中...' : '注册'}
      </button>
      {state.error && <p>{state.error}</p>}
    </form>
  );
}

2. 乐观更新

'use client';
import { useOptimistic } from 'react';

function Comments({ comments, addComment }) {
  const [optimistic, addOptimistic] = useOptimistic(
    comments,
    (curr, newComment) => [...curr, { ...newComment, pending: true }]
  );

  return (
    <div>
      {optimistic.map(c => <div key={c.id}>{c.text}</div>)}
      <form action={async (formData) => {
        addOptimistic({ id: Date.now(), text: formData.get('text') });
        await addComment(formData);
      }}>
        <input name="text" />
        <button>发布</button>
      </form>
    </div>
  );
}

3. Server Actions

'use server';
export async function createPost(formData) {
  const title = formData.get('title');
  if (!title || title.length < 3) {
    return { error: '标题太短' };
  }
  await db.posts.create({ title });
  revalidatePath('/posts');
}

4. 使用Suspense进行流式传输

export default function Dashboard() {
  return (
    <div>
      <Suspense fallback={<Skeleton />}>
        <RevenueCard />
      </Suspense>
      <Suspense fallback={<Skeleton />}>
        <UsersCard />
      </Suspense>
    </div>
  );
}

async function RevenueCard() {
  const data = await db.analytics.getRevenue();
  return <div>{data}</div>;
}

安全要点

// 1. 总是进行身份验证
'use server';
export async function deleteUser(id) {
  const user = await getCurrentUser();
  if (!user) throw new Error('未授权');
  await db.users.delete(id);
}

// 2. 将密钥保留在服务器端
'use server';
export async function fetchData() {
  const secret = process.env.API_SECRET; // 在函数内部！
  return fetch(url, { headers: { Authorization: `Bearer ${secret}` }});
}

// 3. 验证输入
import { z } from 'zod';
const schema = z.object({ email: z.string().email() });
const result = schema.safeParse(formData);

查看references/security-guide.md获取完整的安全指南。

从React 18迁移

先更新到React 18.3（修复警告）
更新到React 19：npm install react@19 react-dom@19
运行代码修改：npx codemod@latest react/19/migration-recipe
修复TypeScript：npx types-react-codemod@latest preset-19 ./src
彻底测试

主要的破坏性变更：

ReactDOM.render → createRoot
PropTypes移除 → 使用TypeScript
forwardRef弃用 → 使用ref作为属性
useRef()需要参数 → useRef(null)

查看references/upgrade-checklist.md和references/migration-patterns.md。

快速参考

新的Hooks

Hook	用途
`useActionState`	带有异步操作的表单状态
`useOptimistic`	即时UI反馈
`use()`	读取承诺/上下文（可以有条件）
`useTransition`	非紧急更新

查看references/hooks-api.md获取详细的API文档。

使用什么

任务	解决方案
表单	`useActionState` + Server Actions
即时UI	`useOptimistic`
数据获取	使用`async/await`的Server Components
Refs	作为常规属性的`ref`
渐进式渲染	Suspense边界

参考文件

references/hooks-api.md - 完整的钩子文档
references/migration-patterns.md - 详细的迁移指南
references/advanced-examples.md - 生产示例
references/security-guide.md - 安全最佳实践
references/upgrade-checklist.md - 逐步升级
references/core-workflows.md - 5个基本模式，带有完整示例

资源

React 19文档：https://react.dev
Next.js 15文档：https://nextjs.org/docs

版本： 2.1 | 更新： 2025-12-27