前言¶

用 Cursor、Claude Code、Codex 这类 AI 编程工具写 React / Next.js 时，组件和页面往往能很快跑起来，但上线后常见的问题并没有消失：接口一个接一个串行等待、客户端 bundle 越来越大、无关状态一变就整页重渲染。性能问题通常是「事后救火」——发版感觉变慢了，再去查 useMemo、再去拆包，成本高，也容易改错地方。

Vercel 工程团队把多年在生产环境里踩过的坑，整理成一套面向 AI Agent 的规则库，打包成 Agent Skill：react-best-practices（Skill 正式名称为 vercel-react-best-practices）。装上之后，Agent 在写组件、做数据获取、做重构时，会按「影响优先级」去套这些规则，而不是先纠结微优化。

本文按官方仓库与 Vercel 博客核实后的信息，介绍它是什么、规则怎么分、如何安装启用，以及怎么在日常开发里用起来。

这是什么¶

vercel-react-best-practices 是 Vercel 官方维护的 Agent Skill，收录在仓库 vercel-labs/agent-skills 的 skills/react-best-practices/ 目录下。许可证为 MIT，SKILL.md 中标注 author: vercel、version: "1.0.0"。

一句话定位：给 React / Next.js 的性能优化指南，专门写成 AI Agent 可读取、可执行的 Skill 格式，用于编写、审查、重构时对齐同一套高性能模式。

根据当前 SKILL.md，规则集包含 70 条规则、8 个类别，按影响从高到低排序，用来指导自动化重构与代码生成。需要说明的是：2026 年 1 月 Vercel 官方博客与仓库 README 仍写「40+ rules」；以一手资料 SKILL.md 为准，规则数量已扩展到 70。早期宣传里的「40+」可以理解为发布时的规模，不影响「按影响优先级组织」这一核心设计。

它解决的核心问题也很直接：让性能工作从「症状驱动」变成「按优先级改对的地方」——先消请求瀑布、再砍 bundle，再谈服务端与客户端细节，最后才是微优化。

核心功能与亮点¶

1. 按影响排序的八大类规则¶

官方把规则分成 8 类，并标明优先级与前缀，方便 Agent 按文件名定位细则：

优先级	类别	影响	前缀
1	Eliminating Waterfalls（消除瀑布）	CRITICAL	`async-`
2	Bundle Size Optimization（包体积）	CRITICAL	`bundle-`
3	Server-Side Performance（服务端）	HIGH	`server-`
4	Client-Side Data Fetching（客户端数据）	MEDIUM-HIGH	`client-`
5	Re-render Optimization（重渲染）	MEDIUM	`rerender-`
6	Rendering Performance（渲染）	MEDIUM	`rendering-`
7	JavaScript Performance（JS 微优化）	LOW-MEDIUM	`js-`
8	Advanced Patterns（进阶模式）	LOW	`advanced-`

Vercel 博客强调：大多数性能工作失败，是因为从栈太低的地方动手。若请求瀑布多等了几百毫秒，再怎么抠 useMemo 也救不了首屏；若每页多塞 300KB JS，循环里省几微秒也几乎无感。因此 CRITICAL 级先盯 async waterfall 与 bundle。

2. 每条规则都有「错例 / 对例」¶

细则文件在 Skill 目录的 rules/ 下（例如 rules/async-parallel.md）。每条通常包含：为什么重要、错误写法、正确写法、补充说明。全部规则还会汇总进 AGENTS.md，方便 Agent 一次性查阅。

以官方示例 async-parallel（独立异步操作用 Promise.all）为例：

错误（串行，三次往返）：

const user = await fetchUser()
const posts = await fetchPosts()
const comments = await fetchComments()

正确（并行，一轮往返）：

const [user, posts, comments] = await Promise.all([
  fetchUser(),
  fetchPosts(),
  fetchComments()
])

博客里还有另一类常见瀑布：分支里根本用不到的数据，却在分支判断之前就 await 了——正确做法是把 await 挪到真正需要的分支里（对应规则如 async-defer-await）。

3. 触发场景写进 Skill 描述¶

SKILL.md 的 description 写明：在编写、审查或重构 React / Next.js 代码、涉及组件、页面、数据获取、bundle 优化或性能改进时，应使用本 Skill。安装后，Agent 在相关任务上会自动引用这些指南。

4. 来源是生产实践，不是纸上谈兵¶

Vercel 博客写明：规则来自十年以上的 React / Next.js 优化经验，以及真实生产代码库里的性能工作（例如把多次扫描消息列表合并成单次遍历、把无依赖的 await 并行化、用惰性初始化避免每次渲染都 JSON.parse localStorage 等）。Skill 把这些经验固化成 Agent 可反复执行的检查清单。

安装与启用¶

该 Skill 遵循通用 Agent Skills 格式，可用官方 Skills CLI 安装。Vercel 文档说明：Skills 可与 Claude Code、GitHub Copilot、Cursor、Cline 等 18+ 种 AI Agent 配合使用。

只装这一条 Skill（推荐）¶

官方文档与 skills.sh 给出的安装命令为：

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices

也可写成完整仓库 URL：

npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices

