Cabloy/Zova 与 Next.js 的 SSR 水合差异

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 更细。所以真正有价值的对比是两条:

  1. Zova 与 Pages Router:同一范式下,工程细节的差距在哪;
  2. 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 的不同位置。

ssrMetaStore.ts 里:

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>;
}

服务端发生的事:

  1. Server Component 在服务端执行,fetch 结果留在服务端;
  2. Client Component 不执行,只是被序列化成一个"占位 + props + chunk 引用";
  3. 两者合起来编成 Flight 协议载荷(RSC Payload);
  4. HTML 由 RSC 渲染结果生成,Client Component 的位置是空容器。

浏览器收到后:

  1. 先渲染 HTML(此时 Client Component 位置是空的或 fallback);
  2. 加载 RSC Payload,React 在根容器上执行一次 hydrateRoot;
  3. 遇到 Client Component 边界才加载对应 chunk 并挂载;
  4. 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);
}

流程是:

  1. 服务端 Controller 加载失败(比如 401、404、跳转);
  2. 把错误的 name / message / code / status / pagePath 序列化成快照,塞进 stateDefer.controllerLoad;
  3. 客户端水合时,走到同一个 Controller,用同样的结构化 key 找到快照;
  4. 直接把错误"重放"出来,而不是重新请求一次。

为什么要重放?因为服务端和客户端的认证状态、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,在"何时知道用了什么"

这里要先把两件事分开,否则很容易得出错误结论:

  1. 模块到输出文件的映射表 ,也就是 quasar.manifest.json。它是构建产物------生产构建生成它,开发构建同样生成它,请求期只读、不会变。
  2. 本次请求实际用到了哪些模块。这是运行期信息,只有把整棵组件树跑完才知道。

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 谁的水合更好"这个问题没有统一答案,取决于你更愿意把复杂度放在框架里还是放在脑子里。


九、小结

  1. Next.js 有两代 SSR 范式:Pages Router 与 Zova 同构(HTML 内嵌状态 + 全树水合),App Router 异构(RSC + 选择性水合)。对比必须先分清这一层。
  2. Zova 的服务端链路是 resolveRoute → serverEntry → renderToString → onRendered → renderTemplate,同步串行,没有流式分片。
  3. 状态走两个通道:__INITIAL_STATE__ 进 head(启动必需),__INITIAL_STATE_DEFER__ 进 body(体积大、可延后)。
  4. 水合靠 data-server-rendered 识别,靠 HydratingCounter 归零收尾,收尾时给水合期间挂起的实例补一次 update()。
  5. 三个 Zova 特有细节值得借鉴:双通道状态的优先级划分、Controller 加载错误的跨端重放、属性不匹配的分类宽容。
  6. 如果要在 Zova 上继续演进,最值得借鉴 App Router 的两点是流式渲染和组件级 JS 裁剪;但两者都需要改造后端响应管线与组件模型,不是小改动。

参考与源码

Zova / Cabloy

Next.js

相关推荐
SoaringHeart1 小时前
Flutter最佳实践:用 flutter_html 渲染富文本
前端·flutter
Flynt2 小时前
Chrome给AI编程助手塞了203篇前端规范,我拆包实测:检索0.77秒是真快,扫描器有点挑食
前端·chrome·ai编程
北城笑笑2 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
程序员韩星3 小时前
OpenAI 兼容接口返回 404,先查请求地址,再查模型名
前端·人工智能·http
Patrick_Wilson3 小时前
构建通过了,为什么有些浏览器还会白屏?
前端·javascript·浏览器
其实防守也摸鱼4 小时前
用 Claude Code 重构遗留系统:从评估到落地的完整指南
前端·网络·人工智能·chrome·安全·重构
七仔啊4 小时前
CNC计算机数控加工模拟器
前端
张一凡934 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
Brookty4 小时前
CSS基础知识(一):选择器、优先级、层叠与继承、边框属性及盒模型
前端·css