Next.js 有过两代 SSR 范式。Zova 与第一代同构,与第二代异构。把它们混为一谈,比较就失去了意义。
聊 SSR 水合时,最常见的问法是"Zova 和 Next.js 有什么不一样"。
这个问题不好直接回答,因为 Next.js 自己就横跨两套完全不同的水合模型:
- Pages Router (
getServerSideProps时代):服务端renderToString→ 把 props 塞进 HTML 的__NEXT_DATA__→ 客户端hydrateRoot。这是 Vue SSR 的同构范式。 - App Router(RSC 时代):服务端渲染 React Server Components,输出 Flight 协议载荷,Client Components 才参与水合。这是另一套东西。
Zova 属于前者,而且做得比 Pages Router 更细。所以真正有价值的对比是两条:
- Zova 与 Pages Router:同一范式下,工程细节的差距在哪;
- Zova 与 App Router:范式不同,各自放弃了什么。
下面从一次真实请求开始。
一、Zova 的一次 SSR 请求
入口在 ssrHandler.ts 的 render()。整条链路是同步串行的:
ts
// 1. 解析路由,确定 SSR Profile
const route = await this.$$sysRouter.resolveRoute(pagePathFull, true, false);
const ssrProfile = resolveSsrProfile(route.meta.ssrProfile, this.sys.env.SSR_PROFILE);
// 2. 创建应用,Controller 在此执行,数据写入 ssrContext
renderFn = await serverEntry(ssrContext);
// 3. 同步渲染整棵组件树
const runtimePageContent = await renderToString(renderFn, ssrContext);
// 4. 回调链:dehydrate query cache、注入 meta、dispose 请求级 Context
onRenderedList.forEach(fn => fn(error));
// 5. 组装最终 HTML
const html = renderTemplate(ssrContext);
三个特征值得注意:
其一,renderToString 是同步的。 Vue 3 的官方服务端渲染 API 只有 renderToString 和 renderToSimpleStream,Zova 用的是前者。这意味着服务端必须等整棵组件树渲染完毕,才能吐出第一个字节。没有 Suspense 分片,没有渐进式传输。
其二,数据不是"请求来的",是 Controller 生产出来的。 在 Zova 里,页面数据来自后端 Controller Bean。服务端渲染时,Controller 直接在后端进程内执行(或者通过 performAction 走内部 HTTP),结果写进 ssrContext.state 与 ssrContext.stateDefer。这和 Next.js 在组件里 await fetch() 是两种取数路径。
其三,请求级状态必须显式销毁。 Zova 的 Bean 是单例的,请求级的东西挂在 ZovaContext 上。所以 ssr.ts 里维护了一个 SymbolServerContexts 集合,每个请求注册进来,渲染完统一 dispose:
ts
private _serverContextsDispose() {
for (const serverContext of this[SymbolServerContexts]) {
if (serverContext.disposed) continue;
if (serverContext.bean && serverContext.bean !== serverContext.app?.bean) {
serverContext.bean.dispose();
}
serverContext.dispose();
}
serverContexts.clear();
}
这一点在 Next.js 里不存在------App Router 的每个请求天然是独立执行环境,Pages Router 也是每次请求走一遍函数,没有跨请求的单例状态需要手动清理。
二、状态怎么进 HTML
Zova 用了两个通道,分别注入到 HTML 的不同位置。
ts
// 关键状态 → head 末尾
ctx.endingHeadTags += `<script id="ssr-state-init">window.__INITIAL_STATE__=${unevalPatch(ssrContext.state)}</script>`;
// 非关键但体积大的状态 → body 末尾
ctx.endingBodyTags += `<script id="ssr-state-defer-init">window.__INITIAL_STATE_DEFER__=${unevalPatch(ssrContext.stateDefer)}</script>`;
两个通道装的东西不一样:
| 通道 | 位置 | 内容 | 特点 |
|---|---|---|---|
__INITIAL_STATE__ |
head 末尾 | pagePathFull、ssrProfile、ssrProfileOptions、compactHint |
应用启动就需要,体积小 |
__INITIAL_STATE_DEFER__ |
body 末尾 | TanStack Query 的 dehydrate 结果、Controller 加载错误快照、meta |
体积大,可延后解析 |
这么拆的理由很直接:head 里的内联脚本会阻塞后续解析。把 query cache 这种动辄几十 KB 的数据放到 body 末尾,首屏能早一点开始。
反过来,pagePathFull 必须早拿到------客户端要靠它把路由对齐到服务端渲染的那一页,否则会先渲染一个空路由再跳转,造成闪屏。
客户端恢复在 sys.ssrState.ts:
ts
protected async __init__() {
if (process.env.CLIENT) {
if (cast(window).__INITIAL_STATE__) {
this[SymbolSSRState] = cast(window).__INITIAL_STATE__;
delete cast(window).__INITIAL_STATE__;
document.getElementById('ssr-state-init')?.remove();
}
// stateDefer 同理
}
}
拿到后立刻 delete 全局变量、移除 script 节点。这两步都是为了让这份状态只被消费一次,同时释放内存。
三、水合是怎么被识别和收尾的
Zova 没有 hydrateRoot 这样的显式调用。它依赖一个 DOM 信号:
ts
// ssr.ts initialize()
} else if (process.env.CLIENT && document.body.getAttribute('data-server-rendered') !== null) {
this[SymbolIsRuntimeSsrPreHydration].value = true;
}
data-server-rendered 这个属性,是服务端在 _initContext() 里通过默认 bodyAttrs 写进 <body> 的:
ts
ssrContext._meta = defu(ssrContext._meta, {
bodyAttrs: 'data-server-rendered',
// ...
});
于是客户端一启动就能判断:我是"接着 SSR 的 DOM 继续",还是"从零挂载"。
Vue 3 的 createSSRApp().mount() 本身会走 hydrate 路径,所以不需要 Zova 手动选 API。但 Zova 还需要知道水合什么时候结束------因为很多逻辑(比如那些只能在浏览器稳定后执行的初始化)要等到那一刻。
它用的办法是计数器:
ts
public _hydratingRootInc() { if (process.env.CLIENT && this.isRuntimeSsrPreHydration) this._hydratingInc(); }
public _hydratingRootDec() { if (process.env.CLIENT && this.isRuntimeSsrPreHydration) this._hydratingDec(); }
public _hydratingDec() {
if (--this[SymbolHydratingCounter] === 0) {
this._hydrated();
}
}
根组件挂载 +1、卸载 -1,归零即完成。_hydrated() 做三件事:
ts
private _hydrated() {
if (!this.isRuntimeSsrPreHydration) return;
this.isRuntimeSsrPreHydration = false; // 先把标志翻掉
// 让水合期间挂起的组件补一次更新
this[SymbolInstanceUpdates].forEach(instance => {
if (!instance.isUnmounted && instance.zova) {
try { instance.update(); }
catch (err) { if (!err.message.includes("'insertBefore'")) throw err; }
}
});
this[SymbolOnHydrateds].forEach(fn => fn());
}
中间那段"补一次更新"是关键。水合期间,组件自身的响应式数据可能已经变了,但 Vue 为了对齐服务端 DOM 会推迟渲染。水合结束后统一 update() 一次,页面才真正进入运行时状态。'insertBefore' 的异常捕获是因为 DOM 结构在水合后可能已与旧 vnode 不完全对应,这个错误无害。
在这之上,Zova 提供了两个回调 API:
ts
onHydrated(fn) // 只在首次 SSR 水合后执行
handleDirectOrOnHydrated(fn) // 水合中则排队,否则立即执行
第二个是给通用逻辑用的。同一段代码在 SSR 场景下要等水合完成,在纯 SPA 场景下要立刻跑,用这个包装就能自动适配。
顺带一提,水合完成后会在 <html> 上打一个标记:
ts
document.documentElement.setAttribute('data-zova-hydrated', this.sys.env.SITE_ID);
它是给外部监控和端到端测试用的------判断"这一页是否真的完成了水合"。
四、对照 Pages Router:同一范式
现在把 Next.js Pages Router 摆过来。它的链路是:
ts
// 服务端
export async function getServerSideProps(ctx) {
return { props: { data: await loadData(ctx) } };
}
// 框架生成
<script id="__NEXT_DATA__" type="application/json">{...}</script>
// 客户端
hydrateRoot(document.getElementById('__next'), <App {...pageProps} />);
和 Zova 对比,结构级一致:
| 环节 | Zova | Next.js Pages Router |
|---|---|---|
| 服务端渲染 | renderToString |
renderToString / renderToPipeableStream |
| 状态注入 | window.__INITIAL_STATE__ + __INITIAL_STATE_DEFER__ |
<script id="__NEXT_DATA__"> |
| 序列化 | unevalPatch → JS 字面量,直接赋值 |
JSON,JSON.parse |
| 水合触发 | <body data-server-rendered> 自动判断 |
框架固定调用 hydrateRoot |
| 取数位置 | Controller Bean | getServerSideProps |
| 组件边界 | 无,全树水合 | 无,全树水合 |
差异只在工程细节:
- Zova 把状态拆成两通道 ,Pages Router 只有一个
__NEXT_DATA__; - Zova 用 DOM 属性判断是否水合,Pages Router 是框架写死的,不存在"这个页面要不要水合"的运行时分支;
- Zova 有
onHydrated生命周期 ,Pages Router 只能靠useEffect在组件里凑; - Zova 的取数走 Controller ,天然带认证、权限、参数校验;Pages Router 的
getServerSideProps是裸函数。
所以在这个范式里,Zova 的位置更接近"把 Pages Router 的每个薄弱点都补了一遍",而不是"另一种做法"。
五、对照 App Router:不同范式
App Router 的水合是另一回事。关键在 'use client' 这个指令:
tsx
// app/page.tsx ------ 默认是 Server Component,不发送 JS
export default async function Page() {
const data = await fetch('https://api.example.com/data');
return <Counter initial={data.count} />;
}
// app/counter.tsx ------ 显式声明为 Client Component
'use client';
export function Counter({ initial }) {
const [n, setN] = useState(initial);
return <button onClick={() => setN(n + 1)}>{n}</button>;
}
服务端发生的事:
- Server Component 在服务端执行,
fetch结果留在服务端; - Client Component 不执行,只是被序列化成一个"占位 + props + chunk 引用";
- 两者合起来编成 Flight 协议载荷(RSC Payload);
- HTML 由 RSC 渲染结果生成,Client Component 的位置是空容器。
浏览器收到后:
- 先渲染 HTML(此时 Client Component 位置是空的或 fallback);
- 加载 RSC Payload,React 在根容器上执行一次
hydrateRoot; - 遇到 Client Component 边界才加载对应 chunk 并挂载;
- Server Component 的输出保持静态,永不参与水合。
对照 Zova:
| 维度 | Zova | Next.js App Router |
|---|---|---|
| 是否需要水合的组件 | 全部 | 仅 Client Components |
| 发送的 JS | 全部组件代码 | 仅 Client Components |
| 数据传输 | 自定义 state 对象 | Flight 协议载荷 |
| 渲染 API | renderToString(同步) |
renderToReadableStream(流式) |
| 首字节时机 | 全树渲染完 | 按 Suspense 边界分片 |
| 错误隔离 | 一错全页 500 | 边界内 fallback |
| 数据获取 | Controller Bean | Server Component 内直接 fetch |
| 水合不匹配面 | 全组件树 | 仅 Client Components |
本质差别是一句话:App Router 从组件源头就切断了水合需求,Zova 则是整棵树都要水合。
代价也不一样。App Router 换来了极小的首屏 JS 和流式渐进显示,代价是开发者必须理解 Server / Client 边界:useState 只能在 Client Component 里用,Server Component 不能有事件处理器,跨边界传值必须可序列化,Server Actions 又是另一套心智模型。
Zova 换来了"一个组件双端运行",任何 SFC 都能直接写 ref、onMounted、$useState,不用想边界。代价是首屏 JS 包含全部组件代码,且整棵树都承担 mismatch 风险。
六、Zova 特有的三个细节
1. 双通道状态,是为了让首屏早开始
前面提过,这里补一句设计判断。__INITIAL_STATE__ 里只放启动必需的几个字段,query cache 走 defer 通道。这个拆法在 Pages Router 里没有对应物------Next.js 把所有 props 都塞进一个 __NEXT_DATA__,大页面的初始状态会拖慢 head 解析。
Zova 的做法本质上是在"关键渲染路径"和"非关键数据"之间做了一次手动的优先级划分。
2. Controller 加载错误会被"重放"
这是 Zova 最有意思的一处,ssr.ts 的 controllerLoad:
ts
public controllerLoad(event: IControllerLoadEvent) {
if (event.phase === 'prepare') {
if (process.env.SERVER) {
event.ctx.meta.state.controllerLoadKey = this._allocateControllerLoadKey(event);
return;
}
// 客户端水合阶段
const key = this._allocateControllerLoadKey(event);
const snapshot = this.stateDefer.controllerLoad?.[key];
if (!snapshot || snapshot.controllerBeanName !== event.controllerBeanName) return;
delete this.stateDefer.controllerLoad![key];
event.replayError = _createControllerLoadError(snapshot);
event.replayControllerRecorded = snapshot.controllerRecorded;
return;
}
// 服务端:把错误存成快照
if (event.phase !== 'fallback' || !process.env.SERVER || !event.error) return;
const key = event.ctx.meta.state.controllerLoadKey;
if (!key) return;
(this.stateDefer.controllerLoad ??= {})[key] = _createControllerLoadErrorSnapshot(event);
}
流程是:
- 服务端 Controller 加载失败(比如 401、404、跳转);
- 把错误的
name / message / code / status / pagePath序列化成快照,塞进stateDefer.controllerLoad; - 客户端水合时,走到同一个 Controller,用同样的结构化 key 找到快照;
- 直接把错误"重放"出来,而不是重新请求一次。
为什么要重放?因为服务端和客户端的认证状态、cookie 可用性、请求上下文可能不同。如果客户端重新请求,很可能得到一个不同结果------服务端跳登录,客户端却拿到了数据,水合就崩了。重放保证了两端对同一个 Controller 的加载结果完全一致。
key 的生成也值得看一眼,它拼接了从根到当前的组件路径、vnode key、同名出现次序:
ts
const parts: string[] = [];
let current: ComponentInternalInstance | null = instance;
while (current) {
const name = current.type.__file ?? current.type.name ?? current.type.__name ?? 'anonymous';
parts.unshift(`${name}:${String(current.vnode.key ?? '')}`);
current = current.parent;
}
const structuralKey = parts.join('/');
const occurrence = this._controllerLoadSequence[structuralKey] ?? 0;
this._controllerLoadSequence[structuralKey] = occurrence + 1;
return `${structuralKey}#${occurrence}:${event.controllerBeanName ?? ''}`;
这是为了区分"同一个 Controller 在页面里出现多次"的情况------每个实例各拿各的错误。
Next.js 没有对应机制。App Router 的 fetch 失败会直接编码进 RSC Payload,由 error boundary 接住;Pages Router 的 getServerSideProps 抛错就直接 500。都不存在"跨端重放同一个失败"的需求,因为它们的取数只发生在服务端。
3. 属性不匹配是宽容的
Vue 的水合默认会因为属性差异报错。Zova 加了一层默认宽容策略:
ts
private _onHydratePropHasMismatchDefault(el, key, clientValue, _vnode, _instance) {
let ignore = false;
if (key === 'class') {
ignore = true;
if (clientValue !== undefined) {
el.setAttribute('class', normalizeClass(clientValue));
}
} else if (key === 'style') {
// 同理,用客户端值覆盖
} else if (['id', 'name', 'for', 'd', 'aria-labelledby', 'aria-controls'].includes(key)) {
// 直接覆盖
} else if (key === 'value') {
// textarea 走 .value,其他走 setAttribute
} else if (isBooleanAttr(key)) {
// 布尔属性按存在/不存在处理
} else if (el.getAttribute(`data-hydrate-ignore-${key}`) !== null) {
// 开发者手动标记忽略
}
return ignore ? { ignore: true } : { clientValue };
}
覆盖的属性集是有讲究的:
class/style:服务端和客户端可能因为动画、主题、响应式断点算出不同结果,这不该算错;id/name/for/d/aria-*:这些常见于自动生成 ID、SVG 路径、无障碍关联,两端略有差异不影响功能;value:输入框的值用户可能已经改过,水合时不该被服务端值覆盖;- 布尔属性:
disabled、checked这类,用"存在与否"语义处理更稳。
还留了一个手动逃生口:data-hydrate-ignore-${key}。给某个元素加上 data-hydrate-ignore-title,这个属性在水合时就不会报错,直接用客户端值。
这套策略的价值在于把"合理的差异"和"真正的 bug"分开。默认放过前者,让开发者能注意到后者。
七、资源预加载:差异不在 manifest,在"何时知道用了什么"
这里要先把两件事分开,否则很容易得出错误结论:
- 模块到输出文件的映射表 ,也就是
quasar.manifest.json。它是构建产物------生产构建生成它,开发构建同样生成它,请求期只读、不会变。 - 本次请求实际用到了哪些模块。这是运行期信息,只有把整棵组件树跑完才知道。
Zova 的做法是先用第 2 项筛出集合,再用第 1 项查表:
ts
// ssrHandler.ts
const modules = cast(ssrContext).modules;
if (modules) {
ssrContext._meta.endingHeadTags += this._renderModulesPreload_zova(modules, { ssrContext });
ssrContext._meta.endingHeadTags += this._renderModulesPreload(modules, { ssrContext });
}
而且第 2 项的收集是生产环境专属 的,a-ssr/src/monkey.ts 的 moduleLoaded 写着:
ts
async moduleLoaded(module: IModule) {
// ssrContext.modules
if (process.env.SERVER && process.env.PROD) {
if (!this.ctx.meta.$ssr.context.modules) this.ctx.meta.$ssr.context.modules = new Set();
this.ctx.meta.$ssr.context.modules.add(`@@${module.info.relativeName}`);
}
}
所以在开发阶段,Zova 模块的 modulepreload 根本不会生成,而不是"渲染后才生成"。
manifest 的结构也印证了它是构建产物:键是源模块路径或带哈希的输出文件名,值是该文件的依赖文件列表。例如:
json
{
".quasar/prod-ssr/client-entry.js": ["/assets/index-xxxx.js"],
"a-api-DvAtaMhL.js": ["/assets/wrapAsyncGenerator-DhsawSOn.js"]
}
Zova 拿 @@a-api 反查前缀为 a-api-、后缀为 .js 的键,命中后把结果缓存进 _ssrModulesZovaCache------一个进程级、永不失效的缓存:
ts
const prefix = `${id.substring(2)}-`;
const postfix = '.js';
for (const key in this._clientManifest) {
if (key.startsWith(prefix) && key.endsWith(postfix)) {
cache = this._resolveUrlPath(`/assets/${key}`);
break;
}
}
注意这里做的是"遍历 manifest 做前缀匹配 ",因为 manifest 的方向是"文件 → 依赖",不是"模块 → 文件",所以需要反查。命中后再按扩展名分派标签类型:js 走 modulepreload,css 走 stylesheet,字体和图片走 preload。
所以真正的差异不在 manifest 的生成时机------两边都是构建期。差异在于:
"这一页需要哪些 chunk",能不能在渲染之前静态确定。
App Router 能。路由段与 chunk 的对应关系在构建产物里是静态的,服务端在渲染前就知道该预加载什么;配合 RSC Payload 里嵌入的 chunk 引用,浏览器甚至能在用户悬停 <Link> 时就提前取。
Zova 不能。因为 Zova 的模块是运行期按需装载的------路由走到哪里,app.meta.module.use(relativeName) 才把哪个模块加载进来。所以"这一页命中哪些模块"取决于 Controller 的加载路径和组件树的实际展开,只能等渲染结束才知道。
换句话说:映射是静态的,命中是动态的。 前置的静态映射并不足以让预加载提前,真正决定时机的是"页面与 chunk 的绑定能否在渲染前求解"。
Pages Router 介于两者之间------有构建产物,但预加载主要靠 next/link 和 <Head>,不像 App Router 那样深度集成。
八、取舍
把两边放到一张表里,看清各自放弃了什么:
| Zova | Next.js Pages Router | Next.js App Router | |
|---|---|---|---|
| 组件心智 | 一个组件双端运行 | 同左 | 必须区分 Server / Client |
| 首屏 JS | 全组件树 | 全组件树 | 仅 Client Components |
| TTFB | 全树渲染完 | 可流式 | 可流式 + 分片 |
| 状态注入 | 双通道 | 单通道 | Flight Payload |
| 取数 | Controller Bean(带完整后端能力) | getServerSideProps(裸函数) |
组件内 fetch(带缓存语义) |
| 水合生命周期 | onHydrated / handleDirectOrOnHydrated |
无,靠 useEffect |
无,靠 useEffect |
| 水合前状态一致性 | 错误快照重放 | 不保证 | 由 RSC Payload 保证 |
| 缓存粒度 | public / session 两档 | 页面级 | 路由段 + fetch + tag |
| 迁移成本 | --- | 低(同构) | 高(范式切换) |
三个判断:
Zova 选择了"完整应用双端运行",把所有复杂度留在框架内部(双通道、错误重放、属性宽容、Context 生命周期),对开发者隐藏。这是一个"框架多做一点,开发者少想一点"的选择。
Pages Router 是同一个选择的不同实现,但细节打磨少一些。它的历史价值在于证明了"HTML 内嵌初始状态 + hydrateRoot"这条路足够用很多年。
App Router 是范式切换。它承认了"全量水合"的成本,用组件边界换取首屏性能。代价是把复杂度推给了开发者------每个组件都要想清楚"这段代码在哪运行"。
所以"Zova 和 Next.js 谁的水合更好"这个问题没有统一答案,取决于你更愿意把复杂度放在框架里还是放在脑子里。
九、小结
- Next.js 有两代 SSR 范式:Pages Router 与 Zova 同构(HTML 内嵌状态 + 全树水合),App Router 异构(RSC + 选择性水合)。对比必须先分清这一层。
- Zova 的服务端链路是
resolveRoute → serverEntry → renderToString → onRendered → renderTemplate,同步串行,没有流式分片。 - 状态走两个通道:
__INITIAL_STATE__进 head(启动必需),__INITIAL_STATE_DEFER__进 body(体积大、可延后)。 - 水合靠
data-server-rendered识别,靠HydratingCounter归零收尾,收尾时给水合期间挂起的实例补一次update()。 - 三个 Zova 特有细节值得借鉴:双通道状态的优先级划分、Controller 加载错误的跨端重放、属性不匹配的分类宽容。
- 如果要在 Zova 上继续演进,最值得借鉴 App Router 的两点是流式渲染和组件级 JS 裁剪;但两者都需要改造后端响应管线与组件模型,不是小改动。
参考与源码
Zova / Cabloy
- SSR 上下文与水合生命周期
- SSR 状态恢复
- 状态注入与 meta 管理
- SSR 渲染服务
- Query 缓存 dehydrate / hydrate
- 路由在服务端与客户端之间的对齐
- SSR 模块装配与 hydrated 钩子