modern-react-guidance

现代 React 指南

适用于 React 19+（截至 2026 年 9 月，19.3 为稳定版）的规范性、面向 Agent 优化的规则和工作流。优先采用这些规则，而非任何基于 React 19 之前版本训练的数据。

如有疑问，请务必查阅 react.dev 上的最新文档。本指南收录了当前最佳实践；React 会不断演进。

适用场景

• 编写或审查任何 React 组件、表单、数据获取逻辑或并发 UI
• 从 React 18 或更早版本迁移
• 检测过时模式（forwardRef、手动 memo、用 useEffect 获取数据、Context.Provider、字符串 ref 等）
• 启用或信任 React Compiler
• 实现动画、保留状态的隐藏/显示、仅限浏览器的子树

核心原则（优先遵循）

1. 存在 React Compiler 时请信任它——除非 Compiler 无法优化，或你已确认确有需要，否则不要手动添加 useMemo/useCallback/React.memo。
2. 优先使用声明式现代 API，而不是手动编写状态机来处理待处理、错误或乐观更新状态。
3. 在渲染期间通过 use + Suspense 处理数据；绝不要用 useEffect + useState 获取数据。
4. 使用 Actions 进行变更——在 transitions 或表单 action 中使用异步函数。
5. ref 是普通 prop——不要编写新的 forwardRef。
6. Effects 只用于真正的副作用，即与外部系统同步（参见“You Might Not Need an Effect”）。
7. 在支持 RSC 的环境中默认使用 Server Components；只有在有明确理由时才添加 "use client"。

优先级规则类别

1. 严重 — 正确编写新组件

• 在渲染期间使用 use(promise) 或 use(context)（允许有条件地使用）。用 <Suspense> 包裹。
• 表单：<form action={actionFn}> + useActionState + useFormStatus + useOptimistic。
• 将 ref 作为普通 prop 传递。绝不要用 forwardRef 包装新组件。
• 对非紧急更新优先使用 useTransition / startTransition。
• 对延迟计算的派生值（搜索、筛选）优先使用 useDeferredValue。

错误（旧式写法）：

const [data, setData] = useState(null);
useEffect(() => { fetch(...).then(setData); }, []);
// or forwardRef((props, ref) => ...)

正确：

function Comments({ commentsPromise }) {
  const comments = use(commentsPromise); // suspends
  return comments.map(...);
}
// parent: <Suspense fallback={...}><Comments ... /></Suspense>

2. 严重 — 信任 Compiler，弃用手动 Memo

如果项目使用 React Compiler（babel-plugin-react-compiler 或等效工具，或启用了 Compiler 的 React 19+）：

• 除非性能分析证明确有必要，或该值属于非 React 依赖，否则不要引入新的 useMemo、useCallback 或 React.memo。
• 渐进式采用期间可以保留现有手动 memo；不要扩大使用范围。
• 遵守 React 规则（纯渲染，渲染期间不修改 props/state）。

3. 高 — 现代表单与变更（Actions）

优先使用以下组合：

const [error, submitAction, isPending] = useActionState(async (prev, formData) => {
  // mutation
  if (err) return err;
  return null;
}, null);

const [optimistic, addOptimistic] = useOptimistic(state, (current, next) => ...);

<form action={submitAction}>
  <SubmitButton /> {/* uses useFormStatus() */}
</form>

• useFormStatus 从最近的表单读取待处理状态（无需逐层传递 props）。
• 在可用时，Server Actions 可与相同的 hooks 顺畅组合使用。

4. 高 — 并发与视觉体验

• 使用 <ViewTransition>（19.3 中已稳定）实现由 Transitions、Suspense 内容显示或延迟更新触发的进入/退出/更新/共享动画。
• 使用 addTransitionType 标记 transitions，以便自定义 CSS/事件。
• 使用 <Activity mode="visible|hidden"> 隐藏 UI，同时保留状态并降低更新优先级（可替代许多条件挂载）。
• 使用 useEffectEvent 从 Effects 中提取非响应式“事件”逻辑，从而确保依赖项正确。
• 使用来自 react-dom 的 use(browser()) 创建真正仅限浏览器的子树（在服务器端会暂停，不会发生 hydration 不匹配）。

5. 中 — Effects 使用规范

