accelint-react-best-practices

React 最佳实践

面向使用 React 代码的 AI Agent 和大模型，全面介绍 React 应用的性能优化和最佳实践。

React 中绝对不要这样做

以下是最严重的反模式，会导致真实的生产问题。专家们在调试和性能排查过程中吃过这些苦头。

绝对不要在组件内部定义组件——每次渲染都会创建新的组件类型，导致组件完全卸载并重新挂载，状态丢失且 DOM 被重新创建。结果是输入框每输入一个字符就失去焦点、动画意外重新开始，以及每次父组件渲染时都会运行 useEffect 的清理和设置。

如果只在回调中读取 searchParams/localStorage，绝对不要订阅它们——即使组件并不显示这些值，也会在每次 URL 变化或存储事件发生时触发重新渲染。应直接在回调中读取：new URLSearchParams(window.location.search)。

绝对不要在 useEffect 中使用对象/数组作为依赖项——由于每次渲染都会重新创建对象并产生新的引用，效果会在每次渲染时触发。应从对象中提取基本类型值（id、name），并将它们用作依赖项。

绝对不要用 useState + useEffect 同步派生状态——这会导致额外的重新渲染、无限循环和过时的中间状态。应在渲染期间计算派生值：const fullName = firstName + ' ' + lastName。

绝对不要在 SSR 组件中直接使用仅客户端状态（localStorage、cookies、设备检测）——这会导致 hydration 不匹配，即服务器 HTML 与客户端渲染结果不一致，进而产生 React 警告、视觉闪烁和交互失效。应在 React hydration 之前使用同步的内联 <script>。

React 19+ 中绝对不要使用 forwardRef——这是已弃用的 API。应将 ref 作为常规 prop 使用：function MyInput({ ref }) { return <input ref={ref} /> }。

绝对不要将内联创建的回调/对象/数组作为 prop 传给经过 memo 优化的组件——每次渲染都会创建新的引用，从而破坏 memo 优化。应将其提取到模块作用域，或使用 useMemo、useCallback：const config = useMemo(() => ({ theme }), [theme])。

绝对不要把用户交互逻辑放进 useEffect——如果逻辑由按钮点击或表单提交触发，就应直接放进事件处理程序。Effect 用于与外部系统同步，而不是处理由用户触发的操作。

优化性能前，请先确认

在建议使用 memo/useMemo/useCallback 优化之前，先判断是否有必要：

1. 此项目是否使用 React Compiler？

   • 在 package.json/配置文件中搜索 babel-plugin-react-compiler 或 react-compiler-webpack-plugin
   • 如果是 → 跳过手动 memo 优化（memo、useMemo、useCallback、将静态 JSX 提升到外部作用域）——编译器会自动处理这些
   • 如果否 → 应用此技能中的所有相关优化
   • 关于编译器的处理范围，请参阅 react-compiler-guide.md

2. 这真的是性能问题吗？

   • 用户是否已经测量/分析并找到了瓶颈？
   • 还是只是在请求常规审查/优化？

3. 规模有多大？

   • 对于列表：有多少项？（这会影响应建议 content-visibility 还是虚拟化）
   • 对于重新渲染：此组件重新渲染的频率如何？

如何使用

此技能采用渐进式披露结构，以尽量减少上下文用量：

1. 从概览开始（AGENTS.md）

阅读 AGENTS.md，了解所有规则及其简要说明。

2. 按需加载特定规则

确定相关优化后，加载对应的参考文件，了解详细的实现指导：

重新渲染优化：

• defer-state-reads.md
• extract-memoized-components.md
• narrow-effect-dependencies.md
• subscribe-derived-state.md
• functional-setstate-updates.md
• lazy-state-initialization.md
• transitions-non-urgent-updates.md
• calculate-derived-state.md
• avoid-usememo-simple-expressions.md
• extract-default-parameter-value.md
• interaction-logic-in-event-handlers.md
• no-inline-components.md
• useref-for-transient-values.md
• split-combined-hooks.md
• use-deferred-value.md

渲染性能：

• animate-svg-wrapper.md
• css-content-visibility.md
• hoist-static-jsx.md
• optimize-svg-precision.md
• prevent-hydration-mismatch.md
• activity-component-show-hide.md
• hoist-regexp-creation.md
• use-usetransition-over-manual-loading.md

