React 流式 SSR（Streaming SSR）：基于 Suspense 的 HTML 片段分批传输与注水（Hydration）

各位同学，大家好！

欢迎来到今天的“React 深度烹饪课”。我是你们的领队，一个在代码江湖里摸爬滚打多年的资深老司机。

今天咱们不聊简单的 useState，也不聊那些花里胡哨的动画库。咱们要聊的是 React 的“核武器”——流式 SSR（Streaming Server-Side Rendering）。

如果你们平时写过传统 SSR，你们肯定经历过那种“等待”的煎熬。就像你去一家高档餐厅点了一桌菜，厨师把你所有的菜都做完，端出来，一次性上齐。如果这桌菜里有道“佛跳墙”做得慢，那你得眼巴巴地盯着空盘子干瞪眼，直到最后一道菜上来，你才能动筷子。

这体验好吗？不好。用户体验（UX）直接拉胯，首屏加载时间（LCP）感人。

于是，React 18 带来了它的杀手锏：流式 SSR。简单来说，这就是“分批上菜”。厨师做完一道，端上一道。佛跳墙慢？没关系，先把清蒸鲈鱼给你，让你先吃上，不用干等。

但是，光把菜端上来还不够，还得让菜能动起来。这就涉及到了注水（Hydration）。

今天，我们就来深扒这个“分批上菜 + 粘合剂”的技术组合拳。

---

第一部分：为什么我们需要流式 SSR？—— 便秘的 HTML

在 React 18 之前，传统的 SSR 是这样的：

1. 打包阶段： React 把你的整个组件树，连同一个庞大的 React 库，统统打包成一个 JavaScript 文件。
2. 渲染阶段： 服务器把所有组件都算了一遍，生成完整的 HTML 字符串。
3. 传输阶段： 服务器把这坨巨大的 HTML 一次性塞给浏览器。
4. 等待阶段： 浏览器收到 HTML，开始下载那坨巨大的 JS 文件，然后执行 JS，最后把 HTML“注水”成可交互的页面。

问题出在哪？

如果中间有一个组件在请求 API 数据，或者计算一个极其复杂的数学题，整个渲染过程就会阻塞。就像一根水管，只要中间有个阀门关着，上游的水（HTML）就流不过去。用户只能看着白屏或者加载动画，心里嘀咕：“这破网站怎么还没好？”

流式 SSR 的核心思想：
把“渲染”和“传输”解耦。渲染是实时的，传输是流式的。

想象一下，你正在写一个长文章，流式输出意味着你每写完一段，就按一下回车发送出去。用户不需要等到你写完最后一句话，就能先看到第一句话。

---

第二部分：Node.js 流—— 水管工的艺术

要实现流式 SSR，我们得先理解 Node.js 的 Stream。

Node.js 里的流，本质上就是一个个水龙头。数据像水流一样源源不断地涌出来，而不是一次性倒进一个巨大的水桶里。

在 React 18 之前，renderToString 就像是把水倒进水桶，等满了再倒给你。而 renderToPipeableStream 则是直接接了一根管子，水龙头一开，水就顺着管子流走了。

代码示例 1：传统的“水桶”模式（阻塞）

// 伪代码演示传统 SSR 的阻塞感
function traditionalSSR() {
  // 1. 算完整个树
  const fullHTML = ReactDomServer.renderToString(<MyApp />);

  // 2. 一次性发送
  res.send(fullHTML);
}

代码示例 2：流式模式（水管模式）

// React 18 的流式渲染
import { renderToPipeableStream } from 'react-dom/server';

function streamingSSR(res) {
  const stream = renderToPipeableStream(<MyApp />);

  // 这里的 pipe 就是把 React 生成的流，塞到 HTTP 响应的流里
  stream.pipe(res);
}

看，这看起来很简单，对吧？但这里面藏着巨大的玄机。

---

第三部分：Suspense—— 什么时候“上菜”？

流式 SSR 离不开 Suspense。Suspense 是 React 的一个“暂停键”和“切片刀”。

当你在组件里使用了 use hook 来请求数据时，React 就知道：“哦，这个组件现在处于‘挂起’状态。”

这时候，流式渲染引擎会怎么做呢？

它会立刻切走这个组件，把已经渲染好的 HTML 片段发给浏览器。然后，它会盯着这个组件，等待数据回来。

如果数据回来了，React 会把剩下的 HTML 片段补上。
如果数据没回来，浏览器会显示 Suspense 的 fallback UI（比如一个转圈圈）。

