Vite Plugin PWA – 零配置构建现代渐进式Web应用
概述
vite-plugin-pwa 是一个为 Vite 提供 PWA（Progressive Web Apps）功能的零配置插件。它结合了 Web 和原生应用的优点，为用户提供更优质的应用体验。该插件支持多种框架，包括 Vue、React、Svelte、SolidJS、Preact 等。
主要特性
- 零配置：为常见用例提供合理的默认配置
- 可扩展：暴露完整的自定义插件行为能力
- 类型安全：使用 TypeScript 编写
- 离线支持：通过 Workbox 生成支持离线的 Service Worker
- 完全可摇树优化：自动注入 Web App Manifest
- 新内容提示：内置支持 Vanilla JavaScript、Vue 3、React、Svelte、SolidJS 和 Preact
- Stale-while-revalidate：当有新内容可用时自动重新加载
安装
# npm
npm install vite-plugin-pwa -D# yarn
yarn add vite-plugin-pwa -D# pnpm
pnpm add vite-plugin-pwa -D基础使用
配置 Vite
在 vite.config.js 或 vite.config.ts 文件中添加插件：
import { defineConfig } from "vite";
import { VitePWA } from "vite-plugin-pwa";export default defineConfig({plugins: [VitePWA()],
});类型定义
在 tsconfig.json 中添加类型定义：
{"compilerOptions": {"types": ["vite/client", "vite-plugin-pwa/client"]}
}或在 vite-env.d.ts 文件中添加：
/// <reference types="vite-plugin-pwa/client" />注册 Service Worker
在应用入口文件中注册 Service Worker：
import { registerSW } from "virtual:pwa-register";registerSW({// 每小时检查一次更新onRegistered: (r) => r && setInterval(async () => await r.update(), 3600000),// 注册失败时输出错误onRegisterError: (error) => console.error(error),
});配置选项
基础配置
VitePWA({// 注册类型：'autoUpdate' | 'prompt'registerType: "autoUpdate",// 输入目录srcDir: "./src",// 输出目录outDir: "./dist",// 是否在开发模式下启用devOptions: {enabled: true,},
});Web App Manifest 配置
VitePWA({manifest: {name: "我的 PWA 应用",short_name: "PWA App",description: "一个使用 Vite Plugin PWA 构建的应用",theme_color: "#ffffff",background_color: "#ffffff",display: "standalone",orientation: "portrait",scope: "/",start_url: "/",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 配置
VitePWA({workbox: {// 全局模式匹配globPatterns: ["**/*.{css,js,html,svg,png,ico,txt,woff2}"],// 运行时缓存配置runtimeCaching: [{// API 请求缓存urlPattern: ({ url }) => url.pathname.startsWith("/api"),handler: "CacheFirst",options: {cacheName: "api-cache",expiration: {maxEntries: 10,maxAgeSeconds: 60 * 60 * 24, // 1天},cacheableResponse: {statuses: [0, 200],},},},{// 图片缓存urlPattern: /\.(?:png|jpg|jpeg|svg|gif|webp)$/,handler: "CacheFirst",options: {cacheName: "images-cache",expiration: {maxEntries: 60,maxAgeSeconds: 60 * 60 * 24 * 30, // 30天},},},],},
});框架集成
Vue 3
<script setup>
import { onMounted } from "vue";
import { registerSW } from "virtual:pwa-register";onMounted(() => {registerSW({onNeedRefresh() {console.log("需要刷新");},onOfflineReady() {console.log("应用已准备离线使用");},});
});
</script>React
import { useEffect } from "react";
import { registerSW } from "virtual:pwa-register";function App() {useEffect(() => {registerSW({onNeedRefresh() {console.log("需要刷新");},onOfflineReady() {console.log("应用已准备离线使用");},});}, []);return <div>我的 PWA 应用</div>;
}高级配置
自定义 Service Worker
VitePWA({strategies: "injectManifest",srcDir: "src",filename: "sw.ts",workbox: {// 自定义配置},
});开发模式配置
VitePWA({devOptions: {enabled: true,type: "module",},
});禁用 PWA 功能
VitePWA({disable: process.env.NODE_ENV === "development",
});最佳实践
缓存策略选择
- CacheFirst：适用于静态资源（图片、字体、CSS、JS）
- NetworkFirst：适用于 API 请求
- StaleWhileRevalidate：适用于需要实时性的内容
图标配置
确保提供多种尺寸的图标：
icons: [{ src: "icon-192.png", sizes: "192x192", type: "image/png" },{ src: "icon-512.png", sizes: "512x512", type: "image/png" },
];更新策略
registerSW({onNeedRefresh() {// 显示更新提示if (confirm("发现新版本，是否立即更新？")) {updateSW(true);}},
});错误处理
registerSW({onRegisterError(error) {console.error("SW 注册失败:", error);},onOfflineReady() {console.log("应用已准备离线使用");},
});常见问题
Q: 如何测试 PWA 功能？
A: 使用 Chrome DevTools 的 Application 标签页，可以查看 Manifest、Service Worker 和缓存状态。
Q: 如何更新 Service Worker？
A: 插件会自动处理更新，你也可以通过 registerSW 的回调函数自定义更新逻辑。
Q: 如何禁用 PWA 功能？
A: 设置 disable: true 或使用环境变量控制。
Q: 如何处理离线状态？
A: 通过 Workbox 的 runtimeCaching 配置缓存策略，确保关键资源在离线时可用。
总结
vite-plugin-pwa 是一个功能强大且易于使用的 PWA 插件，它提供了零配置的 PWA 功能，同时保持了高度的可定制性。通过合理配置，你可以轻松构建出具有离线能力、可安装的现代 Web 应用。
PWA 的核心是提升用户体验，确保你的应用在离线状态下仍能正常工作，并提供接近原生应用的体验。
Vite Plugin PWA - 零配置构建现代渐进式Web应用 - 高质量源码分享平台-免费下载各类网站源码与模板及前沿技术分享