各位开发者，大家好！欢迎来到今天的“前端架构实战”讲座。我是你们的老朋友，那个发誓再也不写 jQuery 代码，结果最后还是被重构折磨得死去活来的资深工程师。
今天我们要聊一个非常有意思，甚至有点“反直觉”的话题：React 预渲染。
我知道，听到“预渲染”三个字，你脑海里可能浮现出的是 Next.js 或者 Nuxt.js 的官方文档，或者是 react-snap 那个略显老派的 CLI 工具。但今天，我要带你们撕开这些框架的外衣，看看在底层，我们到底在玩什么把戏。我们要探讨的是一种基于构建期的静态页面生成与动态注入的混合渲染架构。
听起来很高大上，对吧？其实说白了，这就是一种“诈尸”技术——让 HTML 在你还没死（用户还没打开网页）之前，先准备好，甚至活动一下筋骨。
第一部分：为什么我们要在这个时候聊“预渲染”？
让我们先回到两年前。那时候，我们大多数人在做 React 项目时，信奉的是什么？是 CSR（Client-Side Rendering，客户端渲染）。
CSR 的流程是这样的：
- 浏览器下载一个空的
index.html。 - 浏览器解析 HTML，发现里面只有
<div id="root"></div>。 - 浏览器去下载几百 KB 的 JS 文件。
- JS 文件在浏览器里运行，把数据请求回来，然后像变魔术一样，把内容塞进那个
div里面。
这就像什么？ 这就像你去一家餐厅吃饭，服务员端上来一个空盘子，然后说：“先生，请稍等，我正在去厨房给你炒菜，炒好了再端上来。”
你在门口等了 5 秒钟，看起来很正常；但如果你是那个急着看菜名的 Google 机器人（SEO），你就会觉得：“这餐厅没货啊！”
痛点来了：
- SEO（搜索引擎优化）灾难：爬虫只看得到空壳，看不到内容。你的博客、你的产品页，在 Google 上一搜全是空的。
- 首屏加载慢（FCP）：用户点开链接，白屏几秒，然后突然“砰”地一下内容弹出来。这种体验，就像是在看慢动作回放，用户会以为你网站崩了。
于是，大家开始搞 SSR（Server-Side Rendering，服务端渲染）。
服务端渲染是这么干的：服务器收到请求，生成完整的 HTML，直接扔给浏览器。
这体验好极了！ 首屏秒开，爬虫也能看懂。但是，服务器很累啊！每次请求都要启动 Node.js 进程，都要跑一遍 React 代码，还要处理状态管理。如果并发量大，你的服务器 CPU 就要冒烟了。
这时候，有人提出了一个折中方案：预渲染。
我们不搞服务端渲染，我们搞构建期渲染。在用户打开网页之前，我们（在 CI/CD 管道里）把页面生成好。用户打开的时候，直接拿到现成的 HTML。
这就像什么？ 就像你在餐厅做饭的时候，先把菜炒好，装进保温盒里。客人一来，直接开盖吃。既快（不需要现场炒），又保证了内容（不像空盘子）。
但是！问题来了。预渲染的页面是静态的。如果页面里有“点赞”、“评论”这种需要跟后端交互的功能，预渲染完的 HTML 就是一堆死文字。用户点一下没反应，这叫什么？这叫“金玉其外，败絮其中”。
所以，今天我们要讲的主角——混合渲染架构，就是为了解决这个问题的。
第二部分：混合渲染架构的设计哲学
混合渲染的核心思想可以用一句话概括：“骨架是死的，灵魂是活的。”
我们的架构分为两层：
- 静态层（构建期生成）：负责展示。这部分内容不需要交互，或者交互成本很低（比如导航栏、文章正文、分类标签）。这部分我们在构建时生成 HTML 文件。
- 动态层（运行时注入）：负责交互。这部分内容（比如评论框、即时搜索、动态图表）我们在构建时留个空，或者生成一个简单的容器，等浏览器加载完 React 应用，再通过 Hydration（水合） 或者 Dynamic Injection（动态注入） 的方式，把交互逻辑挂上去。
这就像是一个人体模型。我们用木头和塑料搭建了一个栩栩如生的人体模型（静态 HTML），放在橱窗里展示（SEO 友好）。当观众凑近看的时候，我们再把那个人的大脑（JS 逻辑）和神经（交互事件）接通，让他动起来（用户交互）。
这种架构的优势非常明显：
- 极致的 SEO：搜索引擎爬到的全是完整的 HTML，没有 JS 烦恼。
- 极致的加载速度：用户不需要下载几百 KB 的 JS 代码就能看到内容（如果只预渲染首屏的话）。
- 按需加载：只有当用户真的想交互的时候，我们才去加载那部分复杂的逻辑。
第三部分：实战演练——如何实现这种架构？
光说不练假把式。让我们来手把手实现一个简单的混合渲染架构。为了演示方便，我们使用 Vite 作为构建工具（因为它比 Webpack 更像“现代前端”的工具）。
步骤 1：定义组件
首先，我们要把我们的组件拆分一下。我们要把“静态内容”和“动态交互”分开。
假设我们有一个博客文章页面：
// components/ArticlePage.jsx
import React, { useState } from 'react';
import { Link } from 'react-router-dom';
const ArticlePage = ({ title, content }) => {
// 这是一个纯展示的静态组件
const StaticHeader = () => (
<header>
<nav>
<Link to="/">首页</Link>
<Link to="/about">关于</Link>
</nav>
<h1>{title}</h1>
<p>发布于：2023-10-27</p>
</header>
);
// 这是一个动态组件，包含交互逻辑
const DynamicFooter = ({ likes }) => {
const [count, setCount] = useState(likes);
return (
<footer className="interactive">
<p>这篇文章很棒，共 {count} 人点赞。</p>
<button onClick={() => setCount(count + 1)}>
点赞
</button>
</footer>
);
};
return (
<article>
<StaticHeader />
<div className="content">
<p>{content}</p>
</div>
{/* 这里我们只渲染静态的 Footer，动态的交给后续处理 */}
<DynamicFooter likes={0} />
</article>
);
};
export default ArticlePage;步骤 2：构建期静态生成
现在，我们需要一个插件，在构建的时候，把 ArticlePage 渲染成 HTML 字符串，并保存成文件。Vite 的 build 阶段可以做到这一点。
我们需要写一个简单的 Vite 插件，或者利用 vite-plugin-static-copy 配合自定义逻辑。为了展示架构原理，我们写一个极其简陋的插件：
// plugins/prerender.js
import fs from 'fs';
import path from 'path';
import { fileURLToPath } from 'url';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
export function prerenderPlugin() {
return {
name: 'vite-plugin-prerender',
apply: 'build',
closeBundle() {
console.log('开始执行预渲染...');
// 1. 这里模拟读取构建后的 HTML（实际中可能需要读取 dist 目录）
// 在真实场景中，你可以直接在这里调用 React 渲染函数，获取 HTML 字符串
const html = `
<!DOCTYPE html>
<html>
<head>
<title>我的混合渲染博客</title>
<meta name="description" content="这是一个静态生成的页面">
<link rel="stylesheet" href="/style.css">
</head>
<body>
<div id="app">
<!-- 静态内容区域 -->
<header class="static-header">
<h1>React 混合渲染架构</h1>
<p>构建期生成的内容，SEO 友好。</p>
</header>
<div class="static-body">
<p>这是静态生成的正文内容。搜索引擎可以直接抓取这里。</p>
<p>这里没有 JS 运行时的开销，加载速度极快！</p>
</div>
<!-- 交互区域容器 -->
<div id="root-interaction"></div>
</div>
<!-- 静态 JS 依赖（如果有） -->
<script src="/vendor.js"></script>
</body>
</html>
`;
// 2. 写入文件
const outputPath = path.join(__dirname, '../dist/index.html');
fs.writeFileSync(outputPath, html.trim());
console.log('预渲染完成！静态 HTML 已生成。');
}
};
}注意看上面的代码，我们生成了一个 HTML。里面有一个 <div id="app">，里面全是静态 HTML。还有一个 <div id="root-interaction">，这是留给我们的“动态注入”的空位。
步骤 3：动态注入与水合
现在，当用户访问你的网站时，他们拿到的是那个静态的 index.html。页面瞬间就显示了标题和正文。但是，那个“点赞”按钮是灰色的，没有功能。
这时候，我们需要在浏览器里加载我们的 React 应用程序，把那个“点赞”按钮给激活。
这就是 Client-side Hydration（客户端水合）。
// src/main.js
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
// 我们需要先检查一下，当前页面是不是已经预渲染过的
// 在实际项目中，你可能需要从 URL 参数或者路由配置中判断
const isPrerendered = true;
function initApp() {
// 获取那个静态 HTML 里的容器
const rootContainer = document.getElementById('root-interaction');
if (rootContainer) {
// 如果容器存在，说明这是预渲染页面，我们需要执行 Hydration
console.log('检测到预渲染环境，执行 Hydration...');
// 这里我们只渲染动态部分
// 在实际项目中，你应该根据路由渲染对应的组件
ReactDOM.hydrateRoot(
rootContainer,
<React.StrictMode>
<App />
</React.StrictMode>
);
} else {
// 如果容器不存在，那这就是纯 CSR 模式（或者 SPA 跳转过来的）
console.log('未检测到预渲染环境，执行客户端渲染...');
const mainContainer = document.getElementById('app');
ReactDOM.createRoot(mainContainer).render(
<React.StrictMode>
<App />
</React.StrictMode>
);
}
}
// 等待 DOM 加载完毕
document.addEventListener('DOMContentLoaded', initApp);这里的关键点在于 hydrateRoot。
hydrateRoot 会读取 DOM 中现有的 HTML 节点，然后 React 会去“对号入座”。它会检查你的 JSX 结构和现有的 HTML 结构是否一致。如果一致，它就复用这些节点，只挂载事件监听器。这比 createRoot 更快，因为它省去了创建 DOM 节点的开销。
第四部分：进阶架构——Shadow DOM 与 组件级注入
上面的例子是“页面级”的预渲染。但我们的架构要求更精细。我们能不能做到“组件级”的预渲染？比如，一个电商页面，商品图片是预渲染的（为了 SEO），但购物车按钮是动态的（因为购物车状态在变）。
这就需要用到 Shadow DOM 或者更高级的 组件级构建策略。
架构升级：构建期生成组件 HTML 片段
我们可以修改一下构建流程。不再生成整个 index.html，而是生成一个 JSON 配置文件，或者直接在 HTML 中内联组件的 HTML 片段。
<!-- index.html -->
<div id="app">
<!-- 商品列表 -->
<div class="product-list">
<div class="product-card">
<h3>React 权威指南</h3>
<img src="/book-cover.jpg" />
<div class="price">$99.00</div>
</div>
<div class="product-card">
<h3>深入浅出 React</h3>
<img src="/book-cover2.jpg" />
<div class="price">$89.00</div>
</div>
</div>
<!-- 动态交互区 -->
<div id="cart-widget"></div>
</div>然后，我们的 React 应用启动后，不会重新渲染整个列表，而是只渲染购物车。
// src/CartWidget.jsx
import React, { useState } from 'react';
const CartWidget = () => {
const [items, setItems] = useState(0);
return (
<div className="cart-widget">
<button onClick={() => setItems(items + 1)}>
加入购物车 ({items})
</button>
</div>
);
};
// 在 main.js 中
const cartContainer = document.getElementById('cart-widget');
if (cartContainer) {
ReactDOM.hydrateRoot(cartContainer, <CartWidget />);
}这种架构极其强大。它允许你：
- 无限滚动：上面的商品列表可以用静态 HTML 直接堆叠（或者用 React 渲染静态部分），不需要每次滚动都请求接口。
- 渐进增强：如果你的浏览器不支持 JS，用户依然能看到商品列表，只是不能点购物车。
第五部分：路由与 SPA 的噩梦
预渲染架构最大的敌人，是 SPA 路由。
如果你是一个纯静态站点，只有 /home 和 /about，那很简单，构建两个 HTML 文件就行了。但如果你有一个复杂的路由系统，比如 /blog/1, /blog/2, /product/123，难道你要为每一个路由生成一个 HTML 文件吗？
答案是：是的，你需要。 这就是所谓的 Multi-page App (MPA) 模式，但是由 React 驱动。
策略一：全量预渲染
使用 react-snap 或 vite-plugin-ssr。它们会模拟浏览器访问每一个路由，生成 HTML。
# react-snap 的典型用法
react-snap这会生成一堆 HTML 文件。你的 Webpack 配置需要把它们复制到 dist 目录，并且配置 historyApiFallback（虽然 HTML 文件本身不需要 fallback，但静态资源可能需要）。
缺点：构建时间变长，文件体积变大。
策略二：按需预渲染 + 客户端路由
这是更高级的玩法。
- 首页：全量预渲染。
- 内容页：只预渲染 SEO 关键的字段（标题、摘要），其余内容动态加载。
- 用户页：完全客户端渲染，因为用户页通常不收录，而且需要登录态。
代码示例（伪代码）：
// 路由配置
const routes = [
{
path: '/',
element: <Home />,
// 首页全量预渲染
prerender: true
},
{
path: '/article/:id',
element: <Article />,
// 文章页只预渲染静态字段
prerender: (params) => fetchStaticArticleData(params.id)
},
{
path: '/dashboard',
element: <Dashboard />,
// 仪表盘不预渲染
prerender: false
}
];在构建阶段，我们编写一个脚本来遍历这些路由配置。如果是 prerender: true，就生成 HTML。如果是 prerender: false，就跳过。
第六部分：性能优化与陷阱
虽然混合渲染架构很香，但如果你玩得不好，就会变成“灾难”。
陷阱 1：DOM 结构不一致导致 Hydration Error
这是最常见的问题。
如果你在构建期生成的 HTML 是：
<p>Hello</p>而在运行时 React 试图渲染：
<p>Hello</p>
<p>World</p>Hydration 就会报错：“Hydration failed because the initial UI does not match the rendered UI”。
解决方法：使用 suppressHydrationWarning 属性，或者确保构建逻辑和运行时逻辑完全一致。对于时间戳、随机数这类内容，必须使用 useEffect 来初始化。
<p suppressHydrationWarning>
{new Date().toLocaleDateString()}
</p>陷阱 2：构建速度
每次修改代码都要重新预渲染所有页面，这会让构建时间翻倍。特别是如果你的页面有几百个。
优化方案：
- 增量构建：只重新渲染修改过的路由。
- SSG (Static Site Generation) + ISR (Incremental Static Regeneration)：这是 Next.js 的高阶玩法。它允许你在不重新构建整个网站的情况下，更新某个页面的静态 HTML。
陷阱 3：SEO 的“幽灵”问题
预渲染虽然解决了首屏问题，但如果你的页面内容是异步加载的（比如从 CMS 获取），而你的构建脚本只渲染了默认状态，那么搜索引擎爬到的可能是一个空页面。
解决方法：
在构建脚本中，必须模拟用户的请求，等待数据加载完成后再生成 HTML。
第七部分：工具链推荐
如果你不想从零开始造轮子，这里有几种现成的方案：
-
Vite + Vite Plugin SSR：
这是最现代的方案。你可以写一个服务端入口，返回 HTML 字符串。// entry-server.js import App from './App.svelte'; // 或者 .jsx import { renderToString } from 'react-dom/server'; export function render() { const html = renderToString(<App />); return `<!DOCTYPE html><div id="app">${html}</div>`; }然后用 Vite 构建这个服务端入口，生成静态文件。
-
Next.js (App Router)：
虽然它是 SSR 框架，但你可以配置generateStaticParams，让它像静态站点一样工作。// app/blog/[id]/page.js export async function generateStaticParams() { // 返回所有文章 ID return [{ id: '1' }, { id: '2' }]; } export default function Page({ params }) { return <div>Article {params.id}</div>; }Next.js 会自动帮你把这几篇文章渲染成静态 HTML 文件。
-
Gatsby：
专门为静态站点生成设计的 React 框架。它基于 GraphQL，构建时会把所有数据拉取下来生成 HTML。
第八部分：总结与展望
各位，今天我们聊了混合渲染架构。
这不仅仅是技术选型的问题，更是一种思维方式的转变。我们不再盲目地追求“全量客户端渲染”的灵活性，也不再盲目地追求“全量服务端渲染”的 SEO。
我们学会了在构建期（Build Time）利用 React 的渲染能力生成静态 HTML，满足搜索引擎和用户的即时需求；然后在运行期（Runtime）利用 React 的 Hydration 机制注入动态交互，满足用户的个性化需求。
这种架构像什么？
它像是一个完美的厨师。
他在你点菜之前，就已经把主菜做好了（静态 HTML）放在保温箱里（CDN）。
当你坐下来，他只需要端上来，然后根据你的口味，加一点点葱花（动态注入）。
但是，技术没有银弹。
这种架构增加了构建的复杂度，增加了维护的成本。你需要同时维护两套逻辑（构建逻辑和运行时逻辑），你需要处理 Hydration 的报错，你需要管理大量的静态文件。
我的建议是：
- 如果你是一个博客、文档站、营销落地页，请务必使用混合渲染架构。这是性价比最高的选择。
- 如果你是一个后台管理系统、或者极度依赖实时数据且对 SEO 要求不高的应用，老老实实用 CSR 吧，别折腾了。
最后，记住今天的核心代码：
// 1. 构建期：生成 HTML
const staticHtml = renderToString(<StaticComponent />);
// 2. 运行期：注入交互
if (document.getElementById('interaction-root')) {
ReactDOM.hydrateRoot(
document.getElementById('interaction-root'),
<DynamicComponent />
);
}希望大家在未来的项目中，能根据业务场景，灵活运用这种“静态骨架，动态灵魂”的混合渲染架构。让我们的网站既快（SEO 友好），又好玩（交互丰富）！
下课！散会！记得把你的 hydrateRoot 包裹在 DOMContentLoaded 事件里，别让你的应用一启动就报错！