企业官网建设流程全解析

AG Kit Next.js 性能专家规则详解：服务端性能 7 条规则（Server-Side Performance）

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit

本篇基于 ag-kit 仓库中的 Next.js/React 性能专家技能文档3-server-server-side-performance.md展开，完整解读其中 7 条服务端性能规则（Rule 3.1–3.7）：Server Action 鉴权、RSC 边界序列化瘦身、并行数据获取、跨请求 LRU 缓存、React.cache()请求内去重与after()非阻塞操作。读完你可以掌握一套可直接落地到 Next.js 16 / React 19 项目的服务端性能与安全优化方案，并能理解 ag-kit 自身站点代码是如何体现这些原则的。

一、规则集定位：ag-kit 性能专家体系中的 HIGH 级章节

ag-kit 是一个面向 AI Agent 的工具箱仓库，其.agents/skills/nextjs-react-expert/目录下内置了一套来自 Vercel Engineering 的 58 条 React/Next.js 性能优化规则，按影响级别分为 9 个章节，组织入口见 SKILL.md。

本文聚焦的第 3 章 Server-Side Performance 在该体系中的定位是：

SKILL.md 的 Impact Priority Guide 将优化顺序定义为：先做 CRITICAL（消除瀑布、瘦身 bundle），再做 HIGH（服务端性能），最后做 MEDIUM/LOW。也就是说，当页面级瀑布和 bundle 问题已基本解决后，服务端就是下一个收益来源。

与当前仓库的契合度：ag-kit 自带的文档站点web/使用的技术栈与该技能声明的“Next.js 16 / React 19 era”完全一致——web/package.json 中声明了"next": "^16.2.11"与"react": "19.2.3"。因此本文的 7 条规则可以直接对 ag-kit 自身站点代码做对照分析，而非纸面理论。

二、Rule 3.1：像对待 API 路由一样鉴权 Server Action（Impact: CRITICAL）

Tags:server, server-actions, authentication, security, authorization

这是 7 条规则中唯一标记为 CRITICAL 的一条，属于安全与性能交叉点：

Server Actions（带"use server"的函数）会作为公共端点暴露，与 API 路由无异。必须把认证与授权校验放在每个 Server Action 内部——不要只依赖 middleware、layout 守卫或页面级检查，因为 Server Action 可以被直接调用。

Next.js 官方文档的原文表述也被规则收录：“Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation.”（以对待公共 API 端点的同等安全标准对待 Server Action，并验证用户是否被允许执行该变更。）

反例：无鉴权

