自动重新加载

有了这种行为，一旦浏览器检测到您的应用程序的新版本，那么，它将更新缓存，并将重新加载所有浏览器窗口/选项卡，并自动打开应用程序以获得控制权

警告

为了重新加载所有选项卡/窗口客户端，你需要导入插件提供的虚拟模块:如果你没有使用任何虚拟，就没有办法与应用程序 ui 交互，因此，任何选项卡/窗口客户端都不会重新加载(旧的 service worker 仍将控制应用程序)。

自动重新加载不是自动页面重载，如果你想自动页面重载，你需要在应用程序入口点中使用以下代码：

import { registerSW } from 'virtual:pwa-register';

registerSW({ immediate: true });

使用这种行为的缺点是，用户可能会在一些浏览器窗口/选项卡中丢失数据，那些应用程序正在打开的，和那些正在填写表单的。

如果您的应用程序有表单，我们建议您更改行为，使用默认 prompt 选项，以允许用户决定何时更新应用程序的内容

危险

在您将应用程序投入生产之前，您需要确定您希望 service worker 的行为。将 service worker 的行为从 autoUpdate 更改为 prompt 可能会很痛苦。

插件配置

要想插件强制 workbox.clientsClaim 和 workbox.skipWaiting 选项置为 true。

您必须在您的 vite.config.ts 文件中添加 registerType: 'autoUpdate' 到 vite-plugin-pwa插件选项:

VitePWA({
  registerType: 'autoUpdate',
});

清除过期缓存

service worker 会把你所有的应用资源存储在浏览器缓存(或一组缓存)中。每次你对应用进行修改并重新构建时，service worker 也会被重新构建，包括在它的预缓存清单中所有新修改的资产，这些资产的版本也会发生变化(所有被修改的资产都会有一个新版本)。没有被修改过的资产也会被包含在 service worker 的预缓存清单中，但它们的修订版本不会改变。

预缓存清单条目修改

预缓存清单条目的修订只是资产内容的哈希 MD5 ，如果资产没有被修改，那么计算出来的哈希将始终相同

当浏览器检测并安装新版本的应用程序时，它将在缓存中存储所有新资产和旧资产。要删除旧的资产(先前不再需要的版本)，您必须在插件配置的workbox条目中配置一个选项。

当使用 generateSW 策略时，无需配置，插件会默认激活

我们强烈建议您不要停用该选项。如果你却是想要禁用，可以在插件配置中使用以下代码来禁用它:

import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    VitePWA({
      workbox: {
        cleanupOutdatedCaches: false,
      },
    }),
  ],
});

Inject Manifest Source Map 自v0.18.0+新选项

信息

从 v0.18.0+开始，你可以在 injectManifest 配置选项中使用 minify、sourcemap 和enableWorkboxModulesLogs，查看 New Vite Build 部分了解更多详情。

由于您正在构建自己的 service worker，这个插件将使用 Vite 的 build.sourcemap 配置选项，默认值为 false 来生成源码映射

如果您想为 service worker 生成源码映射，则需要为整个应用程序生成源码映射

生成 SW 源码映射

从插件版本 0.11.2 开始，service worker 的源码映射将不会被生成，因为它使用了 vite 配置选项build.sourcemap来构建，默认情况下为 false

当 vite 的build.sourcemap配置选项为true、'inline'或'hidden'时，并且你没有配置workbox.sourcemap选项，service worker 的源码映射将被生成。如果你配置了workbox.sourcemap选项，插件将不会改变该值。

如果你想生成 service worker 的源码映射，你可以使用以下代码

import { VitePWA } from 'vite-plugin-pwa';

export default defineConfig({
  plugins: [
    VitePWA({
      workbox: {
        sourcemap: true,
      },
    }),
  ],
});

导入虚拟模块

使用此行为时，如果您需要在应用程序准备离线工作时向用户提示对话框，则必须导入 vite-plugin-pwa 插件暴露的虚拟模块。否则，您可以导入或忽略它。

如果你没有导入任何一个虚拟模块，自动重新加载仍然会工作

准备离线工作

您必须在 main.ts 或 main.js 文件中包含以下代码

import { registerSW } from 'virtual:pwa-register';

const updateSW = registerSW({
  onOfflineReady() {},
});

您需要在onOfflineReady回调中使用确认按钮向用户显示一个准备好脱机工作的对话框。

当用户点击 确认 按钮时，只需隐藏在 onOfflineReady 方法中的提示展示。

SSR/SSG

如果你使用SSR/SSG, 你需要导入 virtual:pwa-register 模块使用动态导入并且检查 window 是否 undefined.

你可以在src/pwa.ts 模块注册 service worker:

import { registerSW } from 'virtual:pwa-register';

registerSW({
  /* ... */
});

然后从 main.ts 中导入它:

if (typeof window !== 'undefined') import('./pwa');

更多信息请查看常见问题解答

自动重新加载 ​

插件配置 ​

清除过期缓存 ​

Inject Manifest Source Map 自v0.18.0+新选项 ​

生成 SW 源码映射 ​

导入虚拟模块 ​

准备离线工作 ​

SSR/SSG ​