react-server-components-framework

React 服务端组件框架

概述

React 服务端组件（RSC）支持以服务端优先的方式渲染，同时提供客户端交互功能。本技能涵盖 Next.js 16.2 LTS App Router 模式、服务端组件、服务端操作和流式传输。

Next.js 16.2.6 / React 19.2.6（安全版本，2026 年 5 月）——Turbopack 是默认打包器（无需 --turbo 标志），服务端快速刷新默认启用，新的 cacheComponents 配置标志取代了旧版 experimental_ppr 备用方案。为便于 AI Agent 调试，Next.js 提供 Next DevTools MCP——将 npx -y next-devtools-mcp@latest 接入 .mcp.json（它通过开发服务器的 /_next/mcp 端点连接），即可在会话期间检查渲染树和缓存边界。

适用场景：

• 使用 App Router 构建 Next.js 16+ 应用
• 设计组件边界（服务端组件与客户端组件）
• 实现带缓存和重新验证的数据获取
• 使用服务端操作创建变更
• 使用流式传输和 Suspense 优化性能

---

快速参考

服务端组件与客户端组件对比

特性	服务端组件	客户端组件
指令	无（默认）	'use client'
Async/await	是	否
Hooks	否	是
浏览器 API	否	是
数据库访问	是	否
客户端 JS 包	无	发送至客户端

关键规则：服务端组件可以渲染客户端组件，但客户端组件不能直接导入服务端组件（改用 children 属性）。

数据获取快速参考

Next.js 16 缓存组件（推荐）：

import { cacheLife, cacheTag } from 'next/cache'

// Default — shared across all users (public CDN-cached)
async function CachedProducts() {
  'use cache'
  cacheLife('hours')
  cacheTag('products')
  return await db.product.findMany()
}

// Remote variant (16.2+) — always served from the edge/CDN, never rendered
// inline on the origin. Best for static product listings, marketing content.
async function MarketingHero() {
  'use cache: remote'
  cacheLife('days')
  return <Hero />
}

// Private variant (16.2+) — cached per-user session. Never shared across
// users. Use for personalized dashboards with expensive computation.
async function UserDashboard({ userId }: { userId: string }) {
  'use cache: private'
  cacheLife('minutes')
  cacheTag(`user:${userId}`)
  return await loadDashboard(userId)
}

// Invalidate cache — v16 requires a cacheLife profile as the 2nd arg
import { revalidateTag } from 'next/cache'
revalidateTag('products', 'max') // or updateTag('products') for read-your-writes

通过 next.config.ts 启用：

import type { NextConfig } from 'next'
const config: NextConfig = {
  cacheComponents: true,  // 16.2+ — replaces experimental_ppr flag
}
export default config

旧版 Fetch 选项（Next.js 15）：

// Static (cached indefinitely)
await fetch(url, { cache: 'force-cache' })

// Revalidate every 60 seconds
await fetch(url, { next: { revalidate: 60 } })

// Always fresh
await fetch(url, { cache: 'no-store' })

// Tag-based revalidation
await fetch(url, { next: { tags: ['posts'] } })

服务端操作快速参考

'use server'

export async function createPost(formData: FormData) {
  const title = formData.get('title') as string
  const post = await db.post.create({ data: { title } })
  revalidatePath('/posts')
  redirect("/posts/" + post.id)
}

异步 Params/SearchParams（Next.js 16）

路由参数和搜索参数现在都是必须等待解析的 Promise：

// app/posts/[slug]/page.tsx
export default async function PostPage({
  params,
  searchParams,
}: {
  params: Promise<{ slug: string }>
  searchParams: Promise<{ page?: string }>
}) {
  const { slug } = await params
  const { page } = await searchParams
  return <Post slug={slug} page={page} />
}

**注意：**这也适用于 layout.tsx、generateMetadata() 和路由处理程序。完整迁移指南：一方提供的 next-upgrade / vercel:next-upgrade 技能。项目内部经验：Read("references/ork-delta.md")。

开发服务器（Next.js 16.2 LTS）

• 默认使用 Turbopack——next dev 和 next build 无需任何标志即可运行 Turbopack。仅在必须使用时（旧版插件）才传入 --webpack。
• 服务端快速刷新——保存后，服务端组件会热重载，且不会丢失客户端状态。无需额外配置；在 16.2 中默认启用。
• Next DevTools MCP——在 .mcp.json 中注册 npx -y next-devtools-mcp@latest；它通过 /_next/mcp 端点连接正在运行的开发服务器，并向 MCP 客户端提供 RSC 负载和缓存边界信息。专为需要在会话期间检查渲染树而无需截屏的 AI Agent 设计。（不存在 next-browser 二进制文件。）