'use server' export async function deleteUser(userId: string) { // Anyone can call this! No auth check await db.user.delete({ where: { id: userId } }) return { success: true } }

任何拿到端点的人都可触发deleteUser，直接造成越权数据删除。

正例：在 Action 内部完成认证 + 授权

'use server' import { verifySession } from '@/lib/auth' import { unauthorized } from '@/lib/errors' export async function deleteUser(userId: string) { // Always check auth inside the action const session = await verifySession() if (!session) { throw unauthorized('Must be logged in') } // Check authorization too if (session.user.role !== 'admin' && session.user.id !== userId) { throw unauthorized('Cannot delete other users') } await db.user.delete({ where: { id: userId } }) return { success: true } }

注意这里的两层校验：认证（verifySession确认“你是谁”）与授权（角色 + 资源属主检查确认“你能不能”）。

进阶：先做输入校验

'use server' import { verifySession } from '@/lib/auth' import { z } from 'zod' const updateProfileSchema = z.object({ userId: z.string().uuid(), name: z.string().min(1).max(100), email: z.string().email() }) export async function updateProfile(data: unknown) { // Validate input first const validated = updateProfileSchema.parse(data) // Then authenticate const session = await verifySession() if (!session) { throw new Error('Unauthorized') } // Then authorize if (session.user.id !== validated.userId) { throw new Error('Can only update own profile') } // Finally perform the mutation await db.user.update({ where: { id: validated.userId }, data: { name: validated.name, email: validated.email } }) return { success: true } }

推荐顺序是Validate → Authenticate → Authorize → Mutate：先用 Zod 拒绝畸形输入，再做会话与权限检查，最后才执行数据库变更，避免无效输入消耗数据库连接与鉴权开销。

三、Rule 3.2：避免 RSC Props 的重复序列化（Impact: LOW）

Tags:server, rsc, serialization, props, client-components

RSC 到客户端的序列化按对象引用去重，而不是按值去重：同一引用只序列化一次，新引用则再序列化一次。因此不要在服务端做.toSorted()、.filter()、.map()这类变换后再传给客户端组件——变换会产生新引用，导致同一份数据被重复发送。

反例：同一数组传两份

// RSC: sends 6 strings (2 arrays × 3 items) <ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />

正例：只传一份，客户端自行变换

// RSC: send once <ClientList usernames={usernames} /> // Client: transform there 'use client' const sorted = useMemo(() => [...usernames].sort(), [usernames])

嵌套去重行为：影响程度因数据类型而异

去重是递归生效的，但收益大小取决于数据结构：

• string[]、number[]、boolean[]：HIGH impact——数组容器 + 全部原始值都会被完整复制；
• object[]：LOW impact——只有数组结构被复制，嵌套对象本身仍按引用去重。

// string[] - duplicates everything usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings // object[] - duplicates array structure only users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)

会破坏去重的操作（创建新引用）

• 数组：.toSorted()、.filter()、.map()、.slice()、[...arr]
• 对象：{...obj}、Object.assign()、structuredClone()、JSON.parse(JSON.stringify())

// ❌ Bad <C users={users} active={users.filter(u => u.active)} /> <C product={product} productName={product.name} /> // ✅ Good <C users={users} /> <C product={product} /> // Do filtering/destructuring in client

例外：当变换代价很高、或客户端根本不需要原始数据时，传派生数据是合理的——此时避免重复序列化的目标要让位于服务端计算成本。

四、Rule 3.3：跨请求 LRU 缓存（Impact: HIGH）

Tags:server, cache, lru, cross-request

React.cache()只在单个请求内生效。而当用户在短时间内顺序点击按钮 A 再点击按钮 B（两个连续请求需要同一份数据）时，需要一个跨请求的 LRU 缓存：

import { LRUCache } from 'lru-cache' const cache = new LRUCache<string, any>({ max: 1000, ttl: 5 * 60 * 1000 // 5 minutes }) export async function getUser(id: string) { const cached = cache.get(id) if (cached) return cached const user = await db.user.findUnique({ where: { id } }) cache.set(id, user) return user } // Request 1: DB query, result cached // Request 2: cache hit, no DB query

适用场景：用户连续操作在短时间内多次命中需要相同数据的多个端点。

部署形态决定缓存策略：

• 在 Fluid Compute 这类允许多个并发请求共享同一函数实例的环境中，LRU 缓存尤为有效——缓存跨请求驻留，无需 Redis 等外部存储；
• 在传统 serverless 中，每次调用相互隔离，跨进程共享需考虑 Redis。

选型上可参考node-lru-cache库；从规则给出的参数看，容量上限（max）与过期时间（ttl）是防止内存膨胀的两大关键配置。

五、Rule 3.4：最小化 RSC 边界处的序列化（Impact: HIGH）

Tags:server, rsc, serialization, props

React Server/Client 边界会把对象的所有属性序列化为字符串，并嵌入 HTML 响应及后续 RSC 请求中。这份序列化数据直接计入页面体积与加载时间，尺寸很重要：只传客户端真正用到的字段。

反例：50 个字段全部过界

async function Page() { const user = await fetchUser() // 50 fields return <Profile user={user} /> } 'use client' function Profile({ user }: { user: User }) { return <div>{user.name}</div> // uses 1 field }

客户端只用了name一个字段，却为 50 个字段付了序列化成本。

正例：只传 1 个字段

async function Page() { const user = await fetchUser() return <Profile name={user.name} /> } 'use client' function Profile({ name }: { name: string }) { return <div>{name}</div> }

ag-kit 站点的真实应用

这条规则在 ag-kit 的文档站点中有一个有意思的“反向”实践。以 brainstorm 示例页 为例，页面在服务端把四种语言的 MDX 内容各渲染成一个 RSC 元素，作为 props 传给客户端组件：

export default function Page() { return <LocalizedDoc en={<En />} vi={<Vi />} zh={<Zh />} ja={<Ja />} />; }

而 LocalizedDoc 是"use client"组件，源码注释明确写道：所有分支都在服务端渲染完成，客户端组件“只负责选择显示哪一个”，因此切换语言无需刷新页面即可瞬时生效。

从源码结构看，这是一种有意识的权衡：把“四选一”的选择逻辑下放到客户端换取即时切换体验，同时利用 RSC 边界去重（同一 locale 的内容只作为一份 RSC 元素传递），而不是把四份原始 MDX 文本全部序列化到浏览器。这恰好印证了 Rule 3.4 与 3.2 的核心思想——RSC 边界两侧各干各擅长的事，边界上的数据尽量少、尽量按引用共享。

六、Rule 3.5：组件组合实现并行数据获取（Impact: CRITICAL）

Tags:server, rsc, parallel-fetching, composition

React Server Components 在组件树内部是顺序执行的：Page中先await fetchHeader()完成，才会执行子组件Sidebar的取数逻辑。要用组件组合重构，让各部分的数据获取并行发生。

反例：Sidebar 被迫等待 Page 的 fetch

export default async function Page() { const header = await fetchHeader() return ( <div> <div>{header}</div> <Sidebar /> </div> ) } async function Sidebar() { const items = await fetchSidebarItems() return <nav>{items.map(renderItem)}</nav> }

总耗时 ≈fetchHeader()耗时 +fetchSidebarItems()耗时（串行瀑布）。

正例：两个组件同时取数

async function Header() { const data = await fetchHeader() return <div>{data}</div> } async function Sidebar() { const items = await fetchSidebarItems() return <nav>{items.map(renderItem)}</nav> } export default function Page() { return ( <div> <Header /> <Sidebar /> </div> ) }

取数下沉到各自的异步 Server Component 后，Header与Sidebar的请求同时发起，总耗时 ≈ 两者中的最大值。

变体：children prop 组合

async function Header() { const data = await fetchHeader() return <div>{data}</div> } async function Sidebar() { const items = await fetchSidebarItems() return <nav>{items.map(renderItem)}</nav> } function Layout({ children }: { children: ReactNode }) { return ( <div> <Header /> {children} </div> ) } export default function Page() { return ( <Layout> <Sidebar /> </Layout> ) }

Layout本身不 await 任何数据，Header与children（即Sidebar）独立并行。这种“壳组件不取数、取数组件各自独立”的结构，也是配合 Suspense 做流式渲染的基础。

七、Rule 3.6：用 React.cache() 做单请求内去重（Impact: MEDIUM）

Tags:server, cache, react-cache, deduplication

React.cache()用于服务端请求内去重，认证检查和数据库查询受益最大：

import { cache } from 'react' export const getCurrentUser = cache(async () => { const session = await auth() if (!session?.user?.id) return null return await db.user.findUnique({ where: { id: session.user.id } }) })

在同一个请求内，组件树中多处调用getCurrentUser()只会执行一次查询，其余调用直接拿到缓存结果。

陷阱：内联对象参数导致缓存永远未命中

React.cache()用浅比较（Object.is）判定缓存命中。每次调用都构造新对象，引用必然不同，缓存必然失效。

反例（每次调用都是 cache miss）：

const getUser = cache(async (params: { uid: number }) => { return await db.user.findUnique({ where: { id: params.uid } }) }) // Each call creates new object, never hits cache getUser({ uid: 1 }) getUser({ uid: 1 }) // Cache miss, runs query again

正例（原始值参数可命中）：

const getUser = cache(async (uid: number) => { return await db.user.findUnique({ where: { id: uid } }) }) // Primitive args use value equality getUser(1) getUser(1) // Cache hit, returns cached result

如果必须传对象，请传同一个引用：

const params = { uid: 1 } getUser(params) // Query runs getUser(params) // Cache hit (same reference)

Next.js 特有的注意点

在 Next.js 中，fetchAPI 被自动扩展了请求内 memoization：相同 URL 与 options 的请求在单请求内自动去重，因此 fetch 调用不需要再套React.cache()。但以下非 fetch 的异步工作仍然必须手动去重：

• 数据库查询（Prisma、Drizzle 等）
• 重量级计算
• 认证检查
• 文件系统操作
• 任何非 fetch 的异步任务

八、Rule 3.7：用 after() 处理非阻塞操作（Impact: MEDIUM）

Tags:server, async, logging, analytics, side-effects

Next.js 的after()用于调度“响应发出之后才需要执行”的工作，防止日志、分析等副作用阻塞响应。

反例：日志阻塞响应

import { logUserAction } from '@/app/utils' export async function POST(request: Request) { // Perform mutation await updateDatabase(request) // Logging blocks the response const userAgent = request.headers.get('user-agent') || 'unknown' await logUserAction({ userAgent }) return new Response(JSON.stringify({ status: 'success' }), { status: 200, headers: { 'Content-Type': 'application/json' } }) }

正例：响应先返回，日志后台执行

import { after } from 'next/server' import { headers, cookies } from 'next/headers' import { logUserAction } from '@/app/utils' export async function POST(request: Request) { // Perform mutation await updateDatabase(request) // Log after response is sent after(async () => { const userAgent = (await headers()).get('user-agent') || 'unknown' const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous' logUserAction({ sessionCookie, userAgent }) }) return new Response(JSON.stringify({ status: 'success' }), { status: 200, headers: { 'Content-Type': 'application/json' } }) }

响应立即返回，日志在后台完成。典型适用场景包括：

• 分析埋点（Analytics tracking）
• 审计日志（Audit logging）
• 发送通知
• 缓存失效（Cache invalidation）
• 清理任务

两个重要事实：after()在响应失败或重定向时仍会执行；它可用于 Server Actions、Route Handlers 和 Server Components。注意正例中headers()/cookies()是await调用的——这是 Next.js 16（该仓库web/站点所用的版本）的异步 API 形态。

九、在 ag-kit 中落地：规则导航与自动化审计

按症状定位规则

SKILL.md 提供了一个决策树：遇到 Slow Server-Side Rendering，进入 Section 3，重点检查 Parallel data fetching 与 streaming；做综合性能评审时，按 CRITICAL（水瀑布、bundle）→ HIGH（服务端）→ MEDIUM（客户端取数、重渲染、渲染）→ LOW（JS 微优化）的顺序推进。上文的 7 条规则正好覆盖该章节全部检查面：安全（3.1）、序列化（3.2、3.4）、缓存（3.3、3.6）、并行化（3.5）、非阻塞副作用（3.7）。

自动化审计脚本

技能目录附带了 react_performance_checker.py，可对任意 Next.js 项目执行静态扫描。其工作方式（从源码可见）：

• _discover_scan_roots()会优先寻找包含next/react依赖的package.json，自动适配类似 ag-kit 这种“根目录 +web/子项目”的多包结构；
• 依次执行check_waterfalls（顺序 await 检测）、check_barrel_imports、check_dynamic_imports、check_useEffect_fetching、check_missing_memoization、check_image_optimization等检查项，每项发现都会标注对应规则章节（如2-bundle-bundle-size-optimization.md）便于回溯；
• 通过--fail-on-warnings参数可把建议性告警升级为阻断项，适合接入 CI。

运行方式：

python .agents/skills/nextjs-react-expert/scripts/react_performance_checker.py <project_path>

需要说明的是，该脚本以正则静态扫描为主，用于快速发现模式级问题；像 Rule 3.1（Server Action 是否做了内部鉴权）、Rule 3.2（props 是否重复序列化）这类语义级规则，仍应以本文的 7 条规则作为人工评审清单。

十、小结

配合 web/package.json 所示的 Next.js 16.2.x + React 19.2.x 环境，这 7 条规则构成了一份从安全到吞吐、从单请求到跨请求的完整服务端优化清单：先保证 Server Action 安全（3.1），再通过组件组合消灭服务端瀑布（3.5）、用两级缓存削减重复查询（3.6 请求内 + 3.3 跨请求），最后通过序列化瘦身（3.2、3.4）和非阻塞副作用（3.7）把响应时间与页面体积压到最低。

【免费下载链接】ag-kit项目地址: https://gitcode.com/GitHub_Trending/an/ag-kit