1. vite-plugin-pwa 是什么？

vite-plugin-pwa 是一个专门为 Vite 项目打造的 PWA（Progressive Web App）插件，它可以非常方便地帮你：

• 自动生成 service worker
• 自动注册和更新 service worker
• 生成 manifest.webmanifest
• 支持缓存策略、离线访问、推送通知等高级功能

GitHub 地址 vite-plugin-pwa

2. 安装方式

npm install vite-plugin-pwa --save-dev
# 或者
pnpm add -D vite-plugin-pwa

在 vite.config.ts 里引入：

import { VitePWA } from 'vite-plugin-pwa'
export default {
plugins: [
VitePWA()
]
}

3. 基本使用

简单配置一个标准 PWA：

VitePWA({
registerType: 'autoUpdate',
includeAssets: ['favicon.svg', 'robots.txt', 'apple-touch-icon.png'],
manifest: {
registerType: "prompt", // 很重要，不然 dev 环境不会自己 prompt
strategies: "generateSW",
includeAssets: ["favicon.svg", "robots.txt", "apple-touch-icon.png"],
manifest: {
name: "萌萌哒草头将军的App",
short_name: "萌萌哒草头将军的App",
description: "T萌萌哒草头将军的App",
theme_color: "#ffffff",
icons: [
{
src: "test.png",
sizes: "192x192",
type: "image/png",
},
{
src: "test.png",
sizes: "512x512",
type: "image/png",
},
],
},
}
})

然后你运行命令：

# 先打包
pnpm run build
# 后预览
pnpm run preview

点击地址栏出现的下载按钮，会出现一个下载弹窗，说明配置成功！

4. 核心功能

自动生成 manifest 文件

无需手动写 manifest.json，在 VitePWA 配置 manifest 字段，它自动生成到
/dist/manifest.webmanifest。

自动生成 service worker

支持两种模式：

默认是 generateSW，也可以切换。

自动注册 service worker

通过 registerType 配置：

VitePWA({
registerType: 'autoUpdate' // 服务端检测到新的 SW 版本时自动更新
})

也支持：

• prompt —— 手动提示用户更新
• autoUpdate —— 后台自动更新

离线缓存（Cache Assets）

可以自动缓存：

• 页面路由
• 静态资源（js/css/png）
• 自定义指定的文件

支持 Workbox 的所有缓存策略，比如：

• CacheFirst
• NetworkFirst
• StaleWhileRevalidate

高级玩法

workbox: {
runtimeCaching: [
{
urlPattern: ({ request }) => request.destination === 'image',
handler: 'CacheFirst',
options: {
cacheName: 'images-cache',
expiration: {
maxEntries: 10,
maxAgeSeconds: 60 * 60 * 24 * 30, // 30天
},
},
},
]
}

离线提示页面（Offline Fallback）

当网络断开时，访问 404 或请求资源失败，可以跳到自定义离线页面：

VitePWA({
workbox: {
navigateFallback: '/offline.html',
}
})

后台推送通知（Push API）

PWA 支持推送，配合第三方服务（如 Firebase、OneSignal）可以做推送通知。

需要配置：

• 通知权限
• Service Worker 监听 push 事件

支持热更新（HMR）

在开发环境下，修改 PWA 配置或者页面，插件也能快速热更新，不用手动重启。

5. 进阶功能

除了上面的基本功能外，还支持：

• 多语言 manifest： 根据请求语言动态切换 manifest
• 预缓存（precache）：配置哪些文件在安装时就缓存
• 定制 Service Worker： 手动编写复杂逻辑
• 集成到 VitePress、Nuxt、Astro： 官方有完整适配文档

篇幅有限，就不一一例举了！

最后

vite-plugin-pwa 绝对是给 Vite 项目加 Buff 的神兵利器，无论是离线体验、推送通知还是热更新体验，都非常值得一试！

今天的分享就这些了，感谢大家的阅读，如果文章中存在错误的地方欢迎指正！