使用Vite PWA Plugin时Service Worker未注册且报404错误求助

• 确认vite-plugin-pwa基础配置是否正确

  • 先检查是否已安装插件：执行npm install vite-plugin-pwa --save-dev（或yarn/pnpm对应命令）
  • 确保vite.config.js中正确引入并配置插件，示例如下：

    import { VitePWA } from 'vite-plugin-pwa'
    
    export default {
      plugins: [
        VitePWA({
          registerType: 'autoUpdate', // 新手优先选用自动注册模式
          workbox: {
            globPatterns: ['**/*.{html,js,css,ico,png,svg}'] // 定义需要缓存的文件类型
          }
        })
      ]
    }
    

• 优化Service Worker注册代码

  • virtual:pwa-register已经内置了浏览器兼容性判断，无需额外写"serviceWorker" in navigator，建议添加回调日志方便排查问题：

    import { registerSW } from 'virtual:pwa-register'
    import React from 'react'
    import ReactDOM from 'react-dom/client'
    import App from './App'
    
    ReactDOM.createRoot(document.getElementById('root')).render(
      <React.StrictMode>
        <App />
      </React.StrictMode>
    )
    
    registerSW({
      onRegistered(reg) {
        console.log('Service Worker 注册成功:', reg)
      },
      onRegisterError(err) {
        console.error('Service Worker 注册失败:', err)
      }
    })
    

• 确认运行环境与调试面板状态

  • Service Worker仅支持HTTPS环境（localhost除外），生产环境必须部署在HTTPS服务上
  • 开发环境必须用vite命令启动，不能直接打开本地静态HTML文件
  • 打开开发者工具Application > Service Workers面板，查看注册状态、错误信息，同时取消勾选Bypass for network（避免跳过Service Worker）

• 检查缓存配置与文件生成

  • 若需在开发环境调试缓存功能，在vite.config.js中开启devOptions：

    VitePWA({
      devOptions: {
        enabled: true // 开发环境启用Service Worker
      }
    })
    

  • 生产打包后（执行vite build），检查dist目录是否生成sw.js和workbox-*.js文件，这是缓存功能生效的前提

• 清理旧缓存与Service Worker

  • 打开开发者工具Application > Storage，点击Clear site data，清除所有站点数据后重新加载页面，避免旧缓存干扰新配置

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