关键点： 只有被 Suspense 包裹的组件，或者使用了 use hook 的组件，才会被切成小块。其他同步渲染的组件，依然会像传统 SSR 一样，一次性算完。

代码示例 3：Suspense 的魔法

import { Suspense, useState, use } from 'react';

// 模拟一个异步组件
function ProfileImage() {
  // 模拟网络请求，耗时 2 秒
  const data = use(fetchData('/avatar.jpg'));
  return <img src={data} alt="Avatar" />;
}

function ProfilePage() {
  return (
    <div>
      <h1>用户资料</h1>

      {/* 这里是流式传输的关键 */}
      <Suspense fallback={<div>正在加载头像...</div>}>
        <ProfileImage />
      </Suspense>

      <p>这是主要内容，它不需要等待头像，直接渲染！</p>
    </div>
  );
}

function fetchData(url) {
  return fetch(url).then(res => res.text());
}

在这个例子中，<ProfileImage /> 是一个异步组件。当服务器渲染时，React 会遇到 use hook。

1. React 看到数据没准备好。
2. React 把 <div>正在加载头像...</div> 的 HTML 发给浏览器。
3. React 等待 fetchData 完成。
4. 如果完成，再把 <img src="..."> 的 HTML 补上。

效果： 用户立刻看到了“正在加载头像…”和“这是主要内容”。虽然头像还在转圈，但用户已经能阅读文字了。这种体验，比干等 2 秒再看一张图片，要爽得多。

---

第四部分：注水（Hydration）—— 把 HTML 变成活的

现在，我们的“菜”已经分批端上来了。HTML 在浏览器里是死的，它只是一堆字符串。用户点击按钮没反应，输入框打不出字。

这时候，我们就需要 Hydration（注水）。

注水，听起来很高大上，其实原理很简单：把 React 的“大脑”移植到浏览器里。

注水的流程：

1. HTML 到手： 浏览器收到了服务器发来的 HTML 片段。
2. JS 加载： 浏览器下载了 React 的 JS 文件。
3. React 启动： React 在浏览器里重新跑了一遍组件树，试图生成一模一样的 HTML。
4. 比对与挂载：
   • React 发现：“嘿，这个 <button> 标签，我在浏览器里也生成了，一模一样！”
   • React 就把这个按钮标记为“已存在”。
   • React 给这个按钮挂上 onClick 事件监听器。
   • React 给这个 <input> 挂上 onChange 事件监听器。
5. 完成： 页面从“死”的 HTML 变成了“活”的 SPA（单页应用）。

流式 SSR 的注水挑战：

这才是最麻烦的地方。

因为 HTML 是分批发送的，React 怎么知道“我现在正在注水第 10 片 HTML”？

React 18 内部引入了一个调度器。当 JS 加载完毕，React 会开始注水。如果注水过程中，遇到了一个还没发过来的 HTML 片段（比如那个还没回来的 ProfileImage），React 会暂停注水，等待。

一旦服务器把那片 HTML 发过来，React 立刻接住，继续注水。

代码示例 4：流式渲染与注水的结合

import { renderToPipeableStream } from 'react-dom/server';
import React from 'react';

const App = () => (
  <div>
    <h1>欢迎来到流式世界</h1>
    <Suspense fallback={<div className="loading">加载中...</div>}>
      <SlowComponent />
    </Suspense>
  </div>
);

// 模拟一个慢速组件
function SlowComponent() {
  // 模拟耗时操作
  const data = use(fetchData('/slow-data'));
  return <div>{data}</div>;
}

// 服务端入口
const server = renderToPipeableStream(<App />, {
  // onShellReady: 当主要的 HTML 片段（非 Suspense fallback）都准备好了，
  // 就可以发送 HTTP 响应头了，告诉浏览器“你可以开始渲染了”。
  onShellReady() {
    res.statusCode = 200;
    res.setHeader('Content-type', 'text/html');
    stream.pipe(res);
  },

  // onShellError: 当主组件树出错（比如 API 爆炸了），怎么处理？
  onShellError(error) {
    res.statusCode = 500;
    res.send('<!doctype html><p>Error</p>');
  },

  // onError: 当某个 Suspense 组件出错（比如数据加载失败），
  // 不会影响主线程，只会把这个错误显示在对应的 fallback 里。
  onError(error) {
    console.error(error);
  }
});