注意：安装时 --skill 参数要用正式名称 vercel-react-best-practices（2026 年 6 月仓库将 name 从 react-best-practices 更名为该名称），目录名仍是 skills/react-best-practices/。

安装整个 agent-skills 仓库¶

若希望一并装上同仓库其他 Skill（如 web-design-guidelines、composition-patterns 等）：

npx skills add vercel-labs/agent-skills

CLI 会解析仓库、发现其中的 Skill，并检测本机已安装的编码 Agent，再引导你选择安装范围与方式。

项目级与全局¶

默认安装到当前项目（便于提交进仓库、团队共享）。
加 -g 可装到用户级，跨项目可用：

npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -g

环境要求：Skills CLI 需要 Node.js 18+，可用 npx 直接跑，不必先全局安装 CLI。

安装完成后一般无需额外配置：相关任务出现时，Agent 会按 Skill 说明自动引用规则。

典型用法示例¶

官方 README 给出的用法很直接。安装后，在 Cursor / Claude Code / Codex 等工具里用自然语言触发即可，例如：

Review this React component for performance issues

Help me optimize this Next.js page

更具体一些，可以点名关注 CRITICAL 级问题：

请按 vercel-react-best-practices 审查这个页面：
1. 是否存在异步请求瀑布（该并行却串行、该延后 await 却提前 await）
2. 是否有 barrel import / 过重的客户端依赖导致 bundle 膨胀
3. 给出对应规则前缀（如 async-、bundle-）和改法

Agent 侧会去读 rules/ 下的细则或 AGENTS.md。你也可以自己打开某条规则对照学习，例如：

rules/async-parallel.md
rules/bundle-barrel-imports.md
rules/server-cache-react.md

CRITICAL / HIGH 类里还有一批值得优先记住的规则名（摘自 SKILL.md 速查）：

async-parallel：独立操作用 Promise.all
async-defer-await：只在真正用到的分支里 await
async-suspense-boundaries：用 Suspense 流式输出
bundle-barrel-imports：避免 barrel 文件，直接按需 import
bundle-dynamic-imports：重型组件用 next/dynamic
server-cache-react：用 React.cache() 做请求内去重
server-parallel-fetching：调整组件结构以并行拉取数据

适用场景与注意事项¶

适合谁、什么时候用¶

日常用 AI 写 React 组件、Next.js App Router 页面
Code Review 时专门查性能（瀑布、包体积、RSC 序列化、重渲染）
重构已有页面：先按 CRITICAL → HIGH 排期，再处理 MEDIUM / LOW
团队希望「人和 Agent 用同一套性能决策」，减少风格漂移

使用时注意¶

先高优先级，再微优化。 规则本身已按影响排序；先消瀑布、砍 bundle，再去抠 js-* 微优化，否则收益很小。
规则数量以当前 SKILL.md 为准。 博客/README 的「40+」与 SKILL.md 的「70」并存时，以仓库内 Skill 元数据为准。
名称别装错。 对外常称 react-best-practices，CLI 的 --skill 要用 vercel-react-best-practices。
它是指南，不是运行时监控。 Skill 不会替你采集线上 RUM；改完仍建议结合真实指标与构建分析验证。
部分规则依赖 Next.js / React 新特性（如 after()、Activity、useEffectEvent 等）。项目版本较旧时，Agent 可能给出当前栈用不了的写法，需要人工对照依赖版本取舍。

小结¶

react-best-practices（vercel-react-best-practices）把 Vercel 工程侧的 React / Next.js 性能经验，收成一套按影响排序的 Agent Skill：先消除瀑布与 bundle 浪费，再覆盖服务端、客户端数据、重渲染与进阶模式。对已经把大量样板代码交给 AI 的前端团队来说，它更像是「质量守门员」——让生成与重构默认对齐同一套高性能模式。

官方地址：

Skill 目录：https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices
skills.sh 页面：https://skills.sh/vercel-labs/agent-skills/react-best-practices
介绍博文：https://vercel.com/blog/introducing-react-best-practices
Agent Skills 文档：https://vercel.com/docs/agent-resources/skills

用 react-best-practices 给 AI 编程加上 React 性能守门员

前言¶

这是什么¶

核心功能与亮点¶

1. 按影响排序的八大类规则¶

2. 每条规则都有「错例 / 对例」¶

3. 触发场景写进 Skill 描述¶

4. 来源是生产实践，不是纸上谈兵¶

安装与启用¶

只装这一条 Skill（推荐）¶

安装整个 agent-skills 仓库¶

项目级与全局¶

典型用法示例¶

适用场景与注意事项¶

适合谁、什么时候用¶

使用时注意¶

小结¶

精选优惠券

用 react-best-practices 给 AI 编程加上 React 性能守门员

前言¶

这是什么¶

核心功能与亮点¶

1. 按影响排序的八大类规则¶

2. 每条规则都有「错例 / 对例」¶

3. 触发场景写进 Skill 描述¶

4. 来源是生产实践，不是纸上谈兵¶

安装与启用¶

只装这一条 Skill（推荐）¶

安装整个 agent-skills 仓库¶

项目级与全局¶

典型用法示例¶

适用场景与注意事项¶

适合谁、什么时候用¶

使用时注意¶

小结¶

精选优惠券

相关文章