Webpack Workbox Plugin问题：Service Worker无法正常提供清单起始URL

我帮你梳理下这个问题的核心解决思路：你遇到的「用户收不到安装提示」本质是Service Worker没能正确响应清单里的起始URL请求，同时离线页面的路由也需要明确配置。咱们一步步来调整：

1. 确保起始URL被Service Worker缓存 #

PWA审核要求起始URL（通常是根路径/或者/index.html）能被Service Worker离线访问，所以必须让Workbox把这个URL加入缓存。你可以通过两种方式配置：

• 方式一：直接指定缓存起始页面
  在GenerateSW配置里添加include字段，强制包含起始页面：

  new WorkboxPlugin.GenerateSW({
    swDest: 'sw.js',
    include: [/index\.html$/, /offline\.html$/], // 同时包含起始页和离线页
    // 其他已有配置...
  })
  

• 方式二：用运行时缓存匹配起始URL
  如果你的起始URL是动态的（比如根路径/），可以通过runtimeCaching添加路由规则：

  new WorkboxPlugin.GenerateSW({
    swDest: 'sw.js',
    runtimeCaching: [
      {
        urlPattern: /^\/$/, // 匹配根路径起始URL
        handler: 'StaleWhileRevalidate', // 优先用缓存，后台更新
        options: {
          cacheName: 'start-url-cache',
        },
      },
      // 可以再加一个匹配index.html的规则
      {
        urlPattern: /index\.html$/,
        handler: 'CacheFirst',
        options: {
          cacheName: 'start-url-cache',
        },
      }
    ],
    // 其他已有配置...
  })
  

2. 配置离线页面的路由 fallback #

要让用户在离线时访问任何路由都能跳转到/offline页面，需要添加navigateFallback和相关规则：

new WorkboxPlugin.GenerateSW({
  swDest: 'sw.js',
  navigateFallback: '/offline', // 所有导航请求失败时 fallback 到离线页
  // 排除API等不需要fallback的路径（可选）
  navigateFallbackDenylist: [/^\/api\//],
  // 确保离线页被缓存
  additionalManifestEntries: [
    { url: '/offline', revision: '12345' } // 手动添加离线页到预缓存清单
  ],
  // 其他已有配置...
})

注意：如果你的离线页面是.html文件，要确保它被Webpack正确打包输出到指定路径，Workbox才能找到它。

3. 完善Service Worker激活配置 #

为了让新的Service Worker立即生效，避免旧缓存影响，记得加上skipWaiting和clientsClaim：

new WorkboxPlugin.GenerateSW({
  swDest: 'sw.js',
  skipWaiting: true, // 新SW立即激活，替换旧SW
  clientsClaim: true, // 新SW接管所有已打开的客户端
  // 其他配置...
})

完整配置示例 #

把以上配置整合起来，最终的WorkboxPlugin配置大概是这样：

new WorkboxPlugin.GenerateSW({
  swDest: 'sw.js',
  skipWaiting: true,
  clientsClaim: true,
  include: [/index\.html$/, /offline\.html$/],
  navigateFallback: '/offline',
  navigateFallbackDenylist: [/^\/api\//],
  runtimeCaching: [
    {
      urlPattern: /^\/$/,
      handler: 'StaleWhileRevalidate',
      options: {
        cacheName: 'start-url-cache',
      },
    }
  ],
  additionalManifestEntries: [
    { url: '/offline', revision: '12345' }
  ]
})

调整完配置后，重新构建项目，然后清空浏览器缓存、重新注册Service Worker，再去审核应该就能解决问题了。

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