1. 范围与术语
本文针对“服务端渲染 HTML,浏览器下载脚本后水合”这一类 Web 应用,说明一次页面导航的时间构成、各阶段可用的优化手段、每种手段的实现方式与约束,以及验证方法。
| 术语 | 定义 |
|---|---|
| CSR | Client-Side Rendering。服务端返回不含内容的 HTML,由浏览器执行脚本生成 DOM。 |
| SSR | Server-Side Rendering。服务端执行组件并输出含内容的 HTML。 |
| 水合(Hydration) | 浏览器在服务端输出的 DOM 上重新执行组件,绑定事件并接管状态,不重建 DOM。 |
| 流式 SSR | 服务端分块输出 HTML,先输出已就绪的部分,其余部分就绪后追加。 |
| 关键请求链 | 首屏渲染所依赖的、必须按顺序完成的一组请求。 |
| 渲染阻塞资源 | 未加载完成前浏览器不会进行首次绘制的资源,主要是 <head> 中的同步样式表和同步脚本。 |
| 长任务(Long Task) | 在主线程上连续执行超过 50ms 的任务。 |
2. 时间模型
2.1 导航的阶段划分
W3C Navigation Timing Level 2 将一次导航划分为若干连续阶段,并在阶段边界上定义时间戳。所有时间戳以 startTime(恒为 0)为原点,单位毫秒。
点击任一阶段查看它的起止属性和含义。
Service Worker 的两个阶段在规范中只有 workerStart 和 fetchStart 两个时间戳,无法分别计时。firstInterimResponseStart 是较新的属性,仅部分 Chromium 版本提供。
2.2 派生区间
实际分析时使用的是时间戳之间的差值。
| 区间 | 计算方式 | 含义 |
|---|---|---|
| 重定向耗时 | redirectEnd - redirectStart | 重定向链 |
| Service Worker 耗时 | fetchStart - workerStart | 启动与 fetch 事件处理,仅 workerStart > 0 时有效 |
| DNS | domainLookupEnd - domainLookupStart | 域名解析 |
| 建连 | connectEnd - connectStart | TCP 与 TLS |
| TLS | connectEnd - secureConnectionStart | 仅 HTTPS |
| 请求等待 | responseStart - requestStart | 上行传输、服务端处理、首字节下行 |
| TTFB | responseStart - startTime | 包含上述全部阶段,不只是服务端耗时 |
| 响应传输 | responseEnd - responseStart | HTML 下载 |
| DOM 解析 | domInteractive - responseEnd | 解析至文档可交互 |
| DOMContentLoaded 处理 | domContentLoadedEventEnd - domContentLoadedEventStart | 该事件处理函数的执行 |
| 子资源与脚本 | domComplete - domInteractive | 剩余子资源加载与执行 |
TTFB 常被当作“服务端耗时”,这是不准确的。它以 startTime 为起点,重定向、Service Worker 启动、DNS、建连都计入其中。判断服务端耗时应使用 responseStart - requestStart,并结合 2.4 节的服务端计时。
2.3 模型未覆盖的两个区域
服务端内部。 requestStart 到 responseStart 对浏览器是不透明的。数据获取、组件渲染、序列化各自占多少,时间模型不提供。
加载完成之后。 loadEventEnd 只表示 load 事件处理完毕,不反映用户何时看到内容、何时可以操作。这部分由以下指标描述:
| 指标 | 定义 | 良好阈值(第 75 百分位) |
|---|---|---|
| FCP | First Contentful Paint,首次绘制出文本或图像的时间 | ≤ 1.8s |
| LCP | Largest Contentful Paint,视口内最大内容元素完成绘制的时间 | ≤ 2.5s |
| CLS | Cumulative Layout Shift,非预期布局偏移的累计得分 | ≤ 0.1 |
| INP | Interaction to Next Paint,交互到下一帧绘制的延迟 | ≤ 200ms |
| TTFB | 见 2.2 | ≤ 0.8s |
2.4 采集方式
const [nav] = performance.getEntriesByType('navigation');
const metrics = {
redirect: nav.redirectEnd - nav.redirectStart,
serviceWorker: nav.workerStart > 0 ? nav.fetchStart - nav.workerStart : 0,
dns: nav.domainLookupEnd - nav.domainLookupStart,
connect: nav.connectEnd - nav.connectStart,
requestWait: nav.responseStart - nav.requestStart,
ttfb: nav.responseStart,
download: nav.responseEnd - nav.responseStart,
domInteractive: nav.domInteractive,
domComplete: nav.domComplete,
};new PerformanceObserver((list) => {
const entries = list.getEntries();
report('lcp', entries[entries.length - 1].startTime);
}).observe({ type: 'largest-contentful-paint', buffered: true });
let cls = 0;
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (!entry.hadRecentInput) cls += entry.value;
}
}).observe({ type: 'layout-shift', buffered: true });
new PerformanceObserver((list) => {
for (const entry of list.getEntries()) report('long-task', entry.duration);
}).observe({ type: 'longtask', buffered: true });HTTP/1.1 200 OK
Server-Timing: route;dur=4.1, data;dur=312.6, render;dur=148.0const [nav] = performance.getEntriesByType('navigation');
for (const { name, duration } of nav.serverTiming) report(name, duration);Server-Timing 是打开服务端黑盒的标准方式,但它是响应头,必须在响应体之前发出。采用流式 SSR 时,响应头发出的时刻渲染尚未结束,后续阶段的耗时无法写入。这种情况下服务端应自行上报指标,至少区分两个时刻:外壳就绪(shell ready)和全部就绪(all ready)。
3. 分阶段优化
以下每一节采用相同的结构:阶段构成、典型问题、手段、实现、约束、验证指标。
3.1 Redirect
| 项 | 内容 |
|---|---|
| 构成 | 每一跳重定向包含一次完整的 DNS、建连、请求往返 |
| 典型问题 | 页面加载并执行脚本后才判定需要跳转,等于完整加载了一次无用页面 |
| 手段 | 在服务端处理导航请求的最早阶段判定并返回 3xx |
| 约束 | 判定所需的信息必须在服务端可得 |
| 验证 | redirectEnd - redirectStart;客户端跳转的发生率 |
const target = await resolveRedirect(req);
if (target) return res.redirect(302, target);重定向判定应与其他前置工作并发发起,并最先消费其结果,见 3.4.1。
3.2 Service Worker 与 HTTP Cache
| 项 | 内容 |
|---|---|
| 构成 | Service Worker 线程启动;fetch 事件处理;HTTP 缓存查询 |
| 典型问题 | Service Worker 冷启动耗时计入每一次导航;在它响应之前导航请求不会发出 |
| 手段 | 启用 Navigation Preload,使导航请求与 Service Worker 启动并行;为离线或弱网场景缓存一份不含数据的应用外壳 |
| 约束 | 外壳只能包含与用户、与请求无关的内容;缓存的外壳需要随版本失效 |
| 验证 | fetchStart - workerStart;transferSize === 0 的导航占比(缓存命中) |
self.addEventListener('activate', (event) => {
event.waitUntil(self.registration.navigationPreload?.enable());
});
self.addEventListener('fetch', (event) => {
if (event.request.mode !== 'navigate') return;
event.respondWith((async () => {
const preloaded = await event.preloadResponse;
return preloaded ?? fetch(event.request);
})());
});// 供 Service Worker 预缓存,不执行任何渲染
if (req.query.shell === '1') return res.send(emptyShell);3.3 DNS 与建连
这两个阶段主要由基础设施决定,应用层能做的有限:
- 首屏所需的第三方源使用
<link rel="preconnect">,数量控制在个位数,每个连接都有成本。 - 首屏资源尽量收敛到少数几个源,以复用连接。
- 使用 HTTP/2 或 HTTP/3,避免为并行下载而分域。
验证:connectEnd - connectStart,以及子资源的 Resource Timing 中建连耗时为 0 的比例。
3.4 Request(服务端处理)
该阶段通常是首屏耗时中最大的一段,也是应用层可控程度最高的一段。
3.4.1 前置工作并发
问题。 请求进入后的前置工作(重定向判定、路由匹配、文案或配置加载)彼此没有数据依赖,却因顺序 await 而串行。
实现。
const redirect = await resolveRedirect(req);
const texts = await loadTexts(lang);
const route = await matchRoute(req.path);
// 耗时 = 三者之和const redirectP = resolveRedirect(req);
const textsP = loadTexts(lang).catch(logAndIgnore);
const routeP = matchRoute(req.path);
const redirect = await redirectP; // 可能提前终止请求,最先消费
if (redirect) return res.redirect(302, redirect);
const [, route] = await Promise.all([textsP, routeP]);
// 耗时 = 三者中的最大值约束。 并发发起的 Promise 必须各自处理拒绝,否则提前返回时会留下未处理的 rejection。
3.4.2 数据获取的时间预算
问题。 SSR 的首字节时间受最慢的那个数据请求约束。接口的尾部延迟(P99)会直接成为页面的白屏时间。
手段。 为服务端的数据获取设置上限。超过上限时以空数据完成渲染,并在序列化的数据中标记超时;浏览器水合后检测到标记,重新请求,此时不再设限。
async function withBudget(promise, budgetMs) {
if (!IS_SERVER || budgetMs <= 0) return promise;
return Promise.race([
promise,
new Promise((resolve) => setTimeout(() => resolve({ timedOut: true }), budgetMs)),
]);
}
const result = await withBudget(fetchItems(params), config.fetchBudgetMs);const query = useQuery({ queryKey, queryFn });
useEffect(() => {
if (query.data?.timedOut) query.refetch();
}, []);代价。 设接口耗时为 t,上限为 b。当 t > b 时:
- 页面首字节提前
t - b。 - 该区块的内容完整时间变为约
b + 水合前耗时 + t,晚于不设上限的情况。 - 该区块从占位变为内容,若占位高度不一致会计入 CLS。
因此 b 应取在接口延迟分布的高分位附近(例如 P95),使超时成为少数情况。
约束。
- 输出给不执行脚本的消费方(见第 4 节)时必须关闭,否则该区块永久缺失。
- 离线预生成 HTML 时必须关闭,此时没有用户在等待。
- 上限值应来自运行时配置,未配置时视为关闭。
Promise.race不会取消落败的请求。需要释放连接时应配合AbortController。
配套。 服务端首屏请求的分页大小可以单独配置,只取首屏可见的条数,其余由浏览器分页获取。
3.4.3 流式输出
问题。 传统 SSR 在全部渲染完成后才发出响应。在此之前浏览器没有任何字节可处理,无法开始加载样式和脚本。
手段。 先输出不依赖数据的文档头部,再输出渲染结果。
res.setHeader('Content-Type', 'text/html; charset=utf-8');
res.write(documentHead); // 含样式、脚本的资源声明
const { pipe } = renderToPipeableStream(app, {
onShellReady() { pipe(res); }, // 外壳就绪即输出,Suspense 内的内容后续追加
onShellError(error) { res.end(fallbackHtml); },
onError(error) { log(error); },
});效果。 responseStart 提前到头部写出的时刻;浏览器的预加载扫描器在数据获取期间即可发现并下载资源。responseEnd 不变或略晚。
约束。
- 首个字节写出后,状态码和响应头不可更改。在此之后才能判定的 404 或重定向需要另行处理,例如输出一段执行客户端跳转的脚本,或者将判定前移到写出之前。
- 中间层(反向代理、压缩)若启用了缓冲,分块会被合并,流式失效。
Server-Timing无法包含头部写出之后的耗时,见 2.4。- 因以上约束,建议按页面启用,而非全局默认。
3.4.4 预生成
对内容与用户无关的页面,可以离线完成渲染并缓存整份 HTML,请求到达时直接返回。
renderToPipeableStream(app, {
onAllReady() { pipe(collector); }, // 等全部内容就绪,不流式
});约束:预生成的 HTML 不得包含用户相关数据;用户相关的区块在水合后由浏览器获取。预生成路径上 3.4.2 的时间预算应关闭。
3.5 Early Hints(可选)
HTTP 103 允许服务端在最终响应之前发送一组 Link 头,使浏览器提前建立连接或预加载资源。它解决的问题与 3.4.3 相同(让浏览器在服务端处理期间有事可做),但作用在 HTTP 层,不要求应用支持流式渲染。
HTTP/1.1 103 Early Hints
Link: </static/page.css>; rel=preload; as=style
Link: </static/page.js>; rel=preload; as=script约束:需要 HTTP/2 或 HTTP/3,并且链路上的每一层代理都支持透传 103。验证:firstInterimResponseStart。
3.6 Response(HTML 体积)
HTML 的字节数同时影响传输时间和解析时间。SSR 应用的 HTML 由三部分构成:标记、内联样式、序列化的状态。
3.6.1 选择性服务端渲染
并非所有组件都需要出现在服务端输出中。按内容性质分为三级:
| 级别 | 服务端输出 | 适用内容 |
|---|---|---|
| 始终渲染 | 完整标记 | 首屏可见内容 |
| 首屏模式下跳过 | 占位 | 首屏以下的内容区块 |
| 仅浏览器渲染 | 占位 | 纯交互组件;依赖浏览器环境或设备信息的组件 |
function ClientOnly({ children, fallback = null }) {
const [mounted, setMounted] = useState(false);
useEffect(() => setMounted(true), []);
return mounted ? children : fallback;
}useEffect 不在服务端执行,因此服务端始终输出 fallback;浏览器首次渲染同样输出 fallback,与服务端一致,不产生水合不匹配,随后在 effect 中切换为真实内容。
约束:
fallback应与真实内容尺寸一致,否则内容出现时产生布局偏移,计入 CLS。- 被跳过的内容不在 HTML 中,对不执行脚本的消费方不可见。面向这类消费方的产物不应跳过内容区块,见第 4 节。
- 服务端依据请求头推断设备类型并不可靠。依赖设备类型的组件宜归入“仅浏览器渲染”。
3.6.2 状态序列化
SSR 需要将服务端获取的数据传给浏览器,否则浏览器水合时会重新请求,并可能因两次结果不同而导致水合不匹配。
function serialize(key, data) {
const json = JSON.stringify(data).replace(/</g, '\\u003c');
return `<script type="application/json" data-key="${key}">${json}</script>`;
}function readInitialData(key) {
const node = document.querySelector(`script[type="application/json"][data-key="${key}"]`);
if (!node) return undefined;
try { return JSON.parse(node.textContent); } catch { return undefined; }
}
function clearInitialData(key) {
document.querySelector(`script[type="application/json"][data-key="${key}"]`)?.remove();
}要点:
- 转义。 JSON 中的
<必须转义为<,否则数据中的</script>会提前结束标签,构成注入风险。 - 使用非可执行类型。
type="application/json"的脚本块不会被执行,解析成本低于等价的 JavaScript 对象字面量。 - 按模块分键。 各模块独立读写,互不依赖对方的数据结构。
- 裁剪。 写出前移除浏览器不需要的字段。状态体积直接计入 HTML 体积。
- 读取后清除。 这份数据只对首次渲染有效,保留会占用内存,并可能在后续导航中被误读为当前数据。
- 读取失败不视为错误。 返回
undefined,由调用方回退到正常请求。
3.7 Processing
3.7.1 资源发现
问题。 浏览器的预加载扫描器只能发现 HTML 标记中声明的资源。由脚本在运行时动态加载的代码块,要等到其父脚本下载并执行到相应位置后才会被请求,形成串行的请求链。
手段。 服务端在渲染过程中记录实际用到的代码块,在输出中直接声明。
const AssetContext = createContext({ chunks: new Set() });
function lazyWithChunk(loader, chunkName) {
const Component = lazy(loader);
return function Wrapped(props) {
useContext(AssetContext).chunks.add(chunkName);
return <Suspense fallback={null}><Component {...props} /></Suspense>;
};
}const assets = { chunks: new Set() };
const html = await render(<AssetContext.Provider value={assets}><App /></AssetContext.Provider>);
const tags = [...assets.chunks].flatMap((name) => [
...manifest[name].css.map((href) => `<link rel="stylesheet" href="${href}">`),
...manifest[name].js.map((href) => `<link rel="preload" as="script" href="${href}">`),
]);三种声明方式的语义不同:
| 方式 | 浏览器行为 | 适用 |
|---|---|---|
内联 <style> | 无额外请求,随 HTML 到达即可用 | 首屏关键样式 |
rel="preload" | 以高优先级立即下载,用于当前导航 | 首屏必需的脚本、字体 |
rel="prefetch" | 空闲时以最低优先级下载 | 首屏之后才需要的代码块 |
约束:
- 内联样式不能被独立缓存,并增大 HTML。只内联首屏关键样式。
preload的资源若在数秒内未被使用,浏览器会给出警告,同时它挤占了其他资源的带宽。- 登记与输出必须成对实现。只有登记而没有输出时不产生任何效果,且不会报错,见第 6 节。
- 流式 SSR 下,外壳之后才渲染的组件所登记的代码块,需要随后续分块一并输出。
3.7.2 水合
入口。 根据容器内是否已有服务端输出,选择水合或全新渲染,使同一入口同时支持 SSR 成功与降级为 CSR 两种情况。
const container = document.getElementById('root');
if (container.childElementCount === 0) {
createRoot(container).render(app);
} else {
hydrateRoot(container, app, {
onRecoverableError(error, info) {
if (Math.random() < sampleRate) report('hydration-error', error, info);
},
});
}水合不匹配时 React 会丢弃该子树的服务端输出并在客户端重建,等同于这部分 SSR 白做,应当采样上报并作为缺陷处理。
启动时序。 流式 SSR 下,水合需要两个条件同时满足:应用脚本初始化完成,服务端内容已到达。两者的先后顺序不确定。使用一个共享标记协调,由后到达的一方触发。
// 内容到达时(由服务端输出的内联脚本执行,或在 DOMContentLoaded 时执行)
if (typeof window.__hydrate === 'function') window.__hydrate();
else if (window.__hydrate === undefined) window.__hydrate = true;
// 应用脚本就绪时
if (window.__hydrate === true) start();
else if (window.__hydrate === undefined) window.__hydrate = start;
function start() {
window.__hydrate = false; // 防止重复启动
hydrate();
}3.7.3 主线程
水合期间主线程被占用,用户输入无法得到响应,直接影响 INP。
- 将初始化拆分为多个任务,在任务之间让出主线程。
const yieldToMain = () =>
globalThis.scheduler?.yield?.() ?? new Promise((resolve) => setTimeout(resolve, 0));
initTracking();
await yieldToMain();
initSdk();
await yieldToMain();
hydrate();- 与首屏无关的初始化(Service Worker 注册、定时任务、非首屏 SDK)放在水合之后,且不等待其完成。
- 3.6.1 的选择性渲染同时减少了需要水合的组件数量。
验证:longtask 条目的数量与总时长;INP。
4. 渲染产物
同一套组件需要在三种环境中执行,三者对“完整性”和“速度”的要求不同:
| 产物 | 运行环境 | 目标 | 输出状态与水合数据 | 允许占位 | 允许超时 | 失败时 |
|---|---|---|---|---|---|---|
| 浏览器 | 浏览器 | 交互 | — | — | — | — |
| 首屏 SSR | 服务端 | 尽快出首屏,由浏览器接管 | 是 | 是 | 是 | 返回外壳,降级为 CSR |
| 完整内容 SSR | 服务端 | HTML 自身即完整结果,不依赖脚本 | 否 | 否 | 否 | 返回错误状态码 |
后两者的要求相互冲突,不能由同一份输出同时满足。
实现。 使用编译期常量区分,对同一份源码构建三次。打包工具会将常量替换为字面量并删除不可达分支,各产物中不包含其他产物的代码。
new DefinePlugin({
__SERVER__: JSON.stringify(target !== 'browser'),
__FIRST_SCREEN__: JSON.stringify(target === 'first-screen'),
});if (__SERVER__ && __FIRST_SCREEN__) {
data = await withBudget(fetchItems(), budgetMs);
} else {
data = await fetchItems();
}| 常量组合 | 浏览器 | 首屏 SSR | 完整内容 SSR |
|---|---|---|---|
__SERVER__ | false | true | true |
__FIRST_SCREEN__ | false | true | false |
约束:这些常量描述的是“当前是哪一份产物”,不是“当前请求来自谁”。将请求路由到哪一份产物,是上游(网关或渲染服务入口)的职责,需要单独设计和验证。
5. 降级
首屏 SSR 是加速手段。它的任何环节失败,都应退化为“未加速”,而不是“不可用”。
| 失败点 | 降级行为 | 用户可见结果 | 接管方 |
|---|---|---|---|
| 数据获取超过预算 | 以空数据渲染,写入超时标记 | 该区块先为占位,随后出现 | 浏览器重新请求 |
| 路由未匹配 | 返回外壳,HTTP 200 | 首屏变慢 | 浏览器路由 |
| 渲染抛出异常 | 返回外壳,HTTP 200 | 首屏变慢 | 浏览器全新渲染 |
| 外壳渲染失败(流式) | 结束响应并输出外壳 | 首屏变慢 | 浏览器全新渲染 |
| 序列化数据缺失或解析失败 | 读取返回 undefined | 该区块多一次请求 | 浏览器正常请求 |
| 水合不匹配 | 丢弃该子树的服务端输出 | 可能闪动 | 浏览器重建该子树 |
try {
res.status(200).send(await renderFirstScreen(req));
} catch (error) {
log(error);
res.status(200).send(emptyShell);
}降级必须可观测。 降级后页面仍然可用,问题不会以报错的形式暴露。服务端应将本次请求的渲染状态写入 HTML,由浏览器随性能数据一并上报:
<script type="application/json" id="render-status">{"host":"ok","modules":{"product":"ok","reviews":"error"}}</script>状态至少区分:未做 SSR、SSR 成功、部分失败、完全失败并降级、流式、命中预生成缓存。
例外。 完整内容 SSR 没有可接管的一方,失败时应返回真实的错误状态码。
6. 验证
6.1 生效性检查
第 3 节的多数手段由“写入方”和“读取方”两部分构成。任何一方缺失时,优化不产生效果,也不产生错误。
| 手段 | 写入方 | 读取方 | 检查最终输出 |
|---|---|---|---|
| 资源声明 | 组件登记代码块 | 服务端将登记结果输出为标签 | 响应 HTML 中存在对应的 <link> |
| 状态序列化 | 服务端写出数据 | 浏览器读取并作为初始值 | 水合后无重复的数据请求 |
| 时间预算 | 服务端写入超时标记 | 浏览器检测标记并重新请求 | 超时时浏览器发出了补偿请求 |
| 渲染状态 | 服务端写入状态 | 浏览器读取并上报 | 上报数据中状态字段的分布 |
检查顺序:先确认写入方被执行,再确认读取方存在且被执行,最后在最终的响应内容和网络面板中确认结果。只确认其中一步不足以说明优化生效。
6.2 指标对照
| 手段 | 主要影响的指标 | 可能的副作用 |
|---|---|---|
| 服务端重定向 | redirectEnd - redirectStart | — |
| Navigation Preload | fetchStart - workerStart、TTFB | — |
| 前置工作并发 | responseStart - requestStart | — |
| 数据获取时间预算 | TTFB、FCP 的高分位 | 超时请求的 LCP 变差;CLS |
| 流式输出 | TTFB、FCP | 错误处理复杂度 |
| 预生成 | TTFB | 内容时效性 |
| 选择性服务端渲染 | responseEnd - responseStart、服务端渲染耗时、长任务 | CLS;被跳过内容的出现时间 |
| 状态序列化 | 水合后的请求数、可交互时间 | HTML 体积 |
| 资源声明 | 子资源的 fetchStart、FCP、LCP | 带宽竞争 |
| 主线程让出 | 长任务、INP | 总初始化时间略增 |
6.3 评估方法
- 使用第 75 百分位而非平均值。时间预算、降级这类手段主要改善尾部,平均值上不明显。
- 按渲染状态(第 5 节)分组比较。SSR 成功与降级为 CSR 的请求混在一起时,结论没有意义。
- 实验室数据用于定位,真实用户数据用于结论。
7. 参考
- W3C, Navigation Timing Level 2
- W3C, Resource Timing
- W3C, Server Timing
- W3C, Long Tasks API
- W3C, Service Workers(Navigation Preload)
- IETF RFC 8297, An HTTP Status Code for Indicating Hints
- web.dev, Web Vitals(LCP、INP、CLS、FCP、TTFB 的定义与阈值)
- React 文档:
renderToPipeableStream、hydrateRoot、Suspense