性能中的 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。
检测 API 并退回 prefetch
链接到“检测 API 并退回 prefetch”一节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);}脚本动态添加的规则同样受数量限制。移除脚本元素,就会取消尚未完成的推测加载并释放容量。
另请参阅
链接到“另请参阅”一节- Speculation Rules(wicg.github.io)
- Prerender pages in Chrome for instant page navigations(developer.chrome.com)
- Debug speculation rules(developer.chrome.com)
- 前进后退缓存(bfcache)
- 资源提示(preload 与 preconnect)
- View Transitions API
规范
| 规范 | 状态 |
|---|---|
| 无。 | |