前言¶
用 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.allasync-defer-await：只在真正用到的分支裏awaitasync-suspense-boundaries：用 Suspense 流式輸出bundle-barrel-imports：避免 barrel 文件，直接按需 importbundle-dynamic-imports：重型組件用next/dynamicserver-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