这段代码里的玄机：

• onShellReady：这是流式 SSR 的灵魂。只要主框架（Shell）的 HTML 渲染完了，不管里面的 SlowComponent 还在转圈，我都立刻把响应头发出去。浏览器就开始渲染 HTML，同时下载 JS。这就是所谓的“边下边看”。
• onError：流式 SSR 允许局部失败。如果 SlowComponent 加载失败，它只是显示“加载失败”的 UI，而不会把整个页面搞崩。

---

第五部分：深入 Suspense 的“树”结构

为了让大家彻底明白，咱们得稍微深挖一下 React 的内部机制。

在传统的 SSR 中，组件树是一棵树。
在流式 SSR 中，组件树变成了一种分层的结构。

想象一下，你的应用是一个巨大的树，中间有一个节点是个“异步节点”（比如 SlowComponent）。

1. 同步部分： 树的根节点、左边的分支、右边的分支，这些是同步渲染的。React 把它们拼成一个大块，发给浏览器。
2. 异步部分： SlowComponent 本身，以及它下面的子节点，这些是异步的。

React 在服务器端会把这个树切分成很多“流式块”。

• 块 1：根节点 + 左分支（同步）
• 块 2：右分支（同步）
• 块 3：SlowComponent 的开始标签（异步等待中）
• 块 4：SlowComponent 的内容（数据回来后）

浏览器收到块 1，渲染出来。
浏览器收到块 2，渲染出来。
浏览器收到块 3，发现是 <div>Loading...</div>，渲染出来。

注水的时候，React 也是按块来的。

这里有个非常关键的点： React 必须保证发送的 HTML 顺序和客户端渲染的顺序是一致的。

如果服务器先发了块 1，再发块 2，那浏览器就会先渲染块 1，再渲染块 2。
React 在客户端也会先渲染块 1，再渲染块 2。这样 React 才能认出：“哦，这是同一个节点，我直接挂载事件监听器就好，不用重建 DOM。”

---

第六部分：Next.js 的应用—— 实战演练

虽然 React 核心提供了 renderToPipeableStream，但实际开发中，我们很少直接用这个 API。因为还要处理 HTTP 头、压缩、错误处理、服务端组件（RSC）等一堆乱七八糟的事情。

Next.js 13 的 App Router 就是流式 SSR 的集大成者。

在 Next.js 里，你只需要写普通的组件，Next.js 会自动处理流式传输。

代码示例 5：Next.js 中的流式 SSR（伪代码）

// app/page.tsx
import { Suspense } from 'react';

async function Header() {
  // 这是一个服务端组件，Next.js 会自动流式传输它
  return <header>我是头部</header>;
}

async function Comments() {
  // 模拟异步加载
  await new Promise(r => setTimeout(r, 2000));
  return <div>评论内容...</div>;
}

export default async function Home() {
  return (
    <div>
      <Header />

      <main>
        <h1>首页</h1>

        {/* Suspense 让我们能够优雅地处理 Comments 的加载 */}
        <Suspense fallback={<p>正在加载评论...</p>}>
          <Comments />
        </Suspense>
      </main>
    </div>
  );
}

在 Next.js 里，所有的服务端组件（默认）都是异步的。当你把它们组合在一起时，Next.js 会自动分析哪些组件是同步的，哪些是异步的。

• 同步组件 -> 立刻发送。
• 异步组件 -> 包裹在 Suspense 里，等待数据。

Next.js 会自动生成 onShellReady 和 onError 的逻辑，你完全不需要操心。

---

第七部分：流式 SSR 的陷阱与坑

虽然流式 SSR 很美好，但作为资深专家，我必须提醒大家，这玩意儿也有坑。

1. 不可序列化的数据（致命伤）

流式 SSR 依赖于流。流是线性的。

如果你的组件里用了 useEffect，并且在这个 effect 里修改了 DOM，或者使用了非序列化的对象（比如 Set, Map，或者包含循环引用的对象），React 就会报错。

为什么？因为 React 必须把组件的状态序列化成 HTML 字符串发送给浏览器。如果状态里包含了一个“活”的对象，React 就不知道该怎么把它变成 HTML。

代码示例 6：错误的流式 SSR 写法

function BadComponent() {
  const [items, setItems] = useState(new Set(['a', 'b'])); // Set 不能序列化

  useEffect(() => {
    // 这个 effect 修改了 DOM
    document.getElementById('my-id').style.color = 'red';
  }, []);

  return <div>{/* 这里会报错：对象不可序列化 */}</div>;
}

