从 Vercel Engineering 的 58 条规则看 ag-kit 的 Next.js 与 React 性能优化技能体系【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit本文以 ag-kit 仓库中 .agents/skills/nextjs-react-expert/SKILL.md 技能文档为主体系统讲解这套源自 Vercel Engineering 的 Next.js / React 性能优化规则集如何按影响度分级CRITICAL → LOW组织 58 条优化规则、如何通过决策树快速定位性能瓶颈并深入解析消除数据瀑布、包体积控制与 Next.js 16 Cache Components 三大核心主题的实现细节。读完本文你可以掌握一套可落地的性能评审流程并能使用仓库自带的自动审计脚本对任意 React 项目进行性能体检。一、技能定位面向 AI Agent 的性能专家知识包ag-kit 是一个为 AI 编码 Agent 提供规则、技能Skills、工作流Workflows与脚本工具链的仓库。SKILL.md 的前置元数据定义了这个技能的触发条件与工具边界name: nextjs-react-expert description: React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations. when_to_use: When building React components, optimizing Next.js performance, eliminating waterfalls, or reducing bundle size. For React/Next.js web projects. allowed-tools: Read, Write, Edit, Glob, Grep, Bash version: 1.0.0从元数据可以看出设计意图当 Agent 处于构建 React 组件、优化 Next.js 性能、消除瀑布式请求、缩减包体积、性能评审等场景时应加载该技能且只允许使用只读检索与 Bash 类工具避免 Agent 在评审过程中越权修改项目。技能的核心哲学只有一句话先消除瀑布waterfalls再优化包体积最后做微观优化Eliminate waterfalls first, optimize bundles second, then micro-optimize。全部规则按这一优先级排序共 58 条规则分布在 8 个类别中外加一个仅适用于 Next.js 16 的 Cache Components 章节。二、内容地图与选择性阅读机制该技能没有把所有规则塞在一个巨型文件里而是拆成 9 个主题文件并在 SKILL.md 中给出内容地图Content Map要求 Agent只读取与当前任务相关的章节文件影响度规则数适用场景1-async-eliminating-waterfalls.mdCRITICAL6页面加载慢、串行 API 调用、取数瀑布2-bundle-bundle-size-optimization.mdCRITICAL5包体积大、TTI 慢、首屏加载慢3-server-server-side-performance.mdHIGH7SSR 慢、API 路由优化、服务端瀑布4-client-client-side-data-fetching.mdMEDIUM-HIGH4客户端数据管理、SWR 模式、请求去重5-rerender-re-render-optimization.mdMEDIUM12过度重渲染、memo 化6-rendering-rendering-performance.mdMEDIUM9渲染瓶颈、虚拟化、图片优化7-js-javascript-performance.mdLOW-MEDIUM12热点循环、缓存、正则提升8-advanced-advanced-patterns.mdVARIABLE3useLatest、init-once 等高级模式9-cache-components.mdCRITICAL4 小节仅限 Next.js 16use cache、cacheLife、PPR、cacheTag这种索引 分册结构本身就是一种工程实践Agent 的上下文窗口有限全量加载 58 条规则既浪费 token 又容易稀释重点。SKILL.md 中的Selective Reading Rule甚至用红色警示标注性能评审必须从 CRITICAL 章节1、2开始再向下推进 HIGH / MEDIUM。快速决策树从症状到章节文档给出了一个性能问题 → 阅读章节的映射决策树这是整套技能里最实用的导航页面加载慢 / TTI 长 → 章节 1瀑布 章节 2包体积主包超过 200KB → 章节 2检查动态导入、barrel import、tree-shakingSSR 慢 → 章节 3检查并行取数与流式渲染重渲染过多 / UI 卡顿 → 章节 5检查React.memo、useMemo、useCallback渲染性能问题 → 章节 6检查虚拟化、layout thrashing客户端取数问题 → 章节 4检查 SWR 去重、localStorage 缓存需要高级模式 → 章节 8Next.js 16 缓存与 PPR → 章节 9对应的综合优化顺序则是先做 CRITICAL每个瀑布增加 100–500ms 以上网络延迟包体积直接影响 TTI 与 LCP再做 HIGH消除服务端瀑布然后 MEDIUM客户端取数、重渲染、渲染性能最后才是 LOW 级别的打磨。SKILL.md 同时给出了新手→进阶→高级的学习路径新手只读章节 1、2进阶补章节 3、5高级则通读全部并加章节 8。三、章节 1 深潜消除数据瀑布CRITICAL1-async-eliminating-waterfalls.md 包含 6 条规则是整套技能中优先级最高的部分。核心论断是每个串行await都会叠加一份完整的网络延迟。以下挑选其中四条最具代表性的规则展开。规则 1.1把await推迟到真正需要的分支如果某个await的结果只在部分执行路径中使用就应把取数推迟进那个分支避免被跳过的分支白白等待// 错误两个分支都等待了 fetchUserData async function handleRequest(userId: string, skipProcessing: boolean) { const userData await fetchUserData(userId) // 即使 skipProcessing 为 true 也要等 if (skipProcessing) { return { skipped: true } } return processUserData(userData) } // 正确只在需要的分支取数 async function handleRequest(userId: string, skipProcessing: boolean) { if (skipProcessing) { return { skipped: true } // 立即返回不等待 } const userData await fetchUserData(userId) return processUserData(userData) }文档还给出了一个更典型的早退优化案例updateResource中先查资源是否存在再查权限——因为资源不存在的早退路径完全不需要权限数据把fetchPermissions挪到存在性检查之后冷路径就不用多付一次网络往返。规则 1.2基于依赖关系最大化并行当操作之间存在部分依赖C 依赖 A但与 B 无关时朴素写法会把 C 串行放在 A 之后、B 又只能等 A 与 C 全部结束。Vercel 的better-all库可以让每个任务在最早可行的时刻启动import { all } from better-all const { user, config, profile } await all({ async user() { return fetchUser() }, async config() { return fetchConfig() }, async profile() { // profile 依赖 user但与 config 并行 return fetchProfile((await this.$.user).id) } })不想引入依赖时等价的手动写法是先创建所有 Promise最后统一Promise.allconst userPromise fetchUser() const profilePromise userPromise.then(user fetchProfile(user.id)) const [user, config, profile] await Promise.all([ userPromise, fetchConfig(), profilePromise ])规则 1.3在 API 路由 / Server Actions 中打断瀑布链关键技巧是独立操作立即发起不等待有依赖的操作稍后再 await。以一个 GET 路由为例// 错误config 等 authdata 又等两者 export async function GET(request: Request) { const session await auth() const config await fetchConfig() const data await fetchData(session.user.id) return Response.json({ data, config }) } // 正确auth 与 config 同时启动 export async function GET(request: Request) { const sessionPromise auth() const configPromise fetchConfig() const session await sessionPromise const [config, data] await Promise.all([ configPromise, fetchData(session.user.id) ]) return Response.json({ data, config }) }规则 1.4 与 1.5Promise.all()与战略性 Suspense 边界对于完全没有依赖的取数标准答案就是Promise.all([...])把3 次串行往返压缩为1 次并行往返。更具 Next.js App Router 特色的是规则 1.5——用Suspense边界替代在异步组件里await后再返回整棵 JSX。错误写法让整个页面布局Sidebar / Header / Footer都被中间一块数据的取数阻塞正确写法是function Page() { return ( div divSidebar/div divHeader/div div Suspense fallback{Skeleton /} DataDisplay / {/* 只有这个组件内部 await 数据 */} /Suspense /div divFooter/div /div ) } async function DataDisplay() { const data await fetchData() // 只阻塞自己 return div{data.content}/div }文档进一步给出跨组件共享 Promise的变体页面顶层先发起const dataPromise fetchData()但不await然后把 Promise 传给多个子组件各组件用 React 19 的use(dataPromise)解包——同一次请求被多个组件复用布局立即渲染数据随流到达。同时文档明确列出了不适用该模式的场景影响布局定位的关键数据、首屏 SEO 关键内容、查询本身很小很快、以及需要避免骨架→内容布局跳动的页面。这是一个典型的更快首绘 vs 潜在布局偏移的权衡取舍。规则 1.6Next.js 16 的after()与connection()针对 Next.js 16文档引入两个新 API 来避免阻塞主线程after()把不影响首屏 UI 的逻辑日志、埋点、邮件放到响应发出之后执行不再占用渲染关键路径connection()在组件内显式声明我是动态的不要被我拖住静态预渲染让页面其他部分可以继续独立流式输出。四、章节 2 深潜包体积优化CRITICAL2-bundle-bundle-size-optimization.md 共 5 条规则直接作用于 Time to Interactive 与 LCP。最有信息量的是规则 2.1避免 barrel 文件导入流行的图标/组件库入口文件可能包含上万条 re-export文档给出的量化数据是lucide-react的整包导入约加载 1,583 个模块开发环境额外约 2.8s、mui/material约 2,225 个模块约 4.2s冷启动的运行时成本为 200–800ms直接深路径导入如lucide-react/dist/esm/icons/check只加载用到的 3 个模块约 2KB 对比约 1MBtree-shaking 为什么救不了你当库被标记为 external不打包时bundler 根本无法优化它而若为了 tree-shaking 把整个库纳入打包构建又要分析全部模块图构建时间显著变长Next.js 13.5 提供了折中方案experimental.optimizePackageImports配置让开发者保留import { Check, X, Menu } from lucide-react的 ergonomics构建期自动改写为深路径导入。文档列出了常见受影响的库清单lucide-react、mui/material、tabler/icons-react、react-icons、headlessui/react、radix-ui/react-*、lodash、ramda、date-fns、rxjs、react-use。规则 2.2条件加载模块展示了另一个维度仅在功能被激活时才import()大模块如动画帧数据并用typeof window ! undefined守卫防止该模块被打进 SSR bundle同时优化服务端包体积与构建速度。规则 2.3 则指出分析、日志、错误追踪等第三方库应在 hydration 之后再加载不阻塞初始 bundle。ag-kit 自身的实践佐证仓库内的 web/package.json 声明了lucide-react依赖^0.562.0且 search-dialog.tsx、code-block.tsx 等多个组件都从lucide-react主入口导入图标——按本技能规则 2.1 的标准这正是可以被深路径导入或optimizePackageImports优化的一类真实场景。技能文档与宿主仓库的实际代码形成了可互相印证的关系。五、章节 3 与章节 9服务端性能与 Next.js 16 Cache Components3-server-server-side-performance.md 的 7 条规则中第一条Rule 3.1把安全当作品能的一部分带use server的 Server Action 与 API 路由一样是公开端点可以被直接调用因此认证与授权必须写在 Action 内部而不能只依赖 middleware、布局守卫或页面级检查。文档给出的正确模式是先校验输入如用 zod schema→ 再验证身份 → 再校验权限 → 最后执行变更的固定顺序。9-cache-components.md 是整套规则集中唯一带版本门槛的章节文档开头明确警告不要未经兼容性检查就用于 Next.js 15 及更早版本。它描述了 Next.js 16 从Segment 级缓存到组件级缓存的范式转移包含 4 个小节use cache指令可作用于 Server Component 或普通函数文档强调粒度化应用——只包住真正需要缓存的取数函数或组件cacheLife用预定义 profile 声明缓存的新鲜度/过期度profile 从seconds高频更新到max持久缓存直到失效default为 1 年 stale 时间cacheTag按需失效给缓存数据打标签之后在 Server Action 中二选一——revalidateTag后台 SWR 失效或updateTag立即读写一致更新PPRPartial Prerendering通过next.config.ts中的cacheComponents标志启用且要求把动态的 Cache Components 包进Suspense边界才能生效。这一章节与 ag-kit 的 web 项目高度契合web/package.json 中next版本为^16.2.11正处于该章节标注的 Next.js 16 时代因此章节 9 的模式在仓库上下文中是可参考的当然web 项目当前是否启用了cacheComponents需要以 next.config.ts 的实际配置为准。六、自动化验证内置性能审计脚本该技能不只是纸上规则还附带了可执行的审计工具 scripts/react_performance_checker.pySKILL.md 中给出的调用方式为python scripts/react_performance_checker.py project_path从源码实现可以看到它的工程细节扫描根发现_discover_scan_roots优先在path和path/web下寻找同时声明了next或react依赖的package.json再以src/若存在作为扫描根——这恰好适配 ag-kit 这类根目录是 Agent 工具链、web 子目录才是 Next.js 应用的 monorepo 形态目录过滤跳过.git、.next、node_modules、.agents等 10 类目录瀑布检测对应章节 1用正则await\s\w.*?\n\s*await\s\w匹配同一文件内连续两个await命中即报告 CRITICAL 级Sequential awaits detected并附上修复建议Use Promise.all() for parallel fetchingbarrel import 检测对应章节 2只把显式的from /...index/from ../...index视为 barrel 嫌疑代码注释特意说明——TypeScript 中无扩展名的相对导入如from ./foo是常态不能作为 barrel 证据避免误报。这说明该脚本是规则 → 可执行检查的闭环Agent 评审性能问题时可以先跑脚本拿到机器可判定的疑点清单再依据分册规则做人工判断。七、生产上线前的性能评审清单SKILL.md 末尾给出一份分优先级的上线检查清单可直接作为代码评审的 checklist 使用Critical必须修复不存在串行取数瀑布已消除主包体积 200KB应用代码中无 barrel import大组件使用动态导入可并行处已并行取数High Priority该用 Server Components 的地方已使用API 路由无 N1 查询取数场景有 Suspense 边界可用静态生成的已静态生成Medium Priority昂贵计算已 memo 化超过 100 项的列表已虚拟化图片使用next/image无不必要的重渲染Low Priority打磨热点循环已优化RegExp 已提升到作用域外循环内属性访问已缓存配套的反模式列表同样值得贴在团队规约里不要对独立操作使用串行await不要为用一个函数而导入整个库不要在应用代码中用 barrel 导出不要跳过对大组件的动态导入不要在useEffect里无去重地取数不要在有 Server Components 可用时滥用 client components。正面清单则包括Promise.all()并行取数、dynamic(() import(./Heavy))动态导入、import { specific } from library/specific直接导入、用 Suspense 改善加载体验、优先使用平台内建优化next/image、next/font。八、最佳实践总结性能思维模型SKILL.md 收尾部分提炼了五条黄金法则先测量——用 React DevTools Profiler、Chrome DevTools 定位不靠猜最大收益优先——瀑布 → 包体积 → 服务端 → 微观优化不过度优化——聚焦真实瓶颈善用平台特性——Next.js 内建了大量优化站在用户角度——真实网络与设备条件才是标准。文档最后给出的性能心智模型把规则浓缩成几行直觉值得记住每个串行的await 一个潜在瀑布每个import 一个潜在的包体积膨胀点每次不必要的重渲染 浪费的计算Server Components 更少的需要下发的 JavaScriptMeasure, dont guess测量别猜。九、如何在 ag-kit 生态中组合使用从 SKILL.md 的Related Skills表可以看出这个技能被设计为更大能力网络中的一环API 设计对应api-patterns、数据库对应database-design、测试对应testing-patterns、TypeScript 对应typescript-expert、部署对应deployment-procedures——这些技能目录在 .agents/skills/ 下均真实存在。结合本仓库的实际情况一个可落地的使用流程是确认目标项目版本web/package.json 显示 Next.js 16 React 19因此章节 9 的 Cache Components 规则在适用范围之内遇到性能问题时先按快速决策树定位到具体章节文件1–9 分册之一精读对应规则运行python scripts/react_performance_checker.py web获取瀑布与 barrel import 的机器扫描结果按Critical → High → Medium → Low的顺序修复最后对照评审清单逐项打勾。这套技能的价值不在于单条规则本身——Promise.all、next/image、React.memo都是熟悉的概念——而在于它把 58 条零散经验按影响度分级 症状决策树 可执行验证脚本组织成了 Agent 与人类工程师都能快速检索、按需加载、闭环验证的体系。对于正在维护 Next.js 16 项目的团队这种分册索引 选择性阅读的技能组织方式本身也值得借鉴。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从 Vercel Engineering 的 58 条规则看 ag-kit 的 Next.js 与 React 性能优化技能体系
从 Vercel Engineering 的 58 条规则看 ag-kit 的 Next.js 与 React 性能优化技能体系【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit本文以 ag-kit 仓库中 .agents/skills/nextjs-react-expert/SKILL.md 技能文档为主体系统讲解这套源自 Vercel Engineering 的 Next.js / React 性能优化规则集如何按影响度分级CRITICAL → LOW组织 58 条优化规则、如何通过决策树快速定位性能瓶颈并深入解析消除数据瀑布、包体积控制与 Next.js 16 Cache Components 三大核心主题的实现细节。读完本文你可以掌握一套可落地的性能评审流程并能使用仓库自带的自动审计脚本对任意 React 项目进行性能体检。一、技能定位面向 AI Agent 的性能专家知识包ag-kit 是一个为 AI 编码 Agent 提供规则、技能Skills、工作流Workflows与脚本工具链的仓库。SKILL.md 的前置元数据定义了这个技能的触发条件与工具边界name: nextjs-react-expert description: React and Next.js performance optimization from Vercel Engineering. Use when building React components, optimizing performance, eliminating waterfalls, reducing bundle size, reviewing code for performance issues, or implementing server/client-side optimizations. when_to_use: When building React components, optimizing Next.js performance, eliminating waterfalls, or reducing bundle size. For React/Next.js web projects. allowed-tools: Read, Write, Edit, Glob, Grep, Bash version: 1.0.0从元数据可以看出设计意图当 Agent 处于构建 React 组件、优化 Next.js 性能、消除瀑布式请求、缩减包体积、性能评审等场景时应加载该技能且只允许使用只读检索与 Bash 类工具避免 Agent 在评审过程中越权修改项目。技能的核心哲学只有一句话先消除瀑布waterfalls再优化包体积最后做微观优化Eliminate waterfalls first, optimize bundles second, then micro-optimize。全部规则按这一优先级排序共 58 条规则分布在 8 个类别中外加一个仅适用于 Next.js 16 的 Cache Components 章节。二、内容地图与选择性阅读机制该技能没有把所有规则塞在一个巨型文件里而是拆成 9 个主题文件并在 SKILL.md 中给出内容地图Content Map要求 Agent只读取与当前任务相关的章节文件影响度规则数适用场景1-async-eliminating-waterfalls.mdCRITICAL6页面加载慢、串行 API 调用、取数瀑布2-bundle-bundle-size-optimization.mdCRITICAL5包体积大、TTI 慢、首屏加载慢3-server-server-side-performance.mdHIGH7SSR 慢、API 路由优化、服务端瀑布4-client-client-side-data-fetching.mdMEDIUM-HIGH4客户端数据管理、SWR 模式、请求去重5-rerender-re-render-optimization.mdMEDIUM12过度重渲染、memo 化6-rendering-rendering-performance.mdMEDIUM9渲染瓶颈、虚拟化、图片优化7-js-javascript-performance.mdLOW-MEDIUM12热点循环、缓存、正则提升8-advanced-advanced-patterns.mdVARIABLE3useLatest、init-once 等高级模式9-cache-components.mdCRITICAL4 小节仅限 Next.js 16use cache、cacheLife、PPR、cacheTag这种索引 分册结构本身就是一种工程实践Agent 的上下文窗口有限全量加载 58 条规则既浪费 token 又容易稀释重点。SKILL.md 中的Selective Reading Rule甚至用红色警示标注性能评审必须从 CRITICAL 章节1、2开始再向下推进 HIGH / MEDIUM。快速决策树从症状到章节文档给出了一个性能问题 → 阅读章节的映射决策树这是整套技能里最实用的导航页面加载慢 / TTI 长 → 章节 1瀑布 章节 2包体积主包超过 200KB → 章节 2检查动态导入、barrel import、tree-shakingSSR 慢 → 章节 3检查并行取数与流式渲染重渲染过多 / UI 卡顿 → 章节 5检查React.memo、useMemo、useCallback渲染性能问题 → 章节 6检查虚拟化、layout thrashing客户端取数问题 → 章节 4检查 SWR 去重、localStorage 缓存需要高级模式 → 章节 8Next.js 16 缓存与 PPR → 章节 9对应的综合优化顺序则是先做 CRITICAL每个瀑布增加 100–500ms 以上网络延迟包体积直接影响 TTI 与 LCP再做 HIGH消除服务端瀑布然后 MEDIUM客户端取数、重渲染、渲染性能最后才是 LOW 级别的打磨。SKILL.md 同时给出了新手→进阶→高级的学习路径新手只读章节 1、2进阶补章节 3、5高级则通读全部并加章节 8。三、章节 1 深潜消除数据瀑布CRITICAL1-async-eliminating-waterfalls.md 包含 6 条规则是整套技能中优先级最高的部分。核心论断是每个串行await都会叠加一份完整的网络延迟。以下挑选其中四条最具代表性的规则展开。规则 1.1把await推迟到真正需要的分支如果某个await的结果只在部分执行路径中使用就应把取数推迟进那个分支避免被跳过的分支白白等待// 错误两个分支都等待了 fetchUserData async function handleRequest(userId: string, skipProcessing: boolean) { const userData await fetchUserData(userId) // 即使 skipProcessing 为 true 也要等 if (skipProcessing) { return { skipped: true } } return processUserData(userData) } // 正确只在需要的分支取数 async function handleRequest(userId: string, skipProcessing: boolean) { if (skipProcessing) { return { skipped: true } // 立即返回不等待 } const userData await fetchUserData(userId) return processUserData(userData) }文档还给出了一个更典型的早退优化案例updateResource中先查资源是否存在再查权限——因为资源不存在的早退路径完全不需要权限数据把fetchPermissions挪到存在性检查之后冷路径就不用多付一次网络往返。规则 1.2基于依赖关系最大化并行当操作之间存在部分依赖C 依赖 A但与 B 无关时朴素写法会把 C 串行放在 A 之后、B 又只能等 A 与 C 全部结束。Vercel 的better-all库可以让每个任务在最早可行的时刻启动import { all } from better-all const { user, config, profile } await all({ async user() { return fetchUser() }, async config() { return fetchConfig() }, async profile() { // profile 依赖 user但与 config 并行 return fetchProfile((await this.$.user).id) } })不想引入依赖时等价的手动写法是先创建所有 Promise最后统一Promise.allconst userPromise fetchUser() const profilePromise userPromise.then(user fetchProfile(user.id)) const [user, config, profile] await Promise.all([ userPromise, fetchConfig(), profilePromise ])规则 1.3在 API 路由 / Server Actions 中打断瀑布链关键技巧是独立操作立即发起不等待有依赖的操作稍后再 await。以一个 GET 路由为例// 错误config 等 authdata 又等两者 export async function GET(request: Request) { const session await auth() const config await fetchConfig() const data await fetchData(session.user.id) return Response.json({ data, config }) } // 正确auth 与 config 同时启动 export async function GET(request: Request) { const sessionPromise auth() const configPromise fetchConfig() const session await sessionPromise const [config, data] await Promise.all([ configPromise, fetchData(session.user.id) ]) return Response.json({ data, config }) }规则 1.4 与 1.5Promise.all()与战略性 Suspense 边界对于完全没有依赖的取数标准答案就是Promise.all([...])把3 次串行往返压缩为1 次并行往返。更具 Next.js App Router 特色的是规则 1.5——用Suspense边界替代在异步组件里await后再返回整棵 JSX。错误写法让整个页面布局Sidebar / Header / Footer都被中间一块数据的取数阻塞正确写法是function Page() { return ( div divSidebar/div divHeader/div div Suspense fallback{Skeleton /} DataDisplay / {/* 只有这个组件内部 await 数据 */} /Suspense /div divFooter/div /div ) } async function DataDisplay() { const data await fetchData() // 只阻塞自己 return div{data.content}/div }文档进一步给出跨组件共享 Promise的变体页面顶层先发起const dataPromise fetchData()但不await然后把 Promise 传给多个子组件各组件用 React 19 的use(dataPromise)解包——同一次请求被多个组件复用布局立即渲染数据随流到达。同时文档明确列出了不适用该模式的场景影响布局定位的关键数据、首屏 SEO 关键内容、查询本身很小很快、以及需要避免骨架→内容布局跳动的页面。这是一个典型的更快首绘 vs 潜在布局偏移的权衡取舍。规则 1.6Next.js 16 的after()与connection()针对 Next.js 16文档引入两个新 API 来避免阻塞主线程after()把不影响首屏 UI 的逻辑日志、埋点、邮件放到响应发出之后执行不再占用渲染关键路径connection()在组件内显式声明我是动态的不要被我拖住静态预渲染让页面其他部分可以继续独立流式输出。四、章节 2 深潜包体积优化CRITICAL2-bundle-bundle-size-optimization.md 共 5 条规则直接作用于 Time to Interactive 与 LCP。最有信息量的是规则 2.1避免 barrel 文件导入流行的图标/组件库入口文件可能包含上万条 re-export文档给出的量化数据是lucide-react的整包导入约加载 1,583 个模块开发环境额外约 2.8s、mui/material约 2,225 个模块约 4.2s冷启动的运行时成本为 200–800ms直接深路径导入如lucide-react/dist/esm/icons/check只加载用到的 3 个模块约 2KB 对比约 1MBtree-shaking 为什么救不了你当库被标记为 external不打包时bundler 根本无法优化它而若为了 tree-shaking 把整个库纳入打包构建又要分析全部模块图构建时间显著变长Next.js 13.5 提供了折中方案experimental.optimizePackageImports配置让开发者保留import { Check, X, Menu } from lucide-react的 ergonomics构建期自动改写为深路径导入。文档列出了常见受影响的库清单lucide-react、mui/material、tabler/icons-react、react-icons、headlessui/react、radix-ui/react-*、lodash、ramda、date-fns、rxjs、react-use。规则 2.2条件加载模块展示了另一个维度仅在功能被激活时才import()大模块如动画帧数据并用typeof window ! undefined守卫防止该模块被打进 SSR bundle同时优化服务端包体积与构建速度。规则 2.3 则指出分析、日志、错误追踪等第三方库应在 hydration 之后再加载不阻塞初始 bundle。ag-kit 自身的实践佐证仓库内的 web/package.json 声明了lucide-react依赖^0.562.0且 search-dialog.tsx、code-block.tsx 等多个组件都从lucide-react主入口导入图标——按本技能规则 2.1 的标准这正是可以被深路径导入或optimizePackageImports优化的一类真实场景。技能文档与宿主仓库的实际代码形成了可互相印证的关系。五、章节 3 与章节 9服务端性能与 Next.js 16 Cache Components3-server-server-side-performance.md 的 7 条规则中第一条Rule 3.1把安全当作品能的一部分带use server的 Server Action 与 API 路由一样是公开端点可以被直接调用因此认证与授权必须写在 Action 内部而不能只依赖 middleware、布局守卫或页面级检查。文档给出的正确模式是先校验输入如用 zod schema→ 再验证身份 → 再校验权限 → 最后执行变更的固定顺序。9-cache-components.md 是整套规则集中唯一带版本门槛的章节文档开头明确警告不要未经兼容性检查就用于 Next.js 15 及更早版本。它描述了 Next.js 16 从Segment 级缓存到组件级缓存的范式转移包含 4 个小节use cache指令可作用于 Server Component 或普通函数文档强调粒度化应用——只包住真正需要缓存的取数函数或组件cacheLife用预定义 profile 声明缓存的新鲜度/过期度profile 从seconds高频更新到max持久缓存直到失效default为 1 年 stale 时间cacheTag按需失效给缓存数据打标签之后在 Server Action 中二选一——revalidateTag后台 SWR 失效或updateTag立即读写一致更新PPRPartial Prerendering通过next.config.ts中的cacheComponents标志启用且要求把动态的 Cache Components 包进Suspense边界才能生效。这一章节与 ag-kit 的 web 项目高度契合web/package.json 中next版本为^16.2.11正处于该章节标注的 Next.js 16 时代因此章节 9 的模式在仓库上下文中是可参考的当然web 项目当前是否启用了cacheComponents需要以 next.config.ts 的实际配置为准。六、自动化验证内置性能审计脚本该技能不只是纸上规则还附带了可执行的审计工具 scripts/react_performance_checker.pySKILL.md 中给出的调用方式为python scripts/react_performance_checker.py project_path从源码实现可以看到它的工程细节扫描根发现_discover_scan_roots优先在path和path/web下寻找同时声明了next或react依赖的package.json再以src/若存在作为扫描根——这恰好适配 ag-kit 这类根目录是 Agent 工具链、web 子目录才是 Next.js 应用的 monorepo 形态目录过滤跳过.git、.next、node_modules、.agents等 10 类目录瀑布检测对应章节 1用正则await\s\w.*?\n\s*await\s\w匹配同一文件内连续两个await命中即报告 CRITICAL 级Sequential awaits detected并附上修复建议Use Promise.all() for parallel fetchingbarrel import 检测对应章节 2只把显式的from /...index/from ../...index视为 barrel 嫌疑代码注释特意说明——TypeScript 中无扩展名的相对导入如from ./foo是常态不能作为 barrel 证据避免误报。这说明该脚本是规则 → 可执行检查的闭环Agent 评审性能问题时可以先跑脚本拿到机器可判定的疑点清单再依据分册规则做人工判断。七、生产上线前的性能评审清单SKILL.md 末尾给出一份分优先级的上线检查清单可直接作为代码评审的 checklist 使用Critical必须修复不存在串行取数瀑布已消除主包体积 200KB应用代码中无 barrel import大组件使用动态导入可并行处已并行取数High Priority该用 Server Components 的地方已使用API 路由无 N1 查询取数场景有 Suspense 边界可用静态生成的已静态生成Medium Priority昂贵计算已 memo 化超过 100 项的列表已虚拟化图片使用next/image无不必要的重渲染Low Priority打磨热点循环已优化RegExp 已提升到作用域外循环内属性访问已缓存配套的反模式列表同样值得贴在团队规约里不要对独立操作使用串行await不要为用一个函数而导入整个库不要在应用代码中用 barrel 导出不要跳过对大组件的动态导入不要在useEffect里无去重地取数不要在有 Server Components 可用时滥用 client components。正面清单则包括Promise.all()并行取数、dynamic(() import(./Heavy))动态导入、import { specific } from library/specific直接导入、用 Suspense 改善加载体验、优先使用平台内建优化next/image、next/font。八、最佳实践总结性能思维模型SKILL.md 收尾部分提炼了五条黄金法则先测量——用 React DevTools Profiler、Chrome DevTools 定位不靠猜最大收益优先——瀑布 → 包体积 → 服务端 → 微观优化不过度优化——聚焦真实瓶颈善用平台特性——Next.js 内建了大量优化站在用户角度——真实网络与设备条件才是标准。文档最后给出的性能心智模型把规则浓缩成几行直觉值得记住每个串行的await 一个潜在瀑布每个import 一个潜在的包体积膨胀点每次不必要的重渲染 浪费的计算Server Components 更少的需要下发的 JavaScriptMeasure, dont guess测量别猜。九、如何在 ag-kit 生态中组合使用从 SKILL.md 的Related Skills表可以看出这个技能被设计为更大能力网络中的一环API 设计对应api-patterns、数据库对应database-design、测试对应testing-patterns、TypeScript 对应typescript-expert、部署对应deployment-procedures——这些技能目录在 .agents/skills/ 下均真实存在。结合本仓库的实际情况一个可落地的使用流程是确认目标项目版本web/package.json 显示 Next.js 16 React 19因此章节 9 的 Cache Components 规则在适用范围之内遇到性能问题时先按快速决策树定位到具体章节文件1–9 分册之一精读对应规则运行python scripts/react_performance_checker.py web获取瀑布与 barrel import 的机器扫描结果按Critical → High → Medium → Low的顺序修复最后对照评审清单逐项打勾。这套技能的价值不在于单条规则本身——Promise.all、next/image、React.memo都是熟悉的概念——而在于它把 58 条零散经验按影响度分级 症状决策树 可执行验证脚本组织成了 Agent 与人类工程师都能快速检索、按需加载、闭环验证的体系。对于正在维护 Next.js 16 项目的团队这种分册索引 选择性阅读的技能组织方式本身也值得借鉴。【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考