服务端渲染并不是在Node.js里用模板字符串拼出HTML那么简单。它要求开发者维护一套可以在服务端和浏览器端运行的JavaScript组件代码，服务端负责首次渲染出完整文档，浏览器随后接管页面交互。这个过程涉及虚拟DOM到字符串的转换、路由同步、数据预取以及状态恢复，任何一环处理不当都会导致页面闪烁、重复请求或事件失效。
同构应用与客户端水合的关系
同构应用的核心思路是编写一份组件代码，服务端通过对应框架的渲染API将组件树转换成HTML字符串，浏览器加载完脚本后再对这些静态标记进行事件绑定和状态接管。React提供的renderToString可以把组件渲染成HTML，但这里生成的字符串并不包含任何事件处理器。Vue的createSSRApp配合renderToString也有同样的行为。真正让页面可交互的过程叫水合，也就是客户端用同一份组件树去匹配服务端已经输出好的DOM结构，并为节点添加事件监听。
水合成功的前提是服务端和客户端渲染结果必须一致。如果组件内部使用了Math.random、Date.now或者直接访问window对象，可能导致两端内容不同。浏览器端水合时会发现DOM不匹配，React会抛出警告，Vue会尝试修复但性能会明显下降。因此同构组件必须保持纯渲染逻辑，把依赖浏览器环境的操作放到useEffect或onMounted中执行。
下面的代码展示了React最基本的服务端渲染过程，它只负责输出首屏HTML，暂时不包含交互和路由。
import express from 'express';
import React from 'react';
import { renderToString } from 'react-dom/server';
import App from './App';
const app = express();
app.get('*', (req, res) => {
const content = renderToString(<App location={req.url} />);
const html = `<!DOCTYPE html><html><body><div id="root">${content}</div><script src="/client.js"></script></body></html>`;
res.send(html);
});
app.listen(3000);
在这个例子中，renderToString只生成了静态内容，<div id="root">里的节点没有任何事件。客户端入口需要调用hydrateRoot或者hydrate来接管页面。
构建服务端渲染入口
服务端渲染入口通常需要处理路由、创建应用实例、渲染组件并注入完整HTML模板。以Express为例，可以使用通配路由把请求转发给渲染函数，再由框架路由系统匹配对应页面组件。React Router提供了StaticRouter用于服务端路由，它根据请求URL决定渲染哪个组件。Vue Router则使用createMemoryHistory来避免在Node环境中操作浏览器地址栏。
HTML模板的注入需要格外小心。首屏内容插入到<div id="app">中，同时还要把打包后的客户端脚本路径写入模板。通常项目会准备一个index.html作为外壳，服务端读取后替换占位符。下面是一个更完整的Node服务实现，它包含了路由匹配和模板注入。
import fs from 'fs';
import path from 'path';
import express from 'express';
import React from 'react';
import { renderToString } from 'react-dom/server';
import { StaticRouter } from 'react-router-dom/server';
import App from './App';
const app = express();
const template = fs.readFileSync(path.resolve('dist/index.html'), 'utf-8');
app.get('*', (req, res) => {
const content = renderToString(
<StaticRouter location={req.url}>
<App />
</StaticRouter>
);
const html = template
.replace('<div id="app"></div>', `<div id="app">${content}</div>`);
res.status(200).send(html);
});
app.listen(3000, () => console.log('SSR server running on 3000'));
其中template.replace的第一个参数在真实项目中需要与构建产物中的占位符保持一致。如果使用Vite或Webpack生成HTML，可能会使用id="app"的容器，替换逻辑仍然成立。服务端渲染入口必须保持无状态，因为同一个Node进程可能会同时处理多个请求，任何模块级可变状态都会造成请求间数据污染。
数据预取与状态脱水
首屏渲染最棘手的问题是如何在服务端获取数据，并把数据交给客户端继续使用。如果服务端只渲染了页面外壳，客户端还需要重新请求接口，首屏性能提升就打了折扣。同构应用通常会在组件上定义静态的数据预取方法，服务端在渲染前调用这些方法获取数据，再把结果序列化后注入到HTML中。
状态脱水指的是把服务端已经拿到的数据以全局变量的形式写入页面。客户端启动时读取这个全局变量，用它初始化自己的store或组件状态。这样浏览器端在水合时可以直接使用服务端数据，避免重复请求。状态必须经过JSON序列化，因为注入到HTML中的数据本质上是字符串。可以使用JSON.stringify处理数据，再通过replace防止用户数据中包含</script>导致XSS攻击。
const store = createStore();
await store.dispatch(fetchUser(req.params.id));
const state = store.getState();
const serializedState = JSON.stringify(state).replace(/</g, '\\u003c');
const html = template
.replace('<div id="app"></div>', `<div id="app">${content}</div>`)
.replace(
'</body>',
`<script>window.__INITIAL_STATE__ = ${serializedState};</script></body>`
);
这段代码中replace(/</g, '\\u003c')的作用是把序列化数据中的小于号转成Unicode转义形式，防止恶意数据提前闭合脚本标签。客户端入口在创建store时读取window.__INITIAL_STATE__并调用replaceState，这样水合阶段就能保持服务端和客户端的数据一致。
组件级的数据预取可以根据路由配置来执行。例如在React Router中，可以遍历匹配到的路由，找到组件上挂载的loadData方法并依次执行。数据请求应当并行发起，减少首屏等待时间。服务端完成所有请求后再调用renderToString，客户端水合前也执行同样的预取逻辑，但此时如果已有脱水数据则直接跳过请求。
性能优化与常见陷阱
同构应用的性能瓶颈往往出现在服务端渲染本身。组件树过大或数据请求过慢会直接拖长响应时间。针对这种情况，可以采用流式渲染方案。React的renderToPipeableStream允许服务端边渲染边输出HTML，浏览器可以更早开始解析文档。流式渲染还能配合Suspense实现选择性水合，优先处理用户可见区域的内容。
缓存是另一个重要优化点。服务端渲染的结果可以按路由和用户角色缓存到内存或Redis中。对于公开页面，缓存完整的HTML字符串；对于个性化页面，可以缓存组件渲染结果而不缓存用户数据。需要注意的是，缓存键中包含用户信息时很容易造成数据泄露，因此缓存策略必须与权限校验严格分离。
常见陷阱包括：在组件渲染期间访问localStorage导致服务端报错；使用window对象时没有做环境判断；服务端和客户端使用了不同的API地址；状态脱水中漏掉了日期类型的处理。日期经过JSON序列化后会变成字符串，客户端需要使用new Date()恢复。另一个容易忽略的问题是样式闪烁，服务端渲染输出的HTML缺少样式表引用时，页面会出现短暂的无样式状态。应当把关键CSS内联到模板中，或者使用支持SSR的CSS方案。
错误处理同样重要。服务端渲染入口一旦抛出异常，整个请求就会失败。可以给renderToString包裹try...catch，当渲染出错时降级为客户端渲染，返回空的容器HTML。这样虽然首屏变慢，但不会出现白屏。生产环境还应监控服务端渲染耗时、错误率和内存占用，及时发现问题。
服务端渲染同构应用JavaScript修改时间：2026-08-28 13:25:33