---

参考资料

按需使用 Read("references/<file>") 加载：

文件	内容
ork-delta.md	项目规范与经验：PR #2143 中对虚构 API 的修正、React 19 项目约定（2026-07-31 梳理）
tanstack-router-patterns.md	不使用 Next.js 的 React 19 功能、基于路由的数据获取、客户端渲染应用模式
capability-details.md	全部 12 项 RSC 能力的关键词和问题映射元数据

---

上游内容覆盖范围（无需重述）

这些主题的供应商教程位于第一方技能和文档中。本技能仅保留基础要求、经验教训和团队决策（references/ork-delta.md）。

主题	第一方来源
Server Components 基础知识（异步组件、数据获取、路由段配置、generateStaticParams、错误处理）	next-best-practices / vercel:nextjs 技能；nextjs.org/docs
Client Components、'use client'、水合、仅客户端渲染	next-best-practices / vercel:nextjs 技能
Server/Client 边界与组合模式、可序列化属性	next-best-practices / vercel:nextjs 技能；vercel-composition-patterns
数据获取与缓存（fetch 缓存选项、revalidate、标签）	next-best-practices / vercel:nextjs 技能
流式 SSR、Suspense 边界、loading.tsx、骨架屏状态	vercel:nextjs 技能（流式传输）
Server Actions、渐进增强、useActionState 表单、Zod 验证	vercel:nextjs 技能（Server Actions）
高级路由（并行、拦截、路由组、动态路由和全捕获路由）	vercel:nextjs 技能（路由）
从 Pages Router 迁移到 App Router	next-upgrade / vercel:next-upgrade 技能
Next.js 16 升级、破坏性变更、codemod	next-upgrade / vercel:next-upgrade 技能
Cache Components：use cache、cacheLife、cacheTag、updateTag、PPR	next-cache-components / vercel:next-cache-components 技能
React 19 核心 API（useActionState、useFormStatus、useOptimistic、use()、ref 作为属性）	context7：/vercel/next.js + react.dev（query-docs）
RSC 实现和部署检查清单	next-best-practices 技能

---

最佳实践摘要

组件边界

• 将 Client Components 保留在组件树的边缘（叶节点）
• 默认使用 Server Components
• 将最少量的交互部分提取为 Client Components
• 将 Server Components 作为 children 传递给 Client Components

数据获取

• 在 Server Components 中靠近数据使用位置的地方获取数据
• 对相互独立的数据使用并行获取（Promise.all）
• 设置合适的缓存和 revalidate 选项
• 对静态路由使用 generateStaticParams

性能

• 使用 Suspense 边界实现流式传输
• 使用 loading.tsx 实现即时加载状态
• 启用 PPR，以混合静态和动态内容
• 使用路由段配置控制渲染模式

---

模板

• scripts/server-component-template.tsx - 带数据获取功能的基础异步 Server Component
• scripts/client-component-template.tsx - 使用钩子的交互式 Client Component
• scripts/server-action-template.ts - 带验证和重新验证的 Server Action
• scripts/create-server-component.md - 命令式脚手架；作为由 tests/skills/scripts/ 测试的脚本调用约定保留

---

故障排除

错误	修复方法
"You're importing a component that needs useState"	添加 'use client' 指令
"async/await is not valid in non-async Server Components"	在函数声明中添加 async
"Cannot use Server Component inside Client Component"	将 Server Component 作为 children 属性传递
"Hydration mismatch"	对 Date.now()、Math.random()、浏览器 API 使用 'use client'
"params is not defined" 或 params 返回 Promise	在 params 前添加 await（Next.js 16 破坏性变更）
"experimental_ppr is not a valid export"	改用带 "use cache" 指令的 Cache Components
"cookies/headers is not a function"	在 cookies() 或 headers() 前添加 await（Next.js 16）

---

资源

• Next.js 16 文档
• React 19.2 博客文章
• React Server Components RFC
• App Router 迁移指南

---

相关技能

掌握 React Server Components 后：

1. 流式 API 模式 - 实时数据模式
2. 类型安全与验证 - tRPC 集成
3. 边缘计算模式 - 全球部署
4. 性能优化 - Core Web Vitals

---

功能详情

每项 RSC 功能（react-19-patterns、use-hook-suspense、optimistic-updates-async、rsc-patterns、server-actions、data-fetching、streaming-ssr、caching、cache-components、tanstack-router-patterns、async-params、nextjs-16-upgrade）的关键词和问题映射元数据。

加载完整功能详情：Read("references/capability-details.md")