Vite + VitePWA环境下Service Worker无法缓存文件求助

排查步骤 #

• 确认Vite PWA插件模式配置
  如果你使用自定义的service-worker.js，必须在vite.config.ts中设置strategy: 'injectManifest'，并指定swSrc指向你的文件。如果误设为generateSW，插件会自动生成替代的Service Worker，覆盖你的自定义逻辑：

  // vite.config.ts
  import { VitePWA } from 'vite-plugin-pwa'
  
  export default {
    plugins: [
      VitePWA({
        strategy: 'injectManifest',
        srcDir: 'src',
        swSrc: 'src/service-worker.js',
        // 其他配置
      })
    ]
  }
  

• 验证Service Worker作用域
  检查浏览器控制台Application > Service Workers中的作用域是否覆盖你的页面路径。Vite默认base可能不是根路径（比如开发环境的/或生产环境的自定义路径），若作用域不匹配，SW无法拦截页面请求。可通过两种方式修正：

  1. 在Vite配置中设置base: '/'
  2. 注册SW时显式指定作用域：

     navigator.serviceWorker.register('/sw.js', { scope: '/' })
     

• 开启Workbox调试日志
  在自定义service-worker.js顶部添加调试配置，查看缓存过程中的详细日志：

  workbox.setConfig({ debug: true });
  

  然后在Application > Service Workers中勾选Update on reload，刷新页面后查看控制台的Workbox日志，定位缓存失败或路由匹配异常的原因。

• 检查路由规则优先级
  确保离线重定向的路由规则优先于其他缓存规则。例如，使用NavigationRoute处理导航请求失败的逻辑必须放在静态资源缓存规则之前：

  // service-worker.js
  import { NavigationRoute, registerRoute } from 'workbox-routing';
  import { NetworkOnly } from 'workbox-strategies';
  
  // 先注册离线重定向规则
  const navigationRoute = new NavigationRoute(new NetworkOnly({
    fallback: async () => caches.match('/offline')
  }), {
    denylist: [/^\/api/] // 排除API请求
  });
  registerRoute(navigationRoute);
  
  // 再注册静态资源缓存规则
  registerRoute(
    ({ request }) => request.destination === 'style' || request.destination === 'script',
    new StaleWhileRevalidate()
  );
  

• 生产模式验证
  Vite开发环境的HMR机制可能干扰Service Worker的缓存行为，建议先执行npm run build构建生产包，通过本地服务（如serve dist）测试离线功能，排除开发环境的特殊限制。

可能的问题原因 #

• 插件模式配置错误：使用generateSW模式时，插件会忽略自定义service-worker.js，仅根据插件配置生成SW，这会导致你的缓存逻辑完全失效，仅保留插件默认的/offline页面缓存（若配置了offlinePage）。
• 作用域不匹配：SW的作用域默认是其文件所在的路径，若Vite的base配置为非根路径，SW无法拦截根路径下的页面请求，自然无法触发离线重定向。
• 路由规则顺序错误：若离线重定向规则在其他缓存规则之后，导航请求可能被先匹配的规则处理（如NetworkFirst），导致失败时无法触发/offline的重定向逻辑。
• 版本兼容性问题：vite-plugin-pwa@0.16.4与workbox@7.0.0可能存在兼容性差异，部分Workbox API可能未被插件正确适配。可尝试降级Workbox到插件文档推荐的版本（如6.x系列），或升级插件至最新稳定版。
• 开发环境限制：Vite开发环境下，文件无哈希后缀，Workbox可能因文件频繁变更而跳过缓存，导致离线功能无法正常测试，必须在生产模式下验证。

内容的提问来源于stack exchange，提问作者Generation