name: react-best-practices description: “来自 react.dev 和 Vercel 的 React 最佳实践。使用场景：(1) 审查 React 代码，(2) 调试性能问题，(3) 优化打包体积，(4) 编写副作用或状态逻辑。触发关键词：React 性能、重渲染、打包体积、瀑布流、代码分割、memo、useCallback、useMemo、useEffect、SSR 闪烁、初始加载慢、React 编译器、状态结构、不可变更新、setState 数组对象。” user-invocable: false

React 最佳实践

来自 react.dev 和 Vercel 工程团队的性能模式和指南。

快速参考（优先级排序）

关键 - 必须遵守

规则	影响	参考文档
避免不必要的副作用	渲染周期、错误	effect-pitfalls.md
消除瀑布流	首次绘制、可交互时间	async-waterfall-elimination.md
并行数据获取	加载时间	async-parallel-requests.md
避免桶导入	打包体积	bundle-barrel-imports.md

高 - 强烈推荐

规则	影响	参考文档
React 编译器 (19+)	自动记忆化	react-compiler.md
动态导入	代码分割	bundle-dynamic-import.md
基于用户意图预加载	感知延迟	bundle-preload.md
策略性使用 memo()	渲染性能	rerender-memo-strategy.md
服务器缓存	服务器响应	server-cache-patterns.md

中 - 推荐

规则	影响	参考文档
状态结构	可维护性	state-structure.md
不可变更新	避免突变错误	immutable-updates.md
上下文拆分	避免重渲染	rerender-context-splitting.md
startTransition	UI 响应性	rerender-transitions.md
Set/Map 查找	O(1) 对比 O(n)	js-set-map-lookups.md
Key 模式	列表渲染	rendering-key-patterns.md

低 - 锦上添花

规则	影响	参考文档
content-visibility	长列表渲染	rendering-content-visibility.md
水合闪烁	SSR 稳定性	rendering-hydration-flicker.md
提升静态 JSX	避免重复创建	rendering-hoist-static-jsx.md

快速决策树

遇到 React 问题？
├── 正在编写 useEffect？
│   └── 检查是否必需 → effect-pitfalls.md (关键)
├── 设计状态？
│   └── 遵循 5 项原则 → state-structure.md
├── 更新状态？
│   └── 使用不可变模式 → immutable-updates.md
├── 使用 React 19+？
│   └── 启用 React 编译器 → react-compiler.md
├── 初始加载慢？
│   ├── 检查瀑布流 → async-waterfall-elimination.md
│   ├── 检查打包体积 → bundle-barrel-imports.md
│   └── 基于意图预加载 → bundle-preload.md
├── 交互响应慢？
│   ├── 检查重渲染 → rerender-memo-strategy.md
│   ├── 检查 Context 使用 → rerender-context-splitting.md
│   └── 使用过渡 → rerender-transitions.md
├── 长列表卡顿？
│   └── 使用 content-visibility → rendering-content-visibility.md
├── SSR 页面闪烁？
│   └── 内联脚本模式 → rendering-hydration-flicker.md
└── 服务器响应慢？
    └── 检查缓存 → server-cache-patterns.md

参考文件

文件	内容
hooks-guide.md	Hook 模式、决策指南、陷阱
effect-pitfalls.md	何时不应使用 useEffect
react-compiler.md	React 19+ 自动记忆化
state-structure.md	状态设计的 5 项原则
immutable-updates.md	数组/对象更新模式
references/	所有参考文件（共 19 个）

搜索规则：grep -l "关键词" references/