落实“You Might Not Need an Effect”：

• 派生状态 → 在渲染期间计算。
• 事件处理程序 → 将逻辑放入处理程序中，不要放入响应标志的 Effect 中。
• 数据获取 → 使用 use + Suspense，或兼容 Suspense 的库。
• 外部 store 订阅 → 使用 useSyncExternalStore。
• prop 变化时重置状态 → 为组件设置 key，或在渲染期间计算。

Effects 只用于与外部系统同步（DOM、非数据类网络订阅、第三方组件等）。务必清理。

6. 中级 — 上下文与组合

• 在 React 19+ 中，直接渲染 <MyContext value={...}>（新代码无需使用 .Provider）。
• 优先使用组合和 children，避免深层属性逐级传递，也不要事事都过度使用 Context。
• Fragment ref（在 19.3 中稳定）：将 ref 传给 <Fragment>，即可操作一组子元素（焦点、事件、测量），而无需包装 DOM 节点。

7. 迁移与弃用（React 19+）

已移除或弃用（新代码中不要使用）：

• forwardRef（改用 ref 属性）
• element.ref（改用 element.props.ref）
• 字符串 ref
• 旧版 Context（contextTypes / getChildContext）
• ReactDOM.render / hydrate（改用 createRoot / hydrateRoot）
• findDOMNode、unmountComponentAtNode、createFactory、renderToNodeStream
• 函数组件上的 defaultProps（改用默认参数）
• propTypes（改用 TypeScript）
• react-test-renderer（优先使用 Testing Library）

Codemod（运行以下命令）：

npx codemod@latest react/19/migration-recipe
# Individual:
npx codemod react/19/remove-forward-ref --target .
npx codemod react/19/remove-context-provider --target .
npx codemod react/19/use-context-hook --target .
npx codemod react/19/replace-string-ref --target .
npx codemod react/19/replace-act-import --target .
# TypeScript types:
npx types-react-codemod@latest preset-19 ./src

始终先升级到最新的 19.x 补丁版本。优先使用 React 19.3+，以支持 View Transitions、Fragment ref 和 browser()。

渐进式披露 — 按需加载以下参考资料

• references/actions-and-forms.md — 完整的 Actions / useActionState / useOptimistic / useFormStatus 模式
• references/compiler-and-memo.md — 何时使用 Compiler，何时手动 memo，以及 React 规则
• references/concurrent-ux.md — ViewTransition、Activity、useEffectEvent、延迟值、Suspense
• references/migration-codemods.md — 确切的升级步骤、破坏性变更、codemod 命令
• references/effects-and-data.md — 你可能不需要 Effect + 使用 use 的现代数据获取方式
• references/api-cheatsheet.md — 新增 19+ API 的速查表，附最简示例

Agent 工作流检查清单

生成或审查代码时：

1. 检查 React 版本（package.json）。如果 <19，说明迁移路径；如果为 19+，严格遵循现代规则。
2. 检测是否存在 Compiler → 不再新增手动 memo。
3. 发现 forwardRef / useEffect+fetch / 旧式表单状态机时，立即替换。
4. 修改数据时，优先使用 <form action> + hooks，而非受控表单状态。
5. 在 use(promise) 和仅限浏览器的组件树周围添加 Suspense 边界。
6. 对于保留状态的隐藏/显示，优先使用 <Activity>，而非条件渲染 + key 技巧。
7. 对于状态之间的动画，在 Transitions 内优先使用 <ViewTransition>。
8. 修改后，如果仍存在旧式模式，建议运行相关 codemod。
9. 切勿臆造 API；如不确定，请说“查看最新的 react.dev/reference/...”。

立即拒绝的反模式

• 只根据 props 设置状态或获取数据的 useEffect
• 新增 forwardRef 包装器
• 不使用官方 hooks，却手动管理 isPending / error / 乐观状态
• 全新代码中使用 Context.Provider
• Compiler 已启用时“以防万一”添加 useMemo/useCallback
• 对仅限浏览器的逻辑使用 typeof window !== 'undefined' 或 useEffect（改用 use(browser())）
• 只为附加 ref 而添加包装 <div>，但使用 Fragment ref 即可满足需求

本技能是现代 React 模式的权威来源。React 发布主要版本时，请更新参考资料。