预取配置

在站点的 data/delivery.toml 中配置。模块默认值在 module/data/delivery.toml。Hugo 按顶层字段替换；站点声明 [prefetch] 后， 须填写完整的预取表，未填写的图标和范围不继承模块值。配置应用到所有语言。

预取按条目主图标名称和列范围匹配。Hugo 生成一份共享 CSS 选择器： Speculation Rules 直接匹配文档；自实现 JS 用同一选择器收集链接。 链接不输出预取属性，导航数据不再包含预取分类。

图标与列范围

folder 表示集合入口策略，file 表示内容页面策略。 这些名称是预取提示；更换条目图标也会改变策略。 只匹配条目链接内的主 SVG 图标，正文装饰图标不参与图标分类。 未配置图标、文字、图片和其他页面链接使用 default。

普通链接可直接输出 <a href="…">，无需调用预取专用片段或添加预取属性。 图标和列范围策略读取已有条目结构：主链接带 data-list-entry， 主 SVG 图标位于其直接子元素 .item-icon 中。 共享列表片段负责样式、选中态和可访问属性，模板也可直接输出相同结构。

只计算导航和集合条目列。文章正文、章节和元信息不参与编号。 横向滚动不改变编号。没有路径列的文章页，根导航同时是尾列。 N 使用正整数；偏移到根导航时可匹配它，超出实际列数时不匹配。 偏移键统一加引号；+ 不能用于 TOML 裸键。

重叠优先级固定为：root > tail > tail-N > root+N > all > default。 例如三列页面的 root+1 和 tail-1 指向同一列，使用 tail-1。 两端的明确配置优先；显式 off 阻止回落，配置声明顺序不影响结果。 基础预取和预渲染分别解析。基础预取为 off 的链接不参与预渲染。 两份规则各自生成互斥选择器，共用列定位方法，不需要手写选择器。

配置

[prefetch]
enabled = true
default = "conservative"

[prefetch.icons.folder]
all = "conservative"
root = "moderate"
tail = "eager"
"tail-1" = "moderate"
# 需要按左侧深度配置时，可追加：
# "root+1" = "moderate"

# 原生增强；模块默认对尾列文件夹使用 moderate，可改为 off。
[prefetch.prerender]
default = "off"

[prefetch.prerender.icons.folder]
tail = "moderate"

模块默认关闭预取。开启后，前端自动选择一个机制： 原生 Speculation Rules → 已活动且匹配本站脚本和范围的 Banyan SW → link prefetch。 没有可用机制时停止。浏览器支持原生规则但因设置或资源限制拒绝预取时， 不额外用另一套机制强制请求。

SW 缓存与预取独立。启用 SW 时，完整填写顶层表：

[service_worker]
mode = "enable"
content_check_interval = 5
offline_notice_path = "offline/"

没有活动 SW 时，启动查找最多等待 250ms，然后使用 link。 每页只选择一次机制，之后不自动切换。

同名档位传给原生规则的 eagerness。原生触发细节由浏览器决定； 自实现使用上表中的简单近似。节省流量或 2G 连接关闭自实现的批量、 悬停和可见预取，明确交互仍可预取。

prerender 表沿用图标和列范围，未单独指定的范围使用 off。 模块默认将尾列文件夹设为 moderate；站点可将其改为 off。 仅在基础规则开启且选择原生机制时生效。它增加原生预渲染， 不会改变 SW/link 的基础预取强度。总开关关闭时两者都关闭。 原生 prefetch 请求页面 HTML；prerender 加载资源并运行页面脚本。 SW 处理 HTML 缓存缺失时，也会预热其中引用的同源指纹资源。

配置应用到所有语言。Hugo 严格校验字段、图标、范围和档位，包括关闭时的配置。 旧环境表、运输代码和会话去重后缀不再接受。

启动与缓存

Hugo 把原生规则写入静态 script[type=speculationrules]， 并将其精确正文哈希加入 CSP。规则不依赖部署响应头或额外 JSON 请求。 前端在导航和排序初始化后设置 data-prefetch-ready； 只有选中原生机制时，才设置 data-prefetch-native-ready。 路径恢复的 pending 状态阻止两种机制匹配中间链接。

自实现只扫描一次。可见预取持续观察初始化时已有的链接， 滚动后首次满足可见条件仍可触发。后续新增链接不加入自动预取； 交互时直接匹配链接。不监听 DOM、来源或排序变化。 原生规则的后续匹配由浏览器处理。

页面内 URL 集合防止反复发送；完整重载后重新开始。 去重忽略片段，保留查询参数。发送或 link 加载的可检测失败允许重试。 SW 消息排队成功不表示缓存写入成功。SW 合并相同 URL 的进行中任务， 缓存命中后仍检查相关资源；不维护跨页面的“已预取”会话记录。 新版本切换后，新页面可以再次预热。旧页面不主动重扫。

诊断

/prefetchdebug/ 提供自动、原生、SW、link 和关闭五个选择。 应用后重载，仅影响此诊断页；普通页面忽略测试参数。 强制模式不可用时直接显示原因，不切换到另一机制。 全站关闭时，诊断页仍加载共享引擎和规则，可明确选择机制测试。

页面显示能力、选择结果、潜在 URL、提示发送次数、已知失败和配置。 它不额外请求当前页面或规则文件。发送次数不是下载完成次数； 原生执行结果在 DevTools 的 Speculative loads 中查看。

选择原生或 link 不会绕过已有 SW 的 fetch/cache。 需要绕过时，在 DevTools → Application → Service Workers 使用 Bypass for network。诊断页不自动安装、注销 SW 或清除缓存。