React Server Components 实战：下一代 SSR 开发指南

fruge365

发布于 2025-12-15 14:04:54

2310

React Server Components 实战：下一代 SSR 开发指南

核心理念

组件在服务器渲染并直接输出可序列化的 UI 树片段，客户端仅为交互部分注水
数据靠近服务器与数据库，避免瀑布式请求与冗余水合
按需把交互组件标记为客户端组件，减小包体与提升首屏

技术栈与初始化

pnpm create next-app@latest rsc-app --ts --eslint --tailwind --app
cd rsc-app && pnpm dev

目录（App Router）：

rsc-app/
  app/
    layout.tsx
    page.tsx
    components/
      RepoList.tsx
      InteractiveCounter.tsx
    api/
      items/route.ts
    actions.ts
  lib/
    db.ts
  next.config.js

Server vs Client 组件

Server Component：默认；可访问数据库/后端，仅输出可序列化内容
Client Component：文件顶部加 use client；可使用状态与事件，不能直接访问服务器资源

Server 组件示例

app/components/RepoList.tsx

import { cache } from 'react'

const fetchRepos = cache(async () => {
  const res = await fetch('https://api.github.com/orgs/vercel/repos', { next: { revalidate: 60 } })
  return res.json() as Promise<Array<{ id:number; name:string }>>
})

export default async function RepoList() {
  const repos = await fetchRepos()
  return (
    <ul>{repos.slice(0, 10).map(r => <li key={r.id}>{r.name}</li>)}</ul>
  )
}

Client 组件示例

app/components/InteractiveCounter.tsx

'use client'
import { useState } from 'react'
export default function InteractiveCounter() {
  const [n, setN] = useState(0)
  return <button onClick={() => setN(n + 1)}>Count: {n}</button>
}

页面与布局

app/page.tsx

import RepoList from './components/RepoList'
import InteractiveCounter from './components/InteractiveCounter'

export default function Page() {
  return (
    <main>
      <h1>RSC Demo</h1>
      <RepoList />
      <InteractiveCounter />
    </main>
  )
}

app/layout.tsx

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="zh">
      <body>{children}</body>
    </html>
  )
}

Streaming 与 Suspense

app/page.tsx

import { Suspense } from 'react'
import RepoList from './components/RepoList'

export default function Page() {
  return (
    <main>
      <h1>Streaming</h1>
      <Suspense fallback={<p>Loading repos...</p>}>
        {/* Server 组件可流式传输 */}
        {/* @ts-expect-error Async Server Component */}
        <RepoList />
      </Suspense>
    </main>
  )
}

数据获取与缓存策略

fetch：next: { revalidate } 控制增量静态化；cache: 'no-store' 关闭缓存
cache(asyncFn)：稳定函数层复用结果，避免重复 IO
revalidateTag/revalidatePath：配合标签或路径精细失效

app/actions.ts

'use server'
import { revalidateTag } from 'next/cache'
export async function createItem(formData: FormData) {
  // 写入数据库...
  revalidateTag('items')
}

Server 组件读取：

const res = await fetch('https://api.example.com/items', { next: { tags: ['items'], revalidate: 120 } })

Server Actions（无 API 层的直接提交）

app/actions.ts

'use server'
export async function addTodo(prev: any, formData: FormData) {
  const title = String(formData.get('title') ?? '')
  // 写库...
  return { ok: true, title }
}

app/page.tsx

import { addTodo } from './actions'
export default function Page() {
  return (
    <form action={addTodo}>
      <input name="title" />
      <button type="submit">Add</button>
    </form>
  )
}

Route Handlers（API 路由）

app/api/items/route.ts

import { NextResponse } from 'next/server'
export async function GET() {
  return NextResponse.json([{ id: 1, name: 'A' }], { status: 200 })
}
export async function POST(req: Request) {
  const body = await req.json()
  return NextResponse.json({ ok: true, body }, { status: 201 })
}

Edge Runtime（可选）

app/api/hello/route.ts

export const runtime = 'edge'
export async function GET() { return new Response('Hi from edge') }

SEO 与 Metadata

