Cache API用 match 选项控制查询参数是否参与缓存键的实现方法

Cache API 默认会把 URL 的查询字符串纳入匹配判断。比如缓存里只有 /assets/app.js?v=1，直接匹配 /assets/app.js?v=2 通常不会命中；如果这些参数只是版本标记或无关追踪字段，就可以在 match() 的第二个参数中使用 ignoreSearch: true。它只改变本次查找的比较方式，不会改写缓存中已经保存的 Request。

先把缓存键和查询参数的关系说清楚

Cache.match() 返回第一个匹配的 Response，没有匹配时得到 undefined。默认情况下，https://demo.test/data.json?lang=zh 和 https://demo.test/data.json?lang=en 不应被当作同一请求。将 ignoreSearch 设为 true 后，匹配时会忽略 ? 后面的内容，因此两者可以落到同一个已缓存资源上。

这里的关键是“查找时忽略”，不是“存储时归一化”。调用 cache.put(request, response) 仍然保存传入的原始 Request。若同一个 Cache 中同时存在多个只在查询字符串上不同的条目，忽略查询后可能有多个候选，返回哪个应由你的缓存写入策略和条目顺序决定，不能把它当作精确的参数路由器。

最小实现：只在读取阶段打开 ignoreSearch

下面的 Service Worker 片段把静态脚本的查询参数视为缓存无关信息。先按忽略查询的规则读取；未命中时访问网络，并使用原始请求保存响应。代码中的 response.ok 判断用于避免把明显的 HTTP 错误响应写进静态资源缓存。

const CACHE_NAME = "assets-v1";

self.addEventListener("fetch", (event) => {
  const url = new URL(event.request.url);
  if (event.request.method !== "GET" || url.pathname !== "/assets/app.js") {
    return;
  }

  event.respondWith((async () => {
    const cache = await caches.open(CACHE_NAME);
    // 查询参数只用于追踪或版本标记时，读取阶段忽略它。
    const cached = await cache.match(event.request, { ignoreSearch: true });
    if (cached) {
      return cached;
    }

    // 网络请求保留原始 URL，避免把示例策略误当成 URL 重写。
    const response = await fetch(event.request);
    if (response.ok) {
      // clone 让返回给页面的响应与写入缓存各自拥有可读的副本。
      await cache.put(event.request, response.clone());
    }
    return response;
  })());
});

这段代码的效果是：缓存中已有任意一个同路径脚本时，带不同查询参数的后续请求可能直接复用它；首次访问则按当前 URL 写入。若查询参数代表真实内容，例如 ?lang=en 会改变正文语言，就不要打开 ignoreSearch，而应让每种资源保持独立缓存项。

把响应差异和清理边界一起纳入设计

查询字符串不是唯一的匹配条件。Cache 的匹配还会受到请求方法和响应 Vary 的影响；match() 默认只接受适合缓存读取的 GET/HEAD 语义，ignoreMethod 是另一个独立选项，不能用它替代 ignoreSearch。本主题只处理 URL 查询参数，生产代码不要顺手放宽其他条件。

Cache 也不会自动替你清理条目。可以在 activate 阶段删除不再使用的版本，并用 caches.keys() 配合白名单维护缓存名称；对高频带参数资源，还应设置容量上限或主动删除旧条目。

用命中日志验证策略是否真的合适

调试时不要只看“页面加载成功”。在命中分支记录请求 URL 和缓存版本，在网络分支记录是否写入；再分别测试无参数、参数顺序变化、真实内容参数和非 GET 请求。若带 ?lang=en 仍返回中文，说明忽略查询的范围超过了资源实际变化边界，应立即恢复默认匹配。

另一个容易忽略的事实是：Cache API 的存储由浏览器按源管理，通常要求 HTTPS 安全上下文；缓存对象何时被浏览器回收也不是应用可以完全控制的。因此 ignoreSearch 解决的是一次匹配决策，不等于持久化保证，也不等于 HTTP 缓存策略。

常见问题

ignoreSearch 会删除缓存 URL 的查询参数吗？

不会。它只影响本次 match() 的比较，cache.put() 仍保存原始请求。

查询参数顺序不同也会被忽略吗？

开启该选项后，整个查询字符串都不参与本次匹配，所以顺序问题也失去区分作用；这正是它不适合参数驱动接口的原因。

为什么 match 命中了却拿到旧内容？

可能是多个同路径条目都符合忽略查询规则，也可能是 Cache 名称没有升级。统一写入策略并在版本切换时清理旧缓存。

实际落地时可以把判断收敛成一句话：参数只影响统计或版本标记，就考虑 ignoreSearch: true；参数改变响应内容，就保留默认匹配，并让缓存键明确表达这种差异。