Nuxt结合Vite-PWA实现离线功能遇阻求助

我花了好几个小时尝试给Nuxt配置vite-pwa模块，原以为很简单结果卡壳了，特来求助。

我开发的是一款支持离线运行、可添加到手机主屏/电脑桌面的简易Nuxt应用，核心需求是用户在飞机、隧道这类离线环境下点击浏览器刷新按钮仍能正常使用。

现在的问题：

• Chrome里离线时只会显示默认无网络页面
• 打印$pwa对象时，所有属性（比如swActivated、offlineReady）都是false

我的nuxt.config.ts配置如下：

export default defineNuxtConfig({
   compatibilityDate: "2024-04-03",
   devtools: { enabled: false },
   modules: ["@vite-pwa/nuxt", "@nuxt/ui"],
   ssr: false,

   pwa: {
      registerType: "autoUpdate",
      manifest: {
         name: "Local First Nuxt",
         short_name: "LocalFirstNuxt",
         scope: "/",
         start_url: "/",
         theme_color: "#ffffff",
         background_color: "#ffffff",
         icons: [
            {
               src: "pwa-64x64.png",
               sizes: "64x64",
               type: "image/png",
            },
            {
               src: "pwa-192x192.png",
               sizes: "192x192",
               type: "image/png",
            },
            {
               src: "pwa-512x512.png",
               sizes: "512x512",
               type: "image/png",
            },
            {
               src: "maskable-icon-512x512.png",
               sizes: "512x512",
               type: "image/png",
               purpose: "maskable",
            },
         ],
      },
      workbox: {
         globPatterns: ["**/*"],
      },
      includeAssets: ["**/*"],
      client: {
         installPrompt: true,
      },
      devOptions: {
         enabled: true,
         type: "module",
      },
   },
});

另外我已经在App.vue中配置了pwamanifest，麻烦各位帮忙看看问题出在哪。

排查与解决步骤 #

1. 调整Workbox缓存策略 #

当前workbox.globPatterns: ["**/*"]范围太宽泛，且未明确HTML文件的缓存策略，Workbox默认不会优先缓存HTML资源。建议修改配置，确保核心页面能被缓存：

workbox: {
  globPatterns: ['**/*.{js,css,html,png,ico}'],
  runtimeCaching: [
    {
      urlPattern: ({ url }) => url.pathname === '/' || url.pathname.endsWith('.html'),
      handler: 'StaleWhileRevalidate',
      options: {
        cacheName: 'static-html-cache',
      },
    },
  ],
}

2. 验证Service Worker状态 #

打开Chrome DevTools的Application标签，进入Service Workers面板：

• 确认SW是否处于activated状态
• 若注册失败，查看控制台报错，重点排查PWA图标路径是否正确（图标需放在public根目录下）

3. 确保$pwa对象的使用时机正确 #

$pwa的属性需在Service Worker激活后才会变为true，要在组件的onMounted钩子中打印：

<script setup>
import { onMounted } from 'vue'
const nuxtApp = useNuxtApp()

onMounted(() => {
  console.log('$pwa状态:', nuxtApp.$pwa)
})
</script>

4. 切换到生产环境测试 #

开发环境下devOptions.enabled: true会导致SW缓存行为异常，先执行nuxt build打包，再用nuxt preview启动生产环境服务测试离线功能。

5. 移除手动配置的pwamanifest #

@vite-pwa/nuxt会自动生成manifest文件，无需在App.vue中手动配置。打包后检查dist目录下的manifest.webmanifest，确认图标路径和配置项是否正确。

内容的提问来源于stack exchange，提问作者Peter