app/page.tsx

export const metadata = { title: 'RSC 指南', description: '下一代 SSR 与流式渲染' }

常见坑与修复

第三方库需要 DOM 时必须在客户端组件使用
Server 组件不可使用状态/副作用；事件处理放入客户端组件
仅传递可序列化 props；避免函数与类实例穿越边界
注意缓存层级与失效策略，避免陈旧数据

测试与调试建议

组件分层测试：Server 组件快照 + 客户端交互用 @testing-library/react
端到端流式校验：使用 Playwright 验证 Suspense 与流式内容
观测：结合日志与 APM，对边缘与 Node 运行时区分指标

部署与性能

Vercel 一键部署支持流式 SSR；或 Node 自托管
按路由分层设置 revalidate，减少后端压力
大列表分页与骨架屏结合，兼顾渲染与交互

迁移提示

Page Router → App Router：拆分 Server/Client 组件，数据上移到服务器
移出全局客户端状态，保留必要交互在客户端

总结

RSC 通过服务器端组件与流式输出来提升渲染性能与开发体验
与 Server Actions、Route Handlers 配合，形成端到端的数据与渲染闭环
按需选择客户端组件边界，减少包体与水合成本

数据库直连与增删改查

lib/db.ts

import { PrismaClient } from '@prisma/client'
export const prisma = new PrismaClient()

app/items/page.tsx

import { prisma } from '@/lib/db'
export default async function ItemsPage() {
  const items = await prisma.item.findMany({ take: 20 })
  return <ul>{items.map(i => <li key={i.id}>{i.title}</li>)}</ul>
}

app/items/actions.ts

'use server'
import { prisma } from '@/lib/db'
import { revalidatePath } from 'next/cache'
export async function addItem(prev: any, formData: FormData) {
  const title = String(formData.get('title') || '')
  await prisma.item.create({ data: { title } })
  revalidatePath('/items')
  return { ok: true }
}

动态路由与静态生成

app/items/[id]/page.tsx

import { prisma } from '@/lib/db'
export async function generateStaticParams() {
  const ids = await prisma.item.findMany({ select: { id: true }, take: 10 })
  return ids.map(i => ({ id: String(i.id) }))
}
export default async function ItemDetail({ params }: { params: { id: string } }) {
  const item = await prisma.item.findUnique({ where: { id: Number(params.id) } })
  if (!item) return null
  return <div>{item.title}</div>
}

并行与拦截路由

并行路由与拦截路由适用于复杂布局与模态场景。示例结构：

app/
  @feed/page.tsx
  @sidebar/page.tsx
  intercept/(.)modal/[id]/page.tsx

乐观更新与表单状态

app/items/client/AddForm.tsx

'use client'
import { useOptimistic, useTransition } from 'react'
import { addItem } from '../actions'
export default function AddForm() {
  const [list, addOptimistic] = useOptimistic<string[], string>((state, v) => [v, ...state])
  const [pending, start] = useTransition()
  return (
    <form action={(fd) => start(async () => { addOptimistic(String(fd.get('title'))); await addItem({}, fd) })}>
      <input name="title" />
      <button disabled={pending} type="submit">Add</button>
      <ul>{list.map((t, i) => <li key={i}>{t}</li>)}</ul>
    </form>
  )
}

文件上传（Server Actions）

app/upload/actions.ts

'use server'
export async function upload(prev: any, formData: FormData) {
  const file = formData.get('file') as File
  const buf = Buffer.from(await file.arrayBuffer())
  return { size: buf.length }
}

错误与 404 边界

app/error.tsx

'use client'
export default function Error({ error }: { error: Error }) { return <div>Error</div> }

app/not-found.tsx

export default function NotFound() { return <div>Not Found</div> }

缓存失效矩阵

静态增量：next: { revalidate: N }
标签失效：next: { tags: ['t'] } 配合 revalidateTag('t')
路径失效：revalidatePath('/p')
禁用缓存：cache: 'no-store'

性能与观测

Streaming 与 Suspense 缩短 TTFB 与提升可感知速度
边缘运行适用于低延迟与全球分发
日志与指标区分 Node 与 Edge，关注错误率与渲染耗时

