vercel-react-best-practices

Vercel React 最佳实践

由仓库维护的 React 和 Next.js 指南，改编自 Vercel 的规则。请用它解决当前工作中具体的性能机制问题，而不是在整个应用中套用所有列出的模式。

优化前先确认相关性

确定受影响的路径、符合实际情况的工作负载，以及可避免的开销：依赖瀑布流、重复请求、过大的包、开销高昂的渲染或热点计算。使用代码和用法证据，或有代表性的跟踪记录／性能分析，来佐证相关机制。仅仅匹配某条规则或有影响等级标签，并不足以证明应当进行更改。

保留用户要求的范围、现有架构和正确性约定。优先使用现有功能或直接修改代码，再考虑添加库、缓存或抽象。如果现有代码已经足够，而拟议的优化没有明显的预期收益，就不要改动。正确性和安全性义务不取决于能否证明性能提升。

提出性能方面的主张时，应使用可比的工作负载和条件进行前后测量。如果无法测量，请说明有证据支持的机制，并将收益标注为预期或未经验证。不要把示例中的耗时、百分比或影响评级当作用户应用的实测结果。

依赖项与缓存归属

SWR、better-all、LRU 缓存和记忆化都是有条件的选项。如果项目现有的数据获取、调度或缓存功能可以满足需求，就应复用这些功能。只有在已证实的需求足以证明其维护和运行时成本合理时，才添加依赖；示例导入并不意味着必须安装该依赖。

添加缓存前，应确认是否存在重复工作、键的身份是否合适、缓存的所有者和生命周期、可接受的过期程度、失效机制、内存上限，以及数据是否需要按用户或租户隔离。选择范围最小且实用的缓存。缓存可变结果或依赖授权的结果时，不得破坏这些约定。

适用场景

在以下情况下，请参考这些指南：

• 编写新的 React 组件或 Next.js 页面
• 实现数据获取（客户端或服务端）
• 审查代码中的性能问题
• 重构现有 React/Next.js 代码
• 优化包体积或加载时间

按优先级划分的规则类别

这些评级表示在适用条件下调查问题的相对优先级。规则中的数值收益仅用于说明或源于特定场景，并非当前应用的保证或实测结果。审查时，应根据已证实的影响评估严重程度，而不要直接照搬规则评级。

优先级	类别	影响	前缀
1	消除瀑布流	严重	async-
2	优化包体积	严重	bundle-
3	服务端性能	高	server-
4	客户端数据获取	中高	client-
5	优化重新渲染	中	rerender-
6	渲染性能	中	rendering-
7	JavaScript 性能	低至中	js-
8	高级模式	低	advanced-

快速参考

1. 消除瀑布流（严重）

• async-cheap-condition-before-await - 在等待标志或远程值之前，先检查开销低的同步条件
• async-defer-await - 将 await 移入实际需要它的分支
• async-parallel - 使用 Promise.all() 并行执行互不依赖的操作
• async-dependencies - 直接表达实际依赖；确有必要时再考虑 better-all
• async-api-routes - 在 API 路由中尽早启动 Promise，延后等待
• async-suspense-boundaries - 使用 Suspense 流式传输内容

2. 优化打包体积（CRITICAL）

• bundle-barrel-imports - 直接导入，避免使用汇总文件
• bundle-analyzable-paths - 优先使用可静态分析的导入路径和文件系统路径，避免打包或跟踪范围过广
• bundle-dynamic-imports - 对大型组件使用 next/dynamic
• bundle-defer-third-party - 在 hydration 后加载分析和日志记录工具
• bundle-conditional - 仅在功能启用时加载模块
• bundle-preload - 在悬停或聚焦时预加载，提升感知速度

3. 服务端性能（HIGH）

• server-auth-actions - 像验证 API 路由一样验证服务端操作
• server-cache-react - 对受支持的服务端渲染中重复执行的工作，考虑使用 React.cache()
• server-cache-lru - 在数据时效性和隔离性允许复用时，考虑使用有界跨请求缓存
• server-dedup-props - 避免在 RSC 属性中重复序列化
• server-hoist-static-io - 将静态 I/O（字体、徽标）提升到模块级别
• server-no-shared-module-state - 避免在 RSC/SSR 中使用模块级可变请求状态
• server-serialization - 尽量减少传递给客户端组件的数据
• server-parallel-fetching - 重构组件以并行获取数据
• server-parallel-nested-fetching - 使用 Promise.all 按项目串联嵌套数据获取
• server-after-nonblocking - 使用 after() 执行非阻塞操作

4. 客户端数据获取（MEDIUM-HIGH）

