指南

介绍

将你的 VuePress 站点变成渐进式网络应用程序 (PWA)^[1]。

此插件使用 workbox-build 生成 Service Worker 文件，并使用 register-service-worker 注册 Service Worker。

注意

如果你启用过该插件，并想要禁用它，你可能需要 `@vuepress/plugin-remove-pwa 来移除现有的 Service Worker 。

A PWA uses a Service Worker ^[2] (SW for short) to cache and proxy site content.

一个 PWA 使用 Service Worker ^[2:1] (简称 SW) 来缓存并代理网站内容。

网络 App 清单

为了使你的网站符合 PWA 的要求，一个网络 App 清单^[3]文件是必要的，并且你的 PWA 应满足可安装性^[4]要求。

你可以通过设置 manifest 选项来自定义 manifest 文件，或者在 public 文件夹中提供 manifest.webmanifest 或 manifest.json。前者优先级更高。

插件会自动为你生成 manifest.webmanifest，并在每个页面的 <head> 中添加清单链接声明，但是 你至少应该通过 manifest.icons 或 PWA 插件中的其他选项设置一个有效的图标。

注意

可安装性^[4:1]规范要求 manifest 中至少声明一个有效的图标。

所以如果你不配置 manifest.icons，访问者只能享受到 Service Worker 缓存带来的离线可访问性，而并不能作为 PWA 进行安装。

此外，该插件默认不处理清单中的任何内容，而是按原样输出。这意味着，如果你计划部署到子目录，则应自行将 URL 前缀附加到自己的清单 URLs 中。如果你需要的所有内容都在 base 文件夹下，你可以在插件选项中设置 appendBase: true 让插件将 base 自动附加到任何地址。

缓存控制

为了更好的控制 Service Worker 可以预缓存的内容，插件提供了相关的缓存控制选项。

默认缓存

默认情况下插件会预缓存所有的 JS 和 CSS 文件，但仅缓存主页和 404 页面的 HTML。插件同时还会缓存字体文件 (woff, woff2, eot, ttf, otf) 和 SVG 图标。

图片缓存

如果你的站点只有少量重要图片，并希望它们在离线模式下显示，你可以通过设置 cacheImage 选项为 true 来缓存站点图片。

我们通过文件后缀名识别图片，任何以 .png, .jpg, .jpeg, .gif, .bmp, .webp 结尾的文件都会视为图片。

HTML 缓存

当你网站体积不大，并且希望文档完全离线可用时，你可以通过设置 cacheHTML 为 true 来缓存所有 HTML 页面。

为什么默认不缓存非主页和 404 页面

虽然说 VuePress 为所有的页面通过 SSG^[5] 生成了 HTML 文件，但是这些文件主要用于 SEO^[6]，并能够让你在后端不做 SPA^[7] 配置的情况下能够直接访问任何链接。

VuePress 本质上是一个 SPA。这意味着你只需要缓存主页并从主页进入即可正常访问所有页面。所以默认不缓存其他 HTML 能够有效减小缓存大小 (可以缩减大约 40% 的体积)，加快 SW 更新速度。

但是这样做也有缺点，如果用户直接从非主页进入网站，首个页面的 HTML 文件仍需要从互联网加载。同时离线环境下，用户只能通过主页进入再自行导航到对应页面，直接访问某个链接会出现无法访问的提示。

大小控制

为了防止在预缓存列表中包含大文件，任何 > 2 MB 的文件或 > 1 MB 的图片都将被忽略。你可以通过 maxSize 和 maxImageSize 来自定义大小限制 (单位为 KB)。

更新控制

我们提供 update 选项控制用户如何接收更新。

update 选项的默认值是 "available"，这意味着当网站内容更新后，新的 SW 会在后台静默安装，并在安装结束后弹窗提示用户新内容就绪。用户可以自主选择是否立即刷新查看新内容。这意味在新 SW 就绪前用户会访问旧版本网站。

如果你的文档仍在建设期，希望尽早提示用户他可能在阅读已过时的内容，你可以将其设置为 "hint"。这样用户在进入文档后数秒内就可以收到新内容已发布的通知。但这样做的负面效果是如果用户在新 SW 就绪前选择更新，那么他将在新 SW 安装并接管页面前，需要从互联网获取页面的全部资源。

如果你的文档很稳定，或者你在托管博客，不太关心用户立即接收到最新版本，你可以将其设置为 "disabled"，这意味着新的 Service Worker 将在后台完全静默安装并在安装后等待，当旧版本 Service Worker 控制的页面全部关闭后，新 Service Worker 将在下次访问时接管并提供新内容给用户。此设置可以避免用户在访问中被弹窗打扰。

如果你希望通过 Service Worker 来加速用户在弱网或无网条件下的访问，但同时希望用户时刻访问新内容，你可以将此选项设置为 "force"。这意味着检测到新 Service Worker 后旧 Service Worker 将会被立刻销毁并且页面会被刷新以确保用户浏览最新内容。最大的缺点就是当新 Service Worker 发布后，用户在重新进入网站后的几秒内会遇到预期之外的突然刷新，并且他们将必须通过互联网访问文档并完全重新安装最新的 Service Worker。

更新提示弹窗

当检测到新内容 (检测到新的 Service Worker) 时，更新提示弹窗将会出现；当新内容就绪时，更新就绪弹窗将会出现。

如果你对默认的弹窗不满意，你可以自行编写组件更换。从 @vuepress/plugin-pwa/client 中导入 PwaFoundPopup 或 PwaReadyPopup 并使用其 slot 来自定义弹窗内容，然后将组件路径传递给 foundComponent 或 readyComponent 选项。

<script setup lang="ts">
import { PwaFoundPopup } from '@vuepress/plugin-pwa/client'
</script>
<template>
  <PwaFoundPopup v-slot="{ found, refresh }">
    <div v-if="found">
      已找到新内容
      <button type="button" @click="refresh">刷新</button>
    </div>
  </PwaFoundPopup>
</template>

<script setup lang="ts">
import { PwaReadyPopup } from '@vuepress/plugin-pwa/client'
</script>
<template>
  <PwaReadyPopup v-slot="{ isReady, reload }">
    <div v-if="isReady">
      新内容已就绪
      <button type="button" @click="reload">应用</button>
    </div>
  </PwaReadyPopup>
</template>

其他选项

插件还提供了其他 PWA 相关选项，比如微软磁贴图标与颜色设置，苹果图标等。如果你是一个高级用户，你也可以设置 generateSwConfig 来配置 workbox-build。查看插件选项了解更多细节。