JavaScript实现服务端渲染教程

本文深入剖析了JavaScript实现服务端渲染（SSR）的关键原理与实战陷阱，明确指出JS本身无法直接SSR，必须依托Node.js环境并配合React、Vue等框架提供的专用API（如renderToString或createSSRApp）；文章直击核心痛点——浏览器API（如document、window）在服务端不可用、客户端与服务端执行环境差异导致的水合失败、数据预取与状态同步难题，以及路由、静态资源路径、第三方库兼容性等常见坑点，并给出可落地的规避策略和代码范式，帮助开发者真正跨越“本地能跑”到“生产可用”的鸿沟。

JavaScript 本身不能直接实现服务端渲染（SSR），它需要运行在 Node.js 环境中，并配合框架或手动调用 renderToString / renderToNodeStream 等 API 才能完成。纯浏览器端的 JavaScript 无法 SSR。

为什么 document 在 Node.js 里不可用

服务端没有 DOM，document、window、localStorage 等浏览器全局对象在 Node.js 中未定义。直接运行依赖它们的前端代码会抛出 ReferenceError: document is not defined。

• React/Vue/Angular 的 SSR 入口必须避开客户端专属逻辑（比如组件挂载后才执行的 useEffect 或 mounted）
• 第三方库若内部访问 window，需用 typeof window !== 'undefined' 包裹，或通过 Webpack 的 target: 'node' + externals 隔离
• 静态资源路径（如 public/ 下的图片）在服务端需转为 path.join(__dirname, '../public')，不能靠相对 URL

React 中用 renderToString 做最简 SSR

这是 React 官方支持的同步 SSR 方式，适用于首屏内容确定、无异步数据获取的场景。

• 必须使用 ReactDOMServer.renderToString，不是 ReactDOM.render
• 组件必须是纯函数组件或 class 组件，且不能依赖浏览器 API
• 服务端需提前注入初始 props（比如从数据库或 API 获取的数据），再传给组件
• 示例关键代码：

import { renderToString } from 'react-dom/server';
import App from './App.js';

const html = renderToString();
res.send(`
  
  
    
      
${html}
      
    
  
`);

Vue 3 的 renderToString 需要 createSSRApp

Vue 3 的 SSR 不再兼容普通 createApp，必须用专用的 SSR 入口。

• 服务端入口不能直接 import .vue 单文件组件，需用 defineAsyncComponent 或预编译 SFC
• 必须调用 createSSRApp 创建应用实例，否则 renderToString 会报错
• 响应式状态在服务端不触发更新，所以所有数据应通过 props 或 provide/inject 注入，而非 ref 或 reactive 后动态改
• 常见错误：TypeError: Cannot read property 'push' of undefined —— 通常是因为路由未用 createMemoryHistory 初始化

真实项目绕不开数据预取和水合 mismatch

只渲染 HTML 不够，客户端 JS 加载后必须“水合”（hydrate）服务端生成的 DOM。一旦服务端与客户端渲染结果不一致，Vue 会警告 Hydration failed，React 则会丢弃整个节点并重新渲染。

• 数据获取不能写在 useEffect 或 onMounted 里——服务端不执行这些钩子，导致首屏没数据
• 推荐方案：在路由组件上定义 asyncData 或 load 方法，服务端提前调用并把结果序列化进 HTML 的