VitePress 添加 PWA 支持
🏷️ VitePress
PWA 全称是 渐进式 Web 应用,它是一种可以安装到系统,并具有像应用一样体验的新式 Web 应用。
对 VitePress 来说,添加 PWA 支持非常简单。
首先,安装 @vite-pwa/vitepress
插件:
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 插件,这样本地开发时也可以应用的方式访问网站了。
npm i https-localhost -D
注意
使用了 PWA 插件后,VitePress 的 prefetchLinks
配置项将失效。即使将 prefetchLinks
设置为 false
,页面加载后仍然会继续在后台下载其他页面的 JS 资源。
这个应该是 PWA 为了在离线的状态下仍然可用而做的优化。在页面不多的情况下,一般也不会禁用 prefetchLinks
,而且就算配置失效了影响也不大。
但如果网站的页面很多,虽然不会影响页面的加载速度,但会导致网站浪费很多网络流量。虽然每个页面的资源都不大,但累积下来就不少了。
暂时没有找到可以在 PWA 模式下关闭 prefetchLinks
的方法,如果知道的话请告诉我。