linux.do

踩坑记录：MkDocsMaterial网站开启SPA却在Cloudflare变成全页刷新的解法

各位佬友，最近在折腾一个 MkDocs 的静态文档站，托管在 Cloudflare Pages 上。MkDocs Material 主题有一个非常好用的特性叫 navigation.instant，开启后网站就变成了单页应用（SPA），切网页完全无刷新，全局的背景音乐播放器也不会断。
这个特性其实我 2026 年 2 月 27 日已经成功使用上了。当时是一切正常的。

然而今天 2026 年 3 月 8 日凌晨 3 点打开我的网站一看，点击链接切页面立马变成传统的整页硬刷新，网站的音乐进度直接归零。

难道是我这几天不小心把网站源码改坏了？mkdocs serve！——结果是，我在本地跑得好好的，丝滑无比。但是一推到 Cloudflare Pages 线上，又寄了

排查过程（这些都没用，是踩坑试错）
一开始以为是我自己写的特效 JS 在 SPA 切页瞬间报错，导致路由挂了。我把所有自定义的脚本全删了（注释了），还是硬刷新。

后来用无痕模式排除了浏览器抓包插件劫持 XHR 的嫌疑。

接着怀疑是 CF 免费版默认开启的 Speed Brain（早期提示）功能冲突，关了清缓存，没用。

又去改 mkdocs.yml 里的 site_url，以为是跨域防卫机制，依然没用。

真正的解法发现
无奈之下死盯着 F12 的 Network 面板看，发现一个细节：当鼠标悬停在导航链接上时，网络请求里会瞬间飘红一个 503 Service Unavailable 的报错，请求类型是 prefetch。响应头里带了一句 Cf-Speculation-Refused: prefetch refused: not eligible。

我们知道，MkDocs 的无刷新机制是靠鼠标 hover 链接时，在后台静默发起 prefetch 请求来预加载下一个页面的 HTML。但 Cloudflare 的边缘节点最近防备心太重，它的“浏览器完整性检查”和 Bot 防护策略，一看到这种纯靠后台发起的预加载请求，直接当成非法爬虫在边缘节点拦截掉（猜测的，反正我在最后解决方案把WAF全绕过了），强行返回 503。

MkDocs 的前端路由一收到 503，以为目标页面出了异常，为了防卡死，就会主动放弃无刷新接管，强制回退成浏览器原生的整页跳转。

解决方案
直接在 CF 的 WAF 里给 prefetch 请求设置跳过全部WAF（也许有佬友知道具体是哪一条最近作孽的？我没空一个个排查只好全选了）。

1. 进 CF 控制台，找到你的域名，左侧菜单进安全性 → WAF → 自定义规则，新建一个规则。
2. 匹配条件这样写：字段选“标头” 名称填 sec-purpose （CF 的规则引擎强制要求请求头必须全小写，如果你按标准大写写成 Sec-Purpose，保存时直接报红报错）。运算符选“等于” 值填 prefetch
3. 下面的采取措施选“跳过” (Skip)。
4. 要跳过的 WAF 组件，闭眼全部勾上。
5. 保存部署规则。
6. 最后也是最关键的一步：去 CF 的“缓存” → “配置”里，点一下“清除所有缓存”。不然 CDN 节点有可能还记着以前的拦截策略。

等几十秒缓存清空，再强刷一下页面。F12 里那个讨厌的 503 就变成 200 OK 了。随便怎么点，页面都是瞬间无刷新切换，音乐也不会断了。

希望这篇贴子能帮到以后用 CF 托管 MkDocs 的佬友们。也希望有专业的CF高手指点一二QWQ

1 个帖子 - 1 位参与者

阅读完整话题

via LINUX DO - 最新话题 (author: 鹿目圆)

55 views20:22