使用 Speculation Rules API 预取与预渲染导航页面Front-End-Checklist 性能规则实战指南【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist导航延迟是拖垮 Interaction to Next PaintINP与整体感知性能的最大因素之一。本文以开源仓库 Front-End-Checklist 中 speculation-rules 技能文档 及其 references/rule.md 参考实现 为骨架结合 规则内容文件系统讲解 Speculation Rules API 的声明语法、prefetch 与 prerender 的选择、eagerness 级别、Next.js 集成、DevTools 调试与验证流程。读完本文你将能在一线项目中以渐进增强的方式落地毫秒级导航体验并规避预渲染带来的副作用与资源浪费。该规则在仓库中的定位在 Front-End-Checklist 仓库中这条规则以三份相互呼应的文档承载skills/speculation-rules/SKILL.md面向 Agent 的轻量技能卡包含元数据category: performance、priority: low、difficulty: intermediate、estimatedTime: 20 分钟、快速参考Quick Reference以及 check / fix / explain / codeReview 四个操作提示skills/speculation-rules/references/rule.md完整实现细节含全部代码示例、对比表格与验证清单packages/content/rules/en/performance/speculation-rules.mdx站点内容层与 rule.md 内容同源并额外声明了relatedRulesresource-hints、fetchpriority-attribute、import-on-interaction、import-on-visibility与sourcesweb.dev、MDN、Chrome Developers 等权威资料。SKILL.md 的description明确给出了该规则的适用场景优化多页面导航性能、降低页面切换时的 INP、为快速页面加载实现渐进增强progressive enhancement。为什么它如此重要Navigation latency is one of the biggest contributors to poor Interaction to Next Paint (INP) and overall perceived performance.导航延迟是 INP 与整体感知性能的最主要贡献者之一。预渲染最可能访问的下一页可以消除全部网络与渲染延迟——无论服务器响应时间多长用户都能在100 ms 以内看到新页面。Google Search 正是借助这一 API 实现了其instant即时搜索结果页体验。其核心思路是浏览器在后台预先完成用户很可能执行的导航当用户真正点击时页面已就绪。这与传统的客户端路由client-side router不同——它不需要任何客户端路由框架的介入而是由浏览器原生机制完成。快速参考Quick ReferenceSKILL.md 给出了四条浓缩要点也是代码评审时的检查主线使用prefetch 规则提前加载下一页的 HTML使用prerender 规则在后台完整渲染下一页实现即时导航使用href-matches 或 CSS 选择器模式限定规则范围避免浪费带宽动态站点优先使用document 规则CSS 选择器而非 URL 列表规则。检查、修复与评审流程该规则以四个可执行提示驱动落地Check检查检查站点是否对可能的导航目标使用了 Speculation Rules API 或等效的 prefetch/prerender 技术。Fix修复添加一个针对最可能下一页链接的 Speculation Rules JSON 块从 prefetch 起步逐步升级到 prerender。Explain解释说明 Speculation Rules API 与relprefetch、relprerender的区别以及预渲染如何实现近零导航延迟。核心差异在于旧式 hint 只能静态声明单个 URL而 Speculation Rules 支持基于 CSS 选择器的动态规则并能在 DevTools 中上报推测状态speculation status。Code Review代码评审审查选择器的过度激进over-eagerness——标记会预渲染无关页面、第三方 URL或包含个性化/认证内容不应被预取的规则模式。基础语法script typespeculationrulesJSON 块Speculation rules 以 JSON 形式声明在script typespeculationrules块中参考 references/rule.md 的完整示例script typespeculationrules { prefetch: [ { where: { href_matches: /blog/* }, eagerness: moderate } ], prerender: [ { where: { href_matches: /checkout/confirm }, eagerness: eager } ] } /script该 JSON 顶层包含两个列表prefetch与prerender分别对应两种推测模式。规则内的where描述目标匹配条件eagerness描述触发时机。Prefetch vs Prerender如何选择模式发生什么用户收益成本prefetch下载下一页的 HTML导航时 TTFB 更快低带宽prerender下载并在隐藏标签页中完整渲染页面近即时导航约 0 ms更高 CPU 带宽策略上应先做 prefetch——风险更低仅在拥有高置信度的页面升级为 prerender例如结账流程中唯一确定的下一步。这与 SKILL.md 中starting with prefetch and graduating to prerender的修复指引完全一致。Document Rules推荐用 CSS 选择器圈定目标Document rules 使用 CSS 选择器匹配页面上的链接比显式 URL 列表更易于维护。以下是最完整的推荐形态来自 references/rule.mdscript typespeculationrules { prefetch: [ { source: document, where: { and: [ { href_matches: /* }, { not: { href_matches: /logout } }, { not: { href_matches: /admin/* } }, { not: { selector_matches: [data-no-prefetch] } } ] }, eagerness: moderate } ] } /script要点解析source: document明确这是文档级规则匹配页面上所有a链接href_matches使用 URL 模式匹配路径and/not组合实现白名单与黑名单叠加先匹配所有路径再排除敏感路径selector_matches可按元素选择器排除例如带data-no-prefetch属性的链接。单个链接退出机制Opt-out不需要全局改动规则时可给个别链接打上标记参考 references/rule.md!-- This link will not be prefetched or prerendered -- a href/sensitive-page>script typespeculationrules { prerender: [ { source: document, where: { href_matches: /product/* }, eagerness: moderate } ] } /script实战建议默认使用moderate悬停触发可以在感知速度与带宽成本之间取得平衡immediate/eager仅用于真正必点的页面如结算确认页conservative适合带宽敏感或点击意图不确定的场景。URL List Rules显式列表与动态注入当你能确定要命中的确切页面时使用 URL 列表规则references/rule.mdscript typespeculationrules { prerender: [ { urls: [/checkout/confirm, /checkout/success], eagerness: moderate } ] } /script对于动态流程如向导式注册可以在 JavaScript 中按需注入规则references/rule.mdfunction injectSpeculationRules(urls: string[]) { if (!HTMLScriptElement.supports?.(speculationrules)) return const script document.createElement(script) script.type speculationrules script.textContent JSON.stringify({ prefetch: [{ urls, eagerness: moderate }], }) document.head.appendChild(script) } // Inject rules for the next step in a wizard injectSpeculationRules([/onboarding/step-2])从源码结构可以推断该动态注入模式与仓库中 import-on-interaction 等按交互时机加载的规则属于同一性能策略族——它们都强调在正确的时机做正确的事。Next.jsApp Router集成在 Next.js App Router 中将脚本注入根布局references/rule.md与 内容文件 一致// app/layout.tsx const speculationRules { prefetch: [ { source: document, where: { and: [ { href_matches: /* }, { not: { href_matches: /api/* } }, { not: { selector_matches: [data-no-prefetch] } }, ], }, eagerness: moderate, }, ], } return ( html langen head script typespeculationrules dangerouslySetInnerHTML{{ __html: JSON.stringify(speculationRules), }} / /head body{children}/body /html ) }注意两点工程细节通过dangerouslySetInnerHTML注入 JSON可避免 React 转义破坏规则结构规则中明确排除/api/*与带data-no-prefetch的元素——这正是 codeReview 提示中不得预取认证/接口内容的落地体现。特性检测与渐进增强Speculation Rules 自Chromium 109起支持其他浏览器会静默忽略该脚本块因此天然适合渐进增强references/rule.mdfunction supportsSpeculationRules(): boolean { return ( typeof HTMLScriptElement ! undefined HTMLScriptElement.supports?.(speculationrules) true ) } // Safe to check before injecting — browsers without support simply ignore the script if (supportsSpeculationRules()) { console.info(Speculation Rules supported — prerendering enabled) }支持说明Support Notes也特别提醒在将此项优化视为普遍生效之前必须验证项目目标浏览器与网络环境下的实际行为当协议、预加载、缓存或后台执行行为依赖浏览器与中间层支持时应准备降级方案。在 DevTools 中调试打开DevTools → Application → Background services → Speculative loads查看推测候选列表及其状态pending、fetching、ready、failed以及任何阻止原因blocking reasons。这一面板是判断规则是否生效、eagerness 是否合适的唯一权威来源。什么页面不应该被预渲染预渲染错误的目标会浪费带宽或在用户提交前触发副作用。参考 references/rule.md 的禁区清单场景为什么避免登出 / 破坏性操作可能在预渲染期间触发状态变更已认证的个性化页面可能提供错误内容或消耗限流资源重型服务端操作使服务器负载翻倍外部 / 第三方 URL浏览器会阻止跨源预渲染位于 POST 操作之后的页面预渲染仅支持 GET 请求Analytics 副作用警告内容文件 中以 Warning 形式强调预渲染页面会执行 JavaScript包括 analytics 初始化。如果用户最终未导航到预渲染页面可能会产生虚高的 PV页面浏览量。现代 analytics 库GA4、Plausible通过visibilitychange事件抑制用户从未见过的页面计数——在大规模启用 prerender 前务必验证你的 analytics 实现是否处理了该事件。与旧技术的关系为何说它超越 relprefetchSKILL.md 的explain提示要求讲清与relprefetch/relprerender的差异。综合文档可归纳为三点动态性旧 hint 只能逐个静态声明 URLSpeculation Rules 支持基于 CSS 选择器与href_matches模式的文档级规则站点新增链接后无需改动配置可观测性DevTools 提供 Speculative loads 面板可看到候选、状态与阻止原因精细化eagerness四级触发策略远超旧 hint 的解析即预取。在 speculation-rules.mdx 的relatedRules中它被明确标注为取代旧的 relprefetch / relprerender hint见 resource-hints 的关联理由同时建议与以下规则协同审视resource-hintspreload / preconnect / dns-prefetch 等资源提示的决策表如 preload 通常限制在每条路由 35 个以内fetchpriority-attribute两者都向浏览器传递资源重要性提示共同构成完整性能策略import-on-interaction 与 import-on-visibility同属performance/loading区域常被一起评审。此外仓库中还有与其强相关的 back-forward-cache 规则——两者同属让浏览器提前/复用渲染结果的思路可对比学习。验证清单Verification来自 references/rule.md 与 内容文件 的完整验证步骤添加规则后打开 DevTools →Application → Speculative loads确认目标 URL 出现且状态为Ready导航到被推测的页面检查Network面板——主文档应从缓存提供体积显示为 (prefetch cache)确认/logout、/api/*及所有认证型变更页面已从规则中排除使用Performance面板的 LCP 与 FCP 指标对比开启规则前后的导航性能。最后回到 SKILL.md 的提醒priority: low、difficulty: intermediate、预计耗时 20 分钟——这是一项低成本、渐进式的性能优化正确做法是先 prefetch、按需升级 prerender、持续用 DevTools 验证而非一次性全站激进预渲染。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考