Vue 3 + Vite 做 PWA：用 vite-plugin-pwa 实现离线缓存与可安装

为什么是 PWA

把 Web 应用做成 PWA 后，用户可以把站点"安装"到桌面，离线也能打开最近访问过的页面，体验更接近原生。Vite 生态里 vite-plugin-pwa 把 Workbox 封装好了，配置成本低。

安装与基础配置

npm i -D vite-plugin-pwa

// vite.config.ts
import { VitePWA } from "vite-plugin-pwa";

export default defineConfig({
  plugins: [
    VitePWA({
      registerType: "autoUpdate",
      manifest: {
        name: "我的应用",
        short_name: "App",
        start_url: "/",
        display: "standalone",
        background_color: "#ffffff",
        theme_color: "#2563eb",
        icons: [
          { src: "icon-192.png", sizes: "192x192", type: "image/png" },
          { src: "icon-512.png", sizes: "512x512", type: "image/png" }
        ]
      },
      workbox: {
        globPatterns: ["**/*.{js,css,html,png,svg}"],
        runtimeCaching: [
          {
            urlPattern: ({ url }) => url.pathname.startsWith("/api/"),
            handler: "NetworkFirst",
            options: { cacheName: "api-cache" }
          }
        ]
      }
    })
  ]
});

在应用里注册与提示更新

插件会自动注入注册逻辑。如果你想在"有新版本"时提示用户刷新，可以用虚拟模块拿到注册对象。

// sw.ts
import { registerSW } from "virtual:pwa-register";

const updateSW = registerSW({
  onNeedRefresh() {
    if (confirm("有新版本，是否刷新？")) updateSW();
  },
  onOfflineReady() {
    console.log("已可离线使用");
  }
});

Vue 组件里感知在线状态

<template>
  <div>
    <span v-if="online">在线</span>
    <span v-else>离线（已缓存内容可用）</span>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from "vue";

const online = ref(navigator.onLine);
function sync() { online.value = navigator.onLine; }

onMounted(() => {
  window.addEventListener("online", sync);
  window.addEventListener("offline", sync);
});
onUnmounted(() => {
  window.removeEventListener("online", sync);
  window.removeEventListener("offline", sync);
});
</script>

工程注意点

开发环境默认不生成 Service Worker，用 devOptions.enabled: true 才能本地调试，但别把调试开关带上线。
接口缓存用 NetworkFirst，保证数据新鲜；静态资源用 CacheFirst 提速。
manifest 的图标尺寸要齐全，否则桌面安装时可能不显示。
更新策略选 autoUpdate 还是 prompt，取决于你能否接受静默刷新用户当前页面。