You need to enable JavaScript to run this app. 动态单页PWA开发中Service Worker未触发fetch事件实现离线功能的问题
优惠活动
大模型
产品
解决方案
定价
更多

动态单页PWA开发中Service Worker未触发fetch事件实现离线功能的问题

Service Worker fetch事件无触发的排查方向与修复方案

fetch事件完全无响应,本质上是Service Worker从注册到拦截请求的全链路存在断点,并非编写的缓存逻辑本身存在问题,针对动态单页应用的常见问题按排查优先级排序如下:

  • 检查SW作用域覆盖范围
    默认情况下,SW的可拦截作用域由脚本所在的路径决定:如果把SW脚本放在/static/sw.js路径下,默认只能拦截/static/路径下的请求,根本无法覆盖根路径的HTML、接口、核心静态资源,自然收不到任何fetch事件。
    修复方法:注册SW时手动指定作用域为站点根路径,同时在服务器侧为sw.js的响应配置Service-Worker-Allowed: /响应头,允许SW向上拓展作用域权限。
  • 确认请求是否走原生网络通道
    SW的fetch事件只会拦截浏览器内核层面发起的原生网络请求,如果单页应用内的请求被JS层自定义拦截器(如Axios适配器、自定义blob资源URL、本地直接生成的静态资源)直接接管,没有真正走到浏览器网络栈,SW是完全感知不到这类请求的。
  • 排查SW的激活接管状态
    很多场景下SW代码已经写好,但因为旧版本SW仍处于等待激活状态,新写的fetch监听逻辑根本没有实际运行:
    • 在SW的install事件中调用self.skipWaiting(),跳过旧版本SW的等待流程
    • 在SW的activate事件中调用clients.claim(),让新SW立刻接管所有已打开的页面
      测试时优先在浏览器DevTools的Application面板手动注销旧SW、清空旧版本缓存,不要靠热更新状态判断逻辑是否生效。
  • 修正现有代码的逻辑漏洞
    目前的SW代码存在两类容易造成“fetch事件未触发”错觉的问题:
    • 没有做请求合法性校验:对非同源请求、非http/https协议的请求、浏览器扩展发起的请求直接走缓存匹配逻辑,会直接抛异常报错,从控制台视角容易误判为SW没有监听到请求。
    • 没有离线场景的兜底分支:动态单页应用碰到离线刷新时,缓存匹配空值、网络请求直接失败,会直接触发全局报错,同样会造成SW拦截失效的假象。

修正后的可运行SW逻辑参考:

// SW脚本建议放置在站点根目录下,配合根路径作用域配置使用
self.addEventListener('install', () => {
  self.skipWaiting();
});

self.addEventListener('activate', (event) => {
  event.waitUntil(
    caches.keys().then((allCaches) => 
      Promise.all(
        allCaches
          .filter((key) => key !== 'pwa-core-v2')
          .map((key) => caches.delete(key))
      )
    ).then(() => self.clients.claim())
  );
});

self.addEventListener('fetch', (event) => {
  const req = event.request;
  // 跳过非GET请求、非同源请求,避免无意义的拦截
  if (req.method !== 'GET' || !req.url.startsWith(self.location.origin)) return;

  event.respondWith(
    caches.match(req).then((cachedRes) => {
      // 缓存命中直接返回
      if (cachedRes) return cachedRes;

      // 缓存未命中,发起网络请求并写入缓存
      return fetch(req).then((networkRes) => {
        // 仅缓存正常的同源GET响应
        if (!networkRes || networkRes.status !== 200 || networkRes.type !== 'basic') {
          return networkRes;
        }
        const resClone = networkRes.clone();
        caches.open('pwa-core-v2').then((cache) => cache.put(req, resClone));
        return networkRes;
      }).catch(() => {
        // 离线兜底:页面导航请求返回提前缓存的应用入口HTML
        if (req.mode === 'navigate') return caches.match('/index.html');
      })
    })
  )
})

内容的提问来源于stack exchange,提问作者ZergHeureux

相关产品推荐
方舟 Agent Plan

超全模态模型 × Harness 升级,最新支持 Deepseek-V4.1-Flash、GLM-5.3 系列、Doubao-Seedream-5.0-pro、Kimi-K3 (部分), 限时 9.9 元起

最近更新时间:2026.10.24 00:24:05