• client-swr-dedup - 复用请求去重机制；如果适合项目的数据层，可考虑使用 SWR
• client-event-listeners - 对全局事件监听器进行去重
• client-passive-event-listeners - 为滚动事件使用被动监听器
• client-localstorage-schema - 对 localStorage 数据进行版本管理并尽量精简

5. 重新渲染优化（MEDIUM）

• rerender-defer-reads - 不要订阅仅在回调中使用的状态
• rerender-memo - 将开销较大的工作提取到经过记忆化的组件中
• rerender-memo-with-default-value - 将默认的非原始类型属性提升到组件外
• rerender-dependencies - 在 effect 中使用原始类型依赖项
• rerender-derived-state - 订阅派生布尔值，而不是原始值
• rerender-derived-state-no-effect - 在渲染期间派生状态，而不是在 effect 中
• rerender-functional-setstate - 使用函数式 setState 保持回调稳定
• rerender-lazy-state-init - 对开销较大的值，将函数传给 useState
• rerender-simple-expression-in-memo - 简单原始值无需使用 memo
• rerender-split-combined-hooks - 拆分依赖项彼此独立的 hooks
• rerender-move-effect-to-event - 将交互逻辑放入事件处理程序
• rerender-transitions - 使用 startTransition 处理非紧急更新
• rerender-use-deferred-value - 延迟开销较大的渲染，保持输入响应灵敏
• rerender-use-ref-transient-values - 使用 ref 保存频繁变化的临时值
• rerender-no-inline-components - 不要在组件内部定义组件

6. 渲染性能（MEDIUM）

• rendering-animate-svg-wrapper - 为 div 包装元素添加动画，而不是为 SVG 元素添加动画
• rendering-content-visibility - 对长列表使用 content-visibility
• rendering-hoist-jsx - 将静态 JSX 提取到组件外
• rendering-svg-precision - 降低 SVG 坐标精度
• rendering-hydration-no-flicker - 使用内联脚本处理仅限客户端的数据
• rendering-hydration-suppress-warning - 抑制预期会出现的不匹配警告
• rendering-activity - 使用 Activity 组件控制显示和隐藏
• rendering-conditional-render - 当条件可能为 0、NaN 或其他会被渲染的假值时，使用三元表达式代替 &&
• rendering-usetransition-loading - 优先使用 useTransition 处理加载状态
• rendering-resource-hints - 使用 React DOM 资源提示进行预加载
• rendering-script-defer-async - 在 script 标签上使用 defer 或 async

7. JavaScript 性能（低至中）

• js-batch-dom-css - 将布局读取与样式写入分开；连续写入本身已会批处理
• js-index-maps - 为重复查找构建 Map
• js-cache-property-access - 在循环中缓存对象属性
• js-cache-function-results - 仅在键和生命周期合适时缓存高开销的重复计算
• js-cache-storage - 仅在失效策略可靠时缓存频繁读取的存储数据
• js-combine-iterations - 将多个 filter/map 合并为一次循环
• js-length-check-first - 在进行高开销比较前检查数组长度
• js-early-exit - 尽早从函数返回
• js-hoist-regexp - 将 RegExp 的创建移到循环外
• js-min-max-loop - 使用循环求最小值/最大值，而非排序
• js-set-map-lookups - 使用 Set/Map 实现 O(1) 查找
• js-tosorted-immutable - 使用 toSorted() 实现不可变操作
• js-flatmap-filter - 使用 flatMap 一次完成映射和筛选
• js-request-idle-callback - 将非关键工作推迟到浏览器空闲时间

8. 高级模式（低）

• advanced-effect-event-deps - 不要将 useEffectEvent 的结果放入 effect 依赖项
• advanced-event-handler-refs - 将事件处理程序存储在 ref 中
• advanced-init-once - 每次应用加载时只初始化一次
• advanced-use-latest - 使用 useLatest 获取稳定的回调 ref

使用方法

使用索引选择与已识别机制相关的规则。阅读对应的单独文件及其适用示例；仅在具体依赖或未解决的问题需要时才加载其他规则。默认情况下，不要阅读整个编译版指南。

rules/async-parallel.md
rules/bundle-barrel-imports.md

根据示例所声明的工作负载和假设来理解示例标签。调整示例时，保留框架/版本兼容性，以及实际的错误、顺序、缓存和所有权约定。

编译版参考

rules/ 包含规范指导。AGENTS.md 是供有意阅读完整指南时使用的编译版参考，并非运行时入口。维护规则时，请在同一次更改中同步其编译版章节，以及受影响的索引或元数据；维护详情请参阅此技能的 README.md。