HTML SSR原理详解｜服务端渲染工作流程解析

本文深入剖析了HTML服务端渲染（SSR）的本质与关键机制，明确指出SSR绝非简单返回静态index.html，而是在Node.js环境中安全执行前端组件、同步获取并注入数据、生成带内容的HTML字符串，并严格保障与客户端水合（hydration）的结构与状态一致性；文章系统拆解了React的renderToString和Vue 3的createSSRApp等核心实现原理，强调规避浏览器API、确保同构性、正确处理路由与状态管理，以及模板仅作为壳子而非渲染主体等易被忽视却至关重要的实践要点，帮助开发者真正理解SSR“为什么这样设计”和“错在哪里”。

纯 HTML 文件本身不参与 SSR，SSR 的核心是「在 Node.js 环境中运行前端组件代码，生成带数据的 HTML 字符串」——你手头那个 index.html 只是最终拼接用的壳子，不是渲染主体。

为什么直接读取 index.html 不算 SSR

常见错误是把 fs.readFileSync('./index.html') 的结果返回给浏览器，这本质是静态文件服务，和 SSR 无关。真正 SSR 必须包含：组件执行、数据注入、HTML 字符串合成三个环节。Node.js 里没有 document、window 或 DOM API，所以任何依赖这些的代码（比如 document.getElementById、useRouter 在未适配时）会直接报 ReferenceError: document is not defined。

• 静态 index.html 没有 JS 执行能力，无法响应不同 URL 渲染不同内容
• 没做数据获取逻辑（如 API 调用、数据库查询），页面就是空的或硬编码的
• 没预留客户端水合（hydration）入口，后续交互会失效或重复渲染

React 中 renderToString 是怎么工作的

renderToString() 是 react-dom/server 提供的同步渲染函数，它接收一个 React 元素（如 ），在 Node.js 中模拟挂载过程，递归调用组件的 render 方法，跳过所有浏览器专属生命周期（如 useEffect、useLayoutEffect），只输出纯 HTML 字符串。它不执行事件绑定、不创建真实 DOM 节点，也不触发 ref 回调。

• 必须确保组件是“同构”的：不能含 window.location、localStorage 等浏览器全局对象
• 异步数据需在服务端提前获取，再通过 props 或 context 注入，不能靠组件内 useEffect 触发
• 返回的是字符串，不是 DOM 对象，所以不能对它调用 .appendChild() 或其他 DOM 方法

Vue 3 为什么必须用 createSSRApp

Vue 3.2+ 提供了 createSSRApp 替代 createApp，区别在于前者会屏蔽服务端不兼容的逻辑：比如跳过 onMounted、禁用 useRouter 的路由守卫、绕过 ref 的响应式追踪初始化。如果错用 createApp，组件一执行就会因尝试访问 document 或 window 报错。

• createSSRApp 返回的 app 实例不支持 mount()，只支持 renderToString() 或 renderToNodeStream()
• 路由需配合 vue-router 的 createMemoryHistory，不能用 createWebHistory
• 状态管理（如 Pinia）也得用 createPinia() + serverPrefetch 钩子预取数据

HTML 模板只是容器，不是渲染目标

你在 Express 或 Koa 中写的 res.send(`

`)，其中 htmlString 来自 renderToString()，而