安全建议

仅在服务器组件访问密钥与数据库
传递可序列化数据，避免函数与实例泄露
对输入进行校验与清理，避免注入

架构对比与边界清单

CSR：数据拉取在客户端，水合成本高；适合强交互页面
传统 SSR：整页水合，数据靠 API 层；适合内容页与 SEO
RSC：数据与渲染上移到服务器，仅交互组件注水；适合大多数内容/混合场景
边界检查：
- 仅在客户端组件使用 useState/useEffect
- Server 组件禁止使用浏览器 API 与事件处理
- Props 必须可序列化（JSON 可表达）
- 缓存与失效路径明确（标签/路径/时间）

迁移步骤（增量采纳）

迁入 App Router，保留原 CSR/SSR 页于 pages/，新页在 app/
拆分数据读取到 Server 组件（或 Route Handler/Server Action）
将交互模块标记为 use client 并最小化客户端边界
加入 Streaming 与 Suspense，分层渲染慢数据
引入缓存与失效矩阵（时间/标签/路径），消除冗余请求
建立错误边界与 404，完善观测与告警

路由段配置与动态性

app/items/[id]/page.tsx

export const dynamic = 'force-static'     // 或 'force-dynamic'
export const revalidate = 300             // 段级增量静态化
export const fetchCache = 'default-cache' // 控制 fetch 缓存

Middleware（鉴权示例）

middleware.ts

import { NextResponse } from 'next/server'
export function middleware(req: Request) {
  const url = new URL(req.url)
  const token = (req as any).cookies?.get('token')?.value
  if (url.pathname.startsWith('/dashboard') && !token) return NextResponse.redirect(new URL('/', url))
  return NextResponse.next()
}
export const config = { matcher: ['/dashboard/:path*'] }

generateMetadata（动态 SEO）

app/items/[id]/page.tsx

export async function generateMetadata({ params }: { params: { id: string } }) {
  return { title: `Item #${params.id}`, description: 'RSC 动态元数据' }
}

观测与日志（instrumentation）

instrumentation.ts

export async function register() {
  console.log('app start')
}

测试套件与基准

单测：Server 组件快照；Client 组件交互用 @testing-library/react
E2E：Playwright 校验 Suspense 占位与流式插入
性能基准：记录 TTFB、LCP、交互就绪（INP），分路由对比 CSR/SSR/RSC

常见错误与修复

在 Server 组件使用 useState：改为客户端组件或上移为 props
传递函数/类实例作为 props：改为 ID 或纯数据
缓存失效未触发：检查 revalidateTag 与读取端是否声明 tags
第三方库依赖 DOM：在 use client 文件中引用

生产部署清单

环境变量与密钥仅在 Server 端使用
对慢查询与外部 API 设定 timeout 与降级占位
边缘与 Node 环境分开监控，错误率与耗时告警
构建后启用 Bundle 分析，限制客户端包体与重复依赖

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2025-12-02，如有侵权请联系 cloudcommunity@tencent.com 删除

components

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度

React Server Components 实战：下一代 SSR 开发指南

React Server Components 实战：下一代 SSR 开发指南

React Server Components 实战：下一代 SSR 开发指南

核心理念

技术栈与初始化

Server vs Client 组件

Server 组件示例

Client 组件示例

页面与布局

Streaming 与 Suspense

数据获取与缓存策略

Server Actions（无 API 层的直接提交）

Route Handlers（API 路由）

Edge Runtime（可选）

SEO 与 Metadata

常见坑与修复

测试与调试建议

部署与性能

迁移提示

总结

数据库直连与增删改查

动态路由与静态生成

并行与拦截路由

乐观更新与表单状态

文件上传（Server Actions）

错误与 404 边界

缓存失效矩阵

性能与观测

安全建议

架构对比与边界清单

迁移步骤（增量采纳）

路由段配置与动态性

Middleware（鉴权示例）

generateMetadata（动态 SEO）

观测与日志（instrumentation）

测试套件与基准

常见错误与修复

生产部署清单

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