流式SSR架构设计解析

流式 SSR 并非简单“让页面更快渲染”，而是要在 React 18 的 renderToPipeableStream 基础上，精密协同 hydration 稳定性、组件级数据预取、分层错误边界与脚本注入时序四大关键环节——稍有不慎，看似流畅的流式输出就会退化为更卡顿的体验：hydration 失败导致强制重绘、数据重复请求引发闪烁、单个 chunk 报错拖垮整页、CSS 未临界提取造成样式闪动……真正可靠的流式，是每个 Suspense 块都可独立失败恢复、每段 HTML 都精准锚定客户端接管时机、每份初始数据都在 hydrateRoot 启动前就位的系统工程。

同构渲染本身不难，难的是流式 SSR 里让 React/Vue 的 hydration 不崩、数据不重复请求、错误边界能兜住——这三件事没处理好，流式就只是看起来快，实际更卡。

React 18 的 renderToPipeableStream 是唯一靠谱起点

别碰 renderToString 或旧版 renderToNodeStream，它们没法中断/恢复、不支持 Suspense、错误时整个 stream 就断了。React 18+ 的 renderToPipeableStream 才真正适配流式语义：

• 支持 Suspense 边界内异步组件的分块 flush，比如导航栏先出，商品列表后出
• 错误发生时只丢弃当前 chunk，不影响已 flush 的 HTML 和后续内容
• 必须搭配 ReactDOMClient.hydrateRoot（不是 hydrate）才能正确接续 hydration

注意：Node.js 版本至少 16.14+，且服务端不能用 ESM 模式加载 React（会破坏 pipeable 内部的模块状态追踪）。

数据获取必须和组件声明耦合，不能靠 useEffect 或全局 store

流式 SSR 要求「组件一被 render，它的数据就该准备好」，否则会卡住当前 chunk。传统 getServerSideProps 或手动 fetch 在入口层聚合，无法对齐组件粒度。

• 用 React.lazy + 自定义 loadable 包裹异步组件，并在 fallback 中触发数据预取（如 useQuery 的 initialData 来自服务端注入）
• 推荐 react-query 的 dehydrate/Hydrate 配合流式：在 renderToPipeableStream 的 onShellReady 回调里序列化 query cache，注入到 HTML 的