PWA

Mr.Hope ... 2020-10-22

Feature
Pwa

大约 7 分钟

默认情况下，该主题将通过内置 vuepress-plugin-pwa1 (opens new window) 启用渐进式 Web 应用程序支持^[1]。

如果你不需要此功能或想使用其他 pwa 插件，则可以将 themeConfig.pwa 设置为 false 来禁用该插件。

# 内容缓存和更新

Service Worker ^[2] (简称 SW) 主要用于获取并托管网站内容。

PWA 插件会自动通过 workbox-build 注册 Service Woker。

为了更好地控制 Service Worker 可以预缓存的内容，插件提供了下列设置。

如果你是一个高级用户，你也可以直接设置 themeConfig.pwa.generateSwConfig 来将选项传递给 workbox-build。

# 默认缓存

默认情况下插件会预缓存所有与网站相关的文件: **/*.{html,js,css,svg}

同时插件还会缓存字体文件: **/*.{woff,woff2,eot,ttf,otf}。

# 缓存控制

基于可安装性^[3]的要求，插件提供了缓存控制的相关选项。

# 图片缓存

你可以通过设置 themeConfig.pwa.cachePic 选项为 true 来缓存站点图片。

如果您的站点体积不大，且配图大多为关键性说明，希望可以在离线模式下显示，建议将此项设置为 true。

图片识别

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

# HTML 缓存

当你网站体积过大时，你可以通过设置 themeConfig.pwa.cacheHTML 为 false 来仅缓存除主页和 404 错误页。

为什么可以移除

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

VuePress 本质上是一个 SPA。这意味着你只需要缓存主页并从主页进入即可正常访问所有页面。

当你站点页面数量或内容很多，包含 HTML 文件后体积过大时，你可以考虑将此项设置为 false，这样可以缩减大约 40% 的体积。缺点是用户在离线环境下只能通过主页进入再自行导航到对应页面。直接访问某个链接会出现网页错误的提示。

# 大小控制

为了防止在预缓存列表中包含大文件，任何大于 2MB 的文件或大于 1MB 的图片都将被删除。

你可以通过 themeConfig.pwa.maxSize 选项自定义缓存的最大文件大小 (单位 KB)，或通过 themeConfig.pwa.maxPicSize 来更改图片的大小限制 (单位: KB)。

# 更新弹窗

成功下载新内容后，我们将提供更新弹出窗口。

自定义弹窗

如果你对默认的弹窗不满意，你可以自行编写组件更换。你需要全局注册自己的弹窗组件，并将组件的名称传递给 themeConfig.pwa.popupComponent 选项。

# 清单文件生成

为了保证 PWA 的可安装性，网站需要生成清单文件，并通过 link 声明有效的 manifest 清单文件地址^[7]。

插件会在输出目录自动为你生成 Manifest 文件 manifest.webmanifest，同时还会添加清单地址声明到每一个 HTML 的 <head> 中。

如果你在 .vuepress/public 中已有一个 manifest.webmanifest 或 manifest.json，该插件将读取它并合并到最终 manifest 中。

# 自动生成

插件会尽可能的通过 VuePress 插件接口的信息，为 manifest 的大部分设置项设置 fallback，这意味着即使你无需设置 manifest 的大多数内容。

如果未设置下列选项，它们会按照顺序依次尝试回退到以下预设值。

选项	默认值
name	`siteConfig.title` \|\| `themeConfig.title` \|\| `'Site'`
short_name	`siteConfig.title` \|\| `themeConfig.title` \|\| `'Site'`
description	`siteConfig.description` \|\| `themeConfig.description` \|\| `'A site built with vuepress-theme-hope'`
lang	`siteConfig.locales['/'].lang` \|\| `themeConfig.locales['/'].lang` \|\| `"en-US"`
start_url	`context.base`
scope	`context.base`
display	`"standalone"`
theme_color	`"#46bd87"`
background_color	`'#ffffff'`
orientation	`'portrait-primary'`
prefer_related_applications	`false`

完整的配置项详见 Manifest 类型定义文件 (opens new window)

# 手动配置

你可以在 themeConfig.pwa.manifest 选项中手动指定 manifest 的各项内容。

优先级

themeConfig.pwa.manifest 选项的设置具有最高的优先级，之后是 public 文件夹下可能存在的 manifest 文件。

你至少应该通过 manifest.icons 或 PWA 插件中的其他选项设置一个有效的图标。 因为这是我们没法默认生成的。

注意

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

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

另外插件并不会处理 manifest 中的任何内容，而是原样输出它们。这意味着如果打算你部署到某个子目录，你则应自行添加 base 到 manifest 中的相应 URL。

# 其他选项

插件还提供了其他 PWA 相关选项，比如微软磁贴图标与颜色设置，苹果图标等。

你可以酌情根据需要设置它们。详细的选项请见 PWA 插件配置 (opens new window)。