引入 swpp：先定规则，再谈缓存，以及集成路上踩过的几个坑

缓存协议：false 与 -1#

swpp 的规则返回值语义很简单，但和直觉相反的地方恰恰在这里：

1
// 返回 false —— 不缓存，每次照常走网络
2
// 返回 -1  —— 永久缓存，且不参与 swpp 的版本更新检查
3
function matchCacheRule(url: URL): number | false;

-1 看着像「永远缓存」，实际上它真正的意思是「这份资源信任文件名就是版本，交给 swpp 管反而多余」。所以它只适合两类东西：

• 文件名带内容哈希的构建产物（如 /_astro/*.js），内容一变文件名必变，旧引用自然失效
• 由版本号机制统一失效的 HTML 页面

其余资源——API、跨域资源、任何会原地更新的东西——一律 false，别指望 SW 替你兜底。

版本号驱动失效：update.json#

离线是副产品，那新内容怎么推送？swpp 的做法是给缓存引入「版本」概念。生成的 sw.js 里藏着几个关键常量：

1
const CACHE_NAME = "kmarBlogCache";
2
const UPDATE_JSON_URL = "swpp/update.json";
3
const VERSION_PATH = "https://id.v3/"; // 版本元数据以特殊 key 存在 Cache Storage
4
const INVALID_KEY = "X-Swpp-Invalid";  // 失效标记，打在待更新的缓存 entry 上
5
const UPDATE_CD = 600000;              // 两次版本检查的最小间隔（10 分钟）

SW 收到页面发来的更新信号后，会拉一份 swpp/update.json（构建期生成），把里面的版本号和自己存下的版本号做比较：

三个值得记住的兜底行为：

• 首访用户没有旧版本号，直接返回 -1，按当前规则铺缓存，不参与比较
• 版本号整体丢失（比如缓存被浏览器清了但 SW 还在）时，干脆清空整个 CACHE_NAME 重来
• 逃生门 escape：构建期由 defineCrossEnv 注入到 sw.js，跨版本协议大改时用来兜底

坑一：saveFiles 撞上已存在文件，直接抛 file_duplicate#

第一次跑构建一切正常，第二次跑同一份 dist/ 就直接炸。翻 swpp-backends 源码，saveFiles 对「文件已存在」的处置不是覆盖，而是抛 file_duplicate 异常。

这其实是个守护设计：publicPath 指向的就是站点根目录，里面本来就躺着别人写的文件，无脑覆盖太危险。但对我们的构建流程来说，swpp/ 产物每次都是重新生成的，旧的必须清掉。解法很朴素——先删后写：

1
const files = await builder.buildFiles();
2
// saveFiles 对已存在的文件会抛 file_duplicate，先清掉上次构建可能遗留的产物
3
await Promise.all(
4
  files.map((file) => fs.rm(file.path.absPath, { force: true })),
5
);
6
await builder.saveFiles();

坑二：注入成功的前提是「结构完整的 head」#

注入脚本找的是 <head ...> 开标签和它之后的 </head>：

1
const openTag = /<head[^>]*>/i.exec(html);
2
if (!openTag) return null;
3
const closeStart = html.toLowerCase().lastIndexOf("</head>");
4
if (closeStart < openEnd) return null;

任何一边缺了，injectHead 就返回 null，构建日志里只多一行：

1
⚠ Skipped ${file}: no <head> found

Astro 正常产出的页面没问题，但自定义输出、纯脚本生成的页面一旦结构不完整，就会被静默跳过——SW 注册脚本没进去，那一页就成了缓存盲区。坑不在实现，在于它太安静了。所以注入完我特意数了成功数打日志，injected: n/total 对不上就立刻查。

另一个相关细节是幂等：html.includes(DOM_JS_URL) 命中就直接跳过，保证脚本重复执行不会给页面塞两份注册代码。

坑三：runOnBrowser 是被 toString 的裸函数，别惦记闭包#

这是最反直觉的一个。runOnBrowser 的实现会被 swpp 整个序列化（toString）后嵌进生成的 sw.js——函数体之外的一切都带不走：闭包变量、外层常量、import 进来的东西，全都不存在。

我第一次写的时候，习惯性地在函数体里引用了 SITE_ORIGIN，构建一点错不报，浏览器里跑起来就是 undefined !== undefined 之类的诡异比较。排查了很久才意识到：那个函数在 sw.js 里是孤零零的一段源码，它只认识自己函数体里的东西。

所以写法上要遵守两条：

1. runOnBrowser 函数体必须自包含，要判断同源就现场算 self.location.origin
2. runOnNode 运行在构建期 Node 环境，随便复用模块作用域——但别忘了它和浏览器端必须产出一致的判定结果

坑四：-1 是「永久缓存」，不是「永不变」#

一开始想偷懒，把所有资源都返回 -1，想着「缓存越多越离线」。结果发现 -1 的资源不参与版本检查，意味着它一旦进了缓存，就只有靠它自己的 URL 变化才会被替换。

• 对 /_astro/* 这种带内容哈希的产物，这没问题——文件变了 URL 必变
• 对固定 URL 的资源，这就是灾难：内容更新了，URL 没变，swpp 版本机制又不检查它，用户将永远看到旧文件

所以 -1 的正确用法是且仅是「文件名即版本」的资源；任何「URL 不变但内容会变」的东西，要么交给版本机制失效，要么干脆不缓存。HTML 之所以能 -1，是因为它不在版本机制之外——HTML 恰恰是版本号要盯的主要对象。

坑五：HTTP 缓存头不配合，版本检查会失灵#

swpp 的更新链路依赖「SW 每次能拿到新鲜的 sw.js 和 update.json」。部署端要是给这两个文件套上长缓存，SW 检查到的版本号永远是旧的，等于版本机制整个失灵。而 /_astro/* 这类产物则反过来，巴不得 CDN 层就给足缓存，SW 都不必每次都回源。

所以部署在 Cloudflare Pages 时，_headers 里必须给出截然相反的两段：

1
/sw.js
2
  Cache-Control: no-cache, must-revalidate
3
/swpp/*
4
  Cache-Control: no-cache, must-revalidate
5
/_astro/*
6
  Cache-Control: public, max-age=31536000, immutable

坑六：验证 SW 永远慢半拍#

SW 的更新节奏和普通前端完全不一样，第一次接触很容易被它的「慢半拍」绕进去：

1. 首次访问只是注册 + install，页面还没被接管
2. 刷新一次后 activate 接管，之后的请求才走缓存
3. 新版本的 sw.js 下载后可能处于 waiting 状态，要等旧页面全部关闭才接管
4. dom.js 刷新前还有 sessionStorage 防死循环标记，一个 session 里只刷新一次

把这些叠在一起，实际效果是：改了规则 → build → 刷新 → 看效果，不是原子动作。你可能刷到的是仍被旧 SW 喂着的旧页面，而新 SW 正安静地等在后台。

再叠加一个老熟人——astro preview 只伺服上次 build 产出的 dist/，不编译任何东西。如果 build 都没重新跑，你验的压根不是刚写的代码。所以正确的验证姿势是：

1. 先 pnpm build 再 pnpm preview，确认 dist 是新的
2. 打开开发者工具 Application 面板看 SW 状态，必要时手动 Skip waiting
3. 要彻底重来就直接 Unregister + Clear storage，从头走一遍首访流程