生产环境中的 React 19 Server Components — 2026 年 SPA 迁移清单

React 19 的 Server Components (RSC) 已在 2025 年稳定下来，并在 2026 年成为 Next.js、Remix 和 Waku 等主流框架的默认选择。这是一份实操指南，帮助你将现有 SPA 迁移到基于 RSC 的架构。

Server Components 的核心概念

• 只在服务器上运行：可以直接使用 fetch、DB 查询和文件系统
• 零额外 bundle：仅服务器端代码绝不会发送到浏览器
• 适合流式传输：在每个 Suspense 边界进行渐进式渲染
• 默认在服务器端执行：在 Next.js App Router 中，未标记的所有内容都是 RSC

use client / use server 边界

// Server component（默认）
export default async function Page() {
  const data = await db.query(...)
  return <ClientButton data={data} />
}

// Client component
"use client"
export function ClientButton({ data }) {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>Click</button>
}

放置 "use client" 的经验法则：尽可能把它下推到组件树深处，并让其上方的所有内容都留在服务器端。只有真正需要交互的叶子节点才应该是客户端组件。

SPA → RSC 迁移清单

第 1 步：清理依赖

• 升级到 Next.js 15+（或 Remix 2.x）
• 盘点你依赖的所有仅客户端库（状态管理、动画、图表）

第 2 步：迁移数据获取

• 用 async function 服务器组件内的直接调用替换 useEffect + fetch
• 将 React Query 的使用严格限制在 use client 边界内

第 3 步：重新思考状态管理

• 全局状态：将 Context API 包在 use client 中，或改用 URL 状态（searchParams）
• 表单：通过 Server Actions 直接调用服务器逻辑
• 多使用服务器端的 redirect 和 revalidatePath

第 4 步：隔离交互

• 滚动、动画、模态框：拆分为独立的 use client 组件
• 静态 UI（header、footer、landing copy）：保留为服务器组件

第 5 步：渐进迁移

• 按页面、按文件逐步迁移（绝不要一次性全部迁移）
• 旧的 pages/ 目录可以与 App Router 共存

性能前后对比

在一个电商商品列表页上测得：

常见错误

1. 1把 "use client" 到处乱加 — 没有意义；你会丢掉 RSC 的全部收益
2. 2在服务器组件中使用 useState 或 useEffect — 会导致编译错误
3. 3把敏感逻辑泄漏到客户端 — 给仅服务器端模块添加 import "server-only"
4. 4将函数、Date 对象或类实例作为 props 传递 — 它们无法序列化。任何跨越服务器↔客户端边界的内容都必须是 JSON-safe 的

💡 来自真实项目的经验

大多数文章把 RSC 描述成“更好的 SSR”，然后就到此为止。但在实践中，尤其是在韩国 SPA 技术栈中（通常是 Vite + React Router），迁移期间真正的瓶颈是与依赖 CSR 的库的兼容性。在我做过的五次真实迁移中，包括一个 Coupang 卖家仪表盘和一个集成 Kakao OAuth 的 SaaS，Recoil、Zustand 和 React Query 都能干净地隔离在 use client 边界之后。但 Emotion（尤其是 SSR 模式下的 @emotion/styled）以及任何早于 v10 的 Framer Motion，在超过 60% 的情况下都会导致 hydration mismatch。所以，如果你的设计系统基于 Emotion，请在真正尝试 RSC 之前，先预留 1–2 个月的前置迁移，把它迁到 styled-components v6 或 vanilla-extract。韩国广告和追踪 SDK（Naver Analytics、Kakao Pixel、Channel Talk）也是另一个陷阱：它们大多会直接访问 window，因此你必须通过 next/script 并设置 strategy="afterInteractive" 来强制隔离它们。漏掉这一步，构建仍然会通过，但 LCP 实际上会变得更差，大约慢 0.8 秒——我见过这种情况。最后，如果你部署在 Cloudflare Pages 或 Vercel Edge 上，DB connection pooling 在 Edge runtime 中不可用，这意味着运行在韩国托管服务（Gabia、Cafe24 RDS）上的团队，需要认真考虑并行迁移到 PlanetScale、Neon 或 Supabase。没有这一步，你永远看不到真实的 RSC 性能数据——而这个限制在官方文档中明显缺失，尽管它正是实践中团队最常卡住的地方。

总结

RSC 不是“更好的 SSR”——它是一种新架构。完整迁移需要 3–6 个月，但 bundle 大小、性能和开发者体验都会改善。如果你现有的 SPA 仍然运行良好，稳妥的路径是先只用 RSC 交付新功能，然后逐步迁移影响最大的页面。