跳转到内容

性能中的 API

Speculation Rules API

发布于 更新于

Speculation Rules API 让浏览器提前预取或完整预渲染指定 URL,用户点击时便可直接从内存加载。用 <script type="speculationrules"> 中的 JSON 块声明这些 URL,也可以让 Speculation-Rules 响应标头指向一个 JSON 文件。它用于文档,取代 <link rel="prefetch"> 和已废弃的 <link rel="prerender">(Chrome 63 起后者改为 NoState Prefetch)。生产环境中只有 Chromium 支持。

<script type="speculationrules">
{
"prerender": [{ "where": { "href_matches": "/articles/*" }, "eagerness": "moderate" }],
"prefetch": [{ "urls": ["/next.html"] }]
}
</script>
Speculation-Rules: "/rules.json"

浏览器只解析这个 JSON 块,不执行它。不支持此类型的引擎会忽略它。Chrome 105(Android 为 103)起只支持同源预渲染,109 是第一个完整版本,Chrome 121 加入 Speculation-Rules 头并让 source 成员变为可选;Safari 26.2 启用「SpeculationRules prefetch」偏好后支持 prefetch 规则,Firefox 只在 preview 版本里部分实现了 URL 列表预取(BCD html.elements.script.type.speculationrules)。

成员 类型 含义
prefetch、prerender 规则数组 动作。prefetch 下载响应;prerender 在隐藏标签页中加载并渲染页面,脚本也会执行。
urls 字符串数组 列表规则:显式 URL。内联规则相对文档解析;从文件加载的规则相对该文件的 URL 解析,设置 "relative_to": "document" 后才相对文档解析。
where object 文档规则:对页面内链接的谓词,含 href_matches(URL 模式)、selector_matches(CSS 选择器)以及 and、or、not 组合子。
eagerness "immediate"、"eager"、"moderate"、"conservative" 何时执行。immediate 在解析时;moderate 在桌面端悬停 200 ms 之后或更早的 pointerdown 时触发,移动端自 2025 年 8 月起改用视口启发式;conservative 在 pointerdown;eager 在 Chrome 143 之前与 immediate 行为相同,之后桌面端为悬停 10 ms,移动端自 2026 年 1 月起改用视口启发式。列表规则默认 immediate,文档规则默认 conservative。
requires array ["anonymous-client-ip-when-cross-origin"] 要求浏览器能向跨源预取目标隐藏客户端 IP,规则才生效;Chrome 靠 Google 的预取代理做到这一点。
referrer_policy、tag、expects_no_vary_search、target_hint string 推测请求的 referrer、在 DevTools 和 Sec-Speculation-Tags 头中显示的标签、No-Vary-Search 提示,以及预渲染的目标(_self 或 _blank)。

Chrome 限制并发的推测:immediate 规则 10 个预渲染和 50 个预取,eager、moderate 与 conservative 规则各 2 个,出现更新的候选时按先进先出替换(Prerender pages in Chrome,developer.chrome.com)。预取请求带 Sec-Purpose: prefetch;预渲染的文档看到 document.prerendering === true,并在激活时收到 prerenderingchange 事件。

规则集顶层 JSON 值不是对象时,解析会抛出 TypeError,浏览器随即忽略这个规则集。DevTools 能看到解析状态。

Chromium 是唯一在稳定版中具备 prefetch 和 prerender 规则的引擎:Chrome 和 Edge 自 105 起支持 prerender 规则,自 110 起支持 prefetch 规则,头形式自 121 起。Safari 26.2 只在启用「SpeculationRules prefetch」偏好时解析 prefetch 规则并忽略 prerender;Firefox 稳定版忽略该脚本类型,只有 preview 版本能处理 URL 列表预取(BCD html.elements.script.type.speculationrules)。不支持的引擎只会失去提前加载的效果。规则可以直接发布,无需按引擎筛选。

预渲染会在导航前执行脚本,因此浏览量统计要等到页面激活后再上报。

使用 moderate 的文档规则会预渲染指针停留 200 ms 的那篇文章,不必预先渲染页面上的每个链接。Chrome 仍可能因内存或设置而跳过预渲染。

<script type="speculationrules">
{
"prerender": [{
"where": { "and": [
{ "href_matches": "/articles/*" },
{ "not": { "selector_matches": ".no-prerender" } }
]},
"eagerness": "moderate"
}]
}
</script>

给退出登录、一键操作等不应预渲染的链接加上 no-prerender 类;预渲染的页面会运行脚本,加载时的副作用在用户决定访问之前就会发生。

统计页面浏览的代码必须等预渲染页面变为可见,否则每个悬停过的链接都算一次访问。

function onVisible(callback) {
if (document.prerendering) {
document.addEventListener('prerenderingchange', callback, { once: true });
} else {
callback(); // 未预渲染(或引擎不支持):立即执行
}
}
onVisible(() => sendPageView(location.href));

没有该 API 的引擎里 document.prerendering 为 undefined,else 分支把它当作普通加载。普通加载也可能发生在后台标签页,需要时再等 visibilitychange。

HTMLScriptElement.supports('speculationrules') 是能力测试。兜底插入一个 <link rel="prefetch">,在 Firefox 和 Chromium 中为下一个文档预热 HTTP 缓存而不预渲染。

function speculate(url) {
if (typeof HTMLScriptElement.supports !== 'undefined' && HTMLScriptElement.supports('speculationrules')) {
const script = document.createElement('script');
script.type = 'speculationrules';
script.textContent = JSON.stringify({ prefetch: [{ urls: [url] }] });
document.head.append(script);
return;
}
const link = document.createElement('link'); // 兜底:普通 prefetch,不预渲染
link.rel = 'prefetch';
link.href = url;
document.head.append(link);
}

脚本动态添加的规则同样受数量限制。移除脚本元素,就会取消尚未完成的推测加载并释放容量。

规范

规范状态
无。