# Vercel React Best Practices

> 来自 Vercel 工程团队的 React 和 Next.js 性能优化指南。在编写、审查或重构 React/Next.js 代码以确保最佳性能模式时，应使用此技能。适用于涉及 React 组件、Next.js 页面、数据获取、包体积优化或性能提升的任务。

- Skill: `agent-skills/vercel-react-best-practices` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add agent-skills/vercel-react-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/agent-skills/vercel-react-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: MIT
- Author: agent-skills (https://skillmd.com/u/agent-skills)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/agent-skills/vercel-react-best-practices

---


# Vercel React 最佳实践

由 Vercel 维护的 React 和 Next.js 应用程序全面性能优化指南。包含涵盖 8 个类别的 70 条规则，并按影响力进行优先级排序，以指导自动化重构和代码生成。

## 何时应用

在以下场景参考这些指南：
- 编写新的 React 组件或 Next.js 页面
- 实现数据获取（客户端或服务端）
- 审查代码中的性能问题
- 重构现有的 React/Next.js 代码
- 优化包体积或加载时间

## 按优先级划分的规则类别

| 优先级 | 类别 | 影响力 | 前缀 |
|----------|----------|--------|--------|
| 1 | 消除瀑布流 (Waterfalls) | 关键 (CRITICAL) | `async-` |
| 2 | 包体积优化 | 关键 (CRITICAL) | `bundle-` |
| 3 | 服务端性能 | 高 (HIGH) | `server-` |
| 4 | 客户端数据获取 | 中高 (MEDIUM-HIGH) | `client-` |
| 5 | 重渲染优化 | 中 (MEDIUM) | `rerender-` |
| 6 | 渲染性能 | 中 (MEDIUM) | `rendering-` |
| 7 | JavaScript 性能 | 低中 (LOW-MEDIUM) | `js-` |
| 8 | 高级模式 | 低 (LOW) | `advanced-` |

## 快速参考

### 1. 消除瀑布流 (关键)

- `async-cheap-condition-before-await` - 在等待标志或远程值之前，先检查开销较小的同步条件
- `async-defer-await` - 将 await 移至实际使用的分支中
- `async-parallel` - 对独立的并行操作使用 Promise.all()
- `async-dependencies` - 对部分依赖使用 better-all
- `async-api-routes` - 在 API 路由中尽早开始 Promise，尽晚等待 (await)
- `async-suspense-boundaries` - 使用 Suspense 流式传输内容

### 2. 包体积优化 (关键)

- `bundle-barrel-imports` - 直接导入，避免使用桶文件 (barrel files)
- `bundle-analyzable-paths` - 优先使用可静态分析的导入和文件系统路径，以避免庞大的包和追踪
- `bundle-dynamic-imports` - 对重型组件使用 next/dynamic
- `bundle-defer-third-party` - 在注水 (hydration) 后加载分析/日志脚本
- `bundle-conditional` - 仅在功能激活时加载模块
- `bundle-preload` - 在悬停/聚焦时预加载以提升体感速度

### 3. 服务端性能 (高)

- `server-auth-actions` - 像对待 API 路由一样对 Server Actions 进行身份验证
- `server-cache-react` - 使用 React.cache() 进行逐请求的去重
- `server-cache-lru` - 使用 LRU 缓存进行跨请求缓存
- `server-dedup-props` - 避免在 RSC Props 中进行重复序列化
- `server-hoist-static-io` - 将静态 I/O（字体、Logo）提升至模块层级
- `server-no-shared-module-state` - 在 RSC/SSR 中避免模块级的可变请求状态
- `server-serialization` - 最小化传递给客户端组件的数据
- `server-parallel-fetching` - 重构组件以实现并行获取
- `server-parallel-nested-fetching` - 在 Promise.all 中链式处理每个条目的嵌套获取
- `server-after-nonblocking` - 对非阻塞操作使用 after()

### 4. 客户端数据获取 (中高)

- `client-swr-dedup` - 使用 SWR 进行自动请求去重
- `client-event-listeners` - 对全局事件监听器进行去重
- `client-passive-event-listeners` - 对滚动事件使用被动 (passive) 监听器
- `client-localstorage-schema` - 对 localStorage 数据进行版本控制并最小化

### 5. 重渲染优化 (中)

- `rerender-defer-reads` - 不要订阅仅在回调函数中使用的状态
- `rerender-memo` - 将开销大的工作提取到经过 memo 化的组件中
- `rerender-memo-with-default-value` - 提升非原始类型的默认 Props
- `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. 渲染性能 (中)

- `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` - 对条件判断使用三元运算符，而非 &&
- `rendering-usetransition-loading` - 优先使用 useTransition 处理加载状态
- `rendering-resource-hints` - 使用 React DOM 资源提示进行预加载
- `rendering-script-defer-async` - 在 script 标签上使用 defer 或 async

### 7. JavaScript 性能 (低中)

- `js-batch-dom-css` - 通过类名或 cssText 批量修改 CSS
- `js-index-maps` - 为重复查找构建 Map
- `js-cache-property-access` - 在循环中缓存对象属性
- `js-cache-function-results` - 在模块级 Map 中缓存函数结果
- `js-cache-storage` - 缓存 localStorage/sessionStorage 的读取结果
- `js-combine-iterations` - 将多个 filter/map 合并为一个循环
- `js-length-check-first` - 在进行昂贵比较前先检查数组长度
- `js-early-exit` - 从函数中尽早返回
- `js-hoist-regexp` - 将正则表达式创建提升至循环外部
- `js-min-max-loop` - 使用循环处理最小值/最大值，而非使用 sort
- `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
```

每个规则文件包含：
- 简要说明其重要性的原因
- 带有说明的错误代码示例
- 带有说明的正解代码示例
- 额外的上下文和参考资料

## 完整编译文档

查看包含所有规则展开内容的完整指南： `AGENTS.md`