高级模式：

• store-event-handlers-refs.md
• uselatest-stable-callbacks.md
• cache-repeated-function-calls.md
• initialize-app-once.md
• effect-event-deps.md

其他：

• named-imports.md
• no-forwardref.md

快速参考：

• quick-checklists.md
• compound-patterns.md
• react-compiler-guide.md

自动化脚本：

• scripts/ - 用于检测反模式的辅助脚本

3. 应用模式

每个参考文件都包含：

• ❌ 展示反模式的错误示例
• ✅ 展示最佳实现的正确示例
• 关于该模式为何重要的说明

4. 使用报告模板

调用此技能时，请使用标准报告格式：

模板： assets/output-report-template.md

报告格式包含：

• 执行摘要及影响评估
• 用于确定优先级的严重程度级别（严重、高、中、低）
• 影响分析（潜在 Bug、类型安全、可维护性、运行时故障）
• 分类（类型安全、安全性、状态管理、返回值、代码质量）
• 指向 references/ 中详细指导的模式参考链接
• 用于跟踪所有问题的第 2 阶段摘要表

何时使用审计模板：

• 通过 /accelint-react-best-practices <path> 直接调用技能
• 用户要求对一个或多个文件“检查代码质量”或“审计代码”，从而隐式调用技能

何时不使用报告模板：

• 用户要求“修复此类型错误”（直接实施修复）
• 用户询问“这段代码有什么问题？”（直接回答问题）
• 用户要求具体修复（直接应用修复，不生成正式报告）

示例

示例 1：优化重新渲染

任务：“用户滚动时，这个组件重新渲染过于频繁”

方法：

1. 阅读 AGENTS.md 概览
2. 找出可能的原因：订阅连续变化的值（滚动位置）
3. 加载 subscribe-derived-state.md 或 transitions-non-urgent-updates.md
4. 应用参考文件中的模式

示例 2：修复陈旧闭包

任务：“这个回调总是使用旧的状态值”

方法：

1. 阅读 AGENTS.md 概览
2. 找出问题：useCallback 中存在陈旧闭包
3. 加载 functional-setstate-updates.md
4. 用函数式更新替换直接的状态引用

示例 3：SSR 水合不匹配

任务：“使用 localStorage 中的主题时出现水合错误”

方法：

1. 阅读 AGENTS.md 概览
2. 找出问题：仅客户端状态导致不匹配
3. 加载 prevent-hydration-mismatch.md
4. 实现同步脚本模式

适当使用技能模式

每个参考文件都展示了一种经过验证的模式，但 React 问题通常有多种可行的解决方案。

应用模式时：

1. ✅ 展示参考文件中的模式
2. ✅ 在存在替代方法时提及这些方法
3. ✅ 考虑用户的 React 版本、项目复杂度和团队偏好
4. ✅ 对于简单情况，即使参考资料中没有，也建议更简单的解决方案

**示例：**对于 SSR 水合问题，prevent-hydration-mismatch.md 展示了同步脚本方法，但对于基本用例，简单的“已挂载标记”模式可能更合适。

重要说明

React Compiler 注意事项

许多手动优化模式（memo、useMemo、useCallback、提升静态 JSX）都由 React Compiler 自动处理。

优化前，请检查项目是否使用 React Compiler：

• 如果已启用：跳过手动记忆化，但仍应用状态／effect／CSS 优化
• 如果未启用：应用本指南中的所有相关优化

请参阅 react-compiler-guide.md，了解编译器会处理哪些内容，以及哪些仍需手动优化。

React 19+ 功能

此技能涵盖 React 19 功能，包括：

• useEffectEvent（19.2+），用于稳定的事件处理程序
• <Activity> 组件，用于保留隐藏组件的状态
• 将 ref 作为 prop（取代已弃用的 forwardRef）
• 仅使用命名导入（不默认导入 React）

性能理念

• 先编写正确的代码，再进行优化
• 优化前先测量
• 优先优化最慢的操作（网络 > 渲染 > 计算）
• 避免过早优化琐碎操作

代码质量原则

• 优先选择简单、易读的代码，而非巧妙的优化
• 只有在测量结果证明有必要时才增加复杂性
• 记录不明显的性能优化

其他资源

了解 React 19 功能：

• React 19
• React 19.2
• React 19 升级指南