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 的核心是提升用户体验，确保你的应用在离线状态下仍能正常工作，并提供接近原生应用的体验。