VitePress 添加 PWA 支持

PWA 全称是渐进式 Web 应用，它是一种可以安装到系统，并具有像应用一样体验的新式 Web 应用。

对 VitePress 来说，添加 PWA 支持非常简单。

首先，安装 @vite-pwa/vitepress 插件：

bash

npm i @vite-pwa/vitepress -D

之后在 VitePress 的 config 文件中将自己的配置通过 withPwa 方法包装一下，并在其中添加 PWA 相关的配置项。

import { defineConfig } from 'vitepress'
import { withPwa } from '@vite-pwa/vitepress'

export default withPwa(defineConfig({
  // 自己的 VitePress 配置

  // PWA 配置
  pwa: {
    mode: 'development',
    registerType: 'autoUpdate',
    injectRegister: 'script-defer',
    includeAssets: ['favicon.svg'],
    manifest: {
      name: '佳佳的博客',
      short_name: 'JiaJia Blog',
      theme_color: '#ffffff',
      icons: [
        {
          src: 'pwa-192x192.png',
          sizes: '192x192',
          type: 'image/png',
        },
        {
          src: 'pwa-512x512.png',
          sizes: '512x512',
          type: 'image/png',
        },
        {
          src: 'pwa-512x512.png',
          sizes: '512x512',
          type: 'image/png',
          purpose: 'any maskable',
        },
      ],
    },
    workbox: {
      globPatterns: ['**/*.{css,js,html,svg,png,ico,txt,woff2}'],
      // 这个配置默认是 2M，如果网站文件很多，打包的文件大小若超过这个值，build 会失败，可以根据自己需要调整
      // maximumFileSizeToCacheInBytes: 5 * 1024 * 1024
    },
    experimental: {
      includeAllowlist: true,
    },
    devOptions: {
      enabled: true,
      suppressWarnings: true,
      navigateFallback: '/',
    },
  },
}))

刚开始看了官网仓库主页的文档，以为只要添加一个空的 pwa: {} 配置就可以了，结果没有任何效果。上面的配置主要摘自官网示例的配置文件。

在 public 目录添加配置中使用的图片后，项目发布就可以在 Chrome 浏览器中看到安装应用的图标了。

同时使用 Mermaid 的场合

如果项目中已经使用了 vitepress-plugin-mermaid 插件，config 文件中的配置应该已经被 withMermaid 方法包装了一遍，此时在外面再套一层 withPwa 方法就可以了。

export default withPwa(withMermaid(defineConfig({
  // 自己的 VitePress 配置
  // PWA 配置
  pwa: {},
})))

本地开发时

由于 PWA 功能需要使用 HTTPS 协议才能正常工作，本地开发时可以选择安装 https-localhost 插件，这样本地开发时也可以应用的方式访问网站了。

bash

npm i https-localhost -D

注意

使用了 PWA 插件后，VitePress 的 prefetchLinks 配置项将失效。即使将 prefetchLinks 设置为 false，页面加载后仍然会继续在后台下载其他页面的 JS 资源。

这个应该是 PWA 为了在离线的状态下仍然可用而做的优化。在页面不多的情况下，一般也不会禁用 prefetchLinks，而且就算配置失效了影响也不大。

但如果网站的页面很多，虽然不会影响页面的加载速度，但会导致网站浪费很多网络流量。虽然每个页面的资源都不大，但累计下来就不少了。

暂时没有找到可以在 PWA 模式下关闭 prefetchLinks 的方法，如果知道的话请告诉我。

VitePress 添加 PWA 支持 ​

VitePress 添加 PWA 支持