解决方法：

• 不要在服务端渲染的组件里用 useEffect 修改 DOM。
• 不要在服务端渲染的组件里用 useState 存储不可序列化的数据。
• 如果必须用，请使用 useMemo 或 useCallback 进行序列化处理。

2. 客户端与服务端的差异

这是最让人头秃的问题。

假设你在服务端渲染了一个 div，里面有个 id="app"。
然后在客户端的 JS 里，你试图挂载一个 React 根节点到 document.getElementById('app')。

如果服务端发送的 HTML 里没有这个 div，或者 id 不对，React 就会报错：“Hydration failed because the initial UI does not match what was rendered on the server.”

原因： 服务端和客户端的代码执行结果不一致。可能是时区不同，可能是随机数生成器不同，也可能是服务端组件的数据和客户端组件的数据不一致。

代码示例 7：Hydration Mismatch

// 服务端
function ServerTime() {
  return <div>{new Date().toLocaleTimeString()}</div>; // 服务端时间是 10:00
}

// 客户端
function ClientTime() {
  const [time, setTime] = useState(new Date().toLocaleTimeString()); // 客户端时间是 10:01
  return <div>{time}</div>;
}

解决方法：

• 使用 suppressHydrationWarning 标签（不推荐，这是治标不治本）。
• 在客户端组件里，在 useEffect 里检查时间差，如果不同，更新状态。

function ClientTime() {
  const [time, setTime] = useState(new Date().toLocaleTimeString());

  useEffect(() => {
    const serverTime = new Date().toLocaleTimeString();
    const clientTime = new Date().toLocaleTimeString();

    if (serverTime !== clientTime) {
      setTime(clientTime);
    }
  }, []);

  return <div>{time}</div>;
}

---

第八部分：流式 SSR 与客户端渲染（CSR）的混合

在实际项目中，我们很少全站 SSR，也很少全站 CSR。

通常，我们会有一个混合模式：

• 关键内容（首屏）： 用 SSR（为了 SEO 和首屏速度）。
• 非关键内容（评论区、推荐列表）： 用 CSR（为了交互流畅，不阻塞首屏）。

代码示例 8：混合模式

import { Suspense } from 'react';

// 1. 同步 SSR 部分
function HeroSection() {
  return <h1>超级英雄登场！</h1>;
}

// 2. 异步 SSR 部分（流式传输）
function HeroImage() {
  const data = use(fetchImage());
  return <img src={data} />;
}

// 3. CSR 部分（完全在浏览器运行）
function CommentsWidget() {
  // 这个组件在服务端不渲染，直接挂载到 DOM
  return <div className="comments-csr">评论区 (纯前端)</div>;
}

export default function Page() {
  return (
    <div>
      <HeroSection />

      <Suspense fallback={<div>图片加载中...</div>}>
        <HeroImage />
      </Suspense>

      {/* 这个组件会被 React 直接挂载，不需要 SSR */}
      <CommentsWidget />
    </div>
  );
}

这种混合模式利用了流式 SSR 的优势（图片部分不阻塞文字），同时也利用了 CSR 的优势（评论区不需要 SEO，也不需要等图片）。

---

第九部分：性能优化的终极奥义

流式 SSR 的终极目标是什么？

降低 TTFB（Time To First Byte）和 LCP（Largest Contentful Paint）。

• TTFB 降低： 因为主框架 HTML 发送得快了，服务器不用等所有组件算完。
• LCP 降低： 因为关键的、大的图片或内容（在 Suspense 包裹下），可以尽快发送。

代码示例 9：自动代码分割与流式传输

React 的流式渲染是和代码分割完美配合的。

当你使用 React.lazy 加载一个组件时，这个组件的代码块（chunk）会在运行时下载。

import { lazy, Suspense } from 'react';

// 懒加载组件
const HeavyChart = lazy(() => import('./HeavyChart'));

function Dashboard() {
  return (
    <div>
      <h1>仪表盘</h1>
      <Suspense fallback={<p>图表加载中...</p>}>
        <HeavyChart />
      </Suspense>
    </div>
  );
}

流式传输的魔法在于：
即使 HeavyChart 的代码块还没下载完，React 也会先发送 <p>图表加载中...</p> 给浏览器。一旦代码块下载完毕，React 立刻渲染 HeavyChart。

