Vite PWA插件在Nuxt 3中的离线缓存配置指南

问题背景

在使用Vite PWA插件为Nuxt 3应用添加PWA功能时，开发者常会遇到"non-precached-url"错误。这个错误表明Workbox无法找到预缓存的主页HTML文件，导致离线功能无法正常工作。

核心问题分析

该问题的根本原因是Nuxt 3默认不会为根路径"/"生成静态HTML文件，而Vite PWA插件需要这些文件来实现离线缓存功能。当用户离线访问应用时，Service Worker无法找到缓存的HTML文件，就会抛出这个错误。

解决方案

1. 配置Nitro预渲染

在Nuxt配置文件中，需要显式指定预渲染根路径：

export default defineNuxtConfig({
  nitro: {
    prerender: {
      routes: ['/']
    }
  }
})

这个配置会强制Nuxt在构建时生成根路径的HTML文件，使其能够被Service Worker缓存。

2. 正确配置PWA选项

确保PWA配置中没有不必要的工作箱(Workbox)设置覆盖默认行为：

pwa: {
  manifest: {
    name: '应用名称',
    short_name: '短名称',
    theme_color: '#ffffff',
    scope: '/',
    start_url: '/'
  },
  // 避免覆盖默认的globPatterns配置
  workbox: {
    globPatterns: [] // 不要设置此项
  }
}

3. 处理manifest文件

避免手动创建manifest.webmanifest文件，让Vite PWA插件自动生成：

• 移除项目中手动创建的manifest文件
• 确保所有manifest相关配置都在pwa选项中完成

4. 处理App.vue配置

如果使用了资源生成器，需要调整App.vue中的配置：

<template>
  <NuxtPage />
</template>

5. 排除特定URL缓存

如果遇到"bad-precaching-response"错误，可以在PWA配置中排除特定URL：

pwa: {
  workbox: {
    navigateFallbackDenylist: [/^\/api/]
  }
}

验证步骤

1. 构建应用后检查输出目录，确认存在index.html文件
2. 检查生成的sw.js文件，确认包含根路径的缓存条目
3. 在Chrome开发者工具中检查Service Worker是否正确注册
4. 测试离线访问功能是否正常工作

总结

通过正确配置Nuxt的预渲染和Vite PWA插件，可以解决离线缓存问题。关键点包括确保根路径被预渲染、避免覆盖默认的Workbox配置、让插件自动处理manifest文件。这些配置共同确保了PWA功能在各种浏览器环境下的稳定运行。