这比传统的 CSR（先下载 JS，再运行 JS，再渲染）要快得多，因为 HTML 提前展示了。

---

第十部分：错误处理的艺术

在流式 SSR 中，错误处理是重中之重。

假设你的主组件树里有一个组件报错了（比如数据库连接断开）。在传统 SSR 中，这会导致整个页面白屏，或者报错堆栈。

在流式 SSR 中，我们可以捕获这个错误，并优雅地降级。

代码示例 10：优雅的错误处理

import { renderToPipeableStream } from 'react-dom/server';

function App() {
  throw new Error("服务器出bug了！"); // 模拟一个错误
  return <div>Hello</div>;
}

function ErrorBoundary() {
  return <div>页面出错了，请联系管理员。</div>;
}

const stream = renderToPipeableStream(
  <React.StrictMode>
    <ErrorBoundary>
      <App />
    </ErrorBoundary>
  </React.StrictMode>,
  {
    onShellReady() {
      res.statusCode = 200;
      res.setHeader('Content-type', 'text/html');
      stream.pipe(res);
    },
    // 如果主组件树出错，这里会被触发
    onShellError(error) {
      res.statusCode = 500;
      res.send('<!doctype html><p>Error</p>');
    },
    // 如果某个 Suspense 边界内的组件出错，这里会被触发
    onError(error) {
      console.error(error);
    }
  }
);

注意区别：

• onShellError：主流程挂了（比如 App 报错），浏览器会收到一个白屏或错误页面。因为此时 Shell 都没准备好，onShellReady 没触发。
• onError：某个非关键组件挂了（比如某个图片加载失败），主流程正常，浏览器会看到错误信息，但页面其他部分依然可用。

---

第十一部分：React Server Components (RSC) —— 未来的流式

如果你已经看过 React 19 或者 Next.js 15 的文档，你会发现“流式 SSR”这个词正在慢慢淡出，取而代之的是“React Server Components”。

其实，它们是一回事。

RSC 的本质就是把 React 组件的执行权从“客户端”完全搬到了“服务端”。

在 RSC 架构下：

1. 服务器直接把组件渲染成 JSON 数据流（不是 HTML，是 JSON）。
2. 这个 JSON 流包含组件的结构、props 和状态。
3. 客户端收到 JSON 后，用 React 重新渲染一遍。

为什么这比 HTML 流式传输更牛？

1. 体积更小： JSON 可以被压缩得比 HTML 更好（因为去掉了标签名、属性名）。
2. 类型安全： 因为是 JSON，TypeScript 可以在编译时检查数据结构。
3. 无 Hydration Mismatch： 因为服务器渲染的也是 React 组件，客户端渲染的也是 React 组件，两者的结构天然一致（前提是代码一致）。

虽然 RSC 是未来的趋势，但基于 HTML 的流式 SSR 依然是理解 React 渲染机制的基础，也是目前 Next.js 13/14 的主流实现方式。

---

第十二部分：总结与实战建议

好了，讲了这么多理论，咱们来点干货。

如果你现在要在一个新项目里使用流式 SSR，我给你几条黄金建议：

1. 拥抱 Suspense： 不要试图绕过 Suspense。它是流式传输的开关。把所有可能耗时的操作（数据获取、图片加载、大计算）都包在 Suspense 里。
2. 区分组件类型：
   • 同步组件： 纯 UI，无副作用，纯函数或简单 Hook。用它们构建骨架。
   • 异步组件： 包含数据获取。用它们构建内容。
3. 不要在服务端组件里用 useEffect： 这是一个大坑。如果你必须在服务端用副作用，请确保它不会修改 DOM 或产生不可序列化的状态。
4. 处理 Hydration Mismatch： 相信我，你会遇到它的。学会使用 useEffect 来修正时区、随机数或服务端数据差异。
5. 使用 Next.js： 除非你是为了学习 React 源码，否则直接用 Next.js 的 App Router。它帮你把所有复杂的流式处理、错误边界、代码分割都搞定了。

最后的最后，我想说：

流式 SSR 不是一种“技术”，它是一种“思维模式”的转变。它从“把结果一次性给你”，变成了“把过程分批给你”。

它让 Web 应用从“笨重”变得“敏捷”。它让用户不再需要盯着那个该死的转圈圈，而是能先看到内容，再看到细节。

这就是 React 带给我们的现代 Web 开发体验。

希望今天的讲座能让你对流式 SSR 有一个深刻的理解。下课！