vite-plugin-pwa 开发模式下 Service Worker 路径问题解析

在 vite-plugin-pwa 0.19.4 及之前版本中，当项目配置了 base 路径时，开发模式下 Service Worker 的注册会出现路径错误问题。本文将详细分析该问题的成因、影响以及解决方案。

问题现象

当开发者配置了如下 vite 设置时：

{
  base: "/my/app/",
  plugins: [
    VitePWA({
      strategies: "injectManifest",
      devOptions: {
        enabled: true
      }
    })
  ]
}

并在代码中按照文档注册 Service Worker：

const baseName = "/my/app/";
const serviceWorkerPath = import.meta.env.MODE === "production" 
  ? `${baseName}sw.js` 
  : `${baseName}dev-sw.js?dev-sw`;

开发模式下会出现 Service Worker 404 错误。经调试发现，实际生成的 dev-sw.js 文件路径为 https://my-machine/my/app//my/app/dev-sw.js，而浏览器尝试加载的路径却是 https://my-machine/my/app/dev-sw.js。

问题根源

该问题的根本原因在于 vite-plugin-pwa 在开发模式下解析 dev-sw.js URL 时，错误地处理了 base 路径。具体表现为：

1. 在开发插件中解析 dev-sw.js URL 时，vite 移除了 base 路径部分
2. 导致生成的 dev-sw.js URL 为 /dev-sw.js?dev-sw
3. 但实际需要匹配的路径应为 dev-sw.js?dev-sw
4. 最终导致返回空内容且 Content-Type 为 text/html

解决方案

vite-plugin-pwa 已在 0.19.5 版本中修复此问题。开发者只需升级到最新版本即可解决该路径问题。

对于暂时无法升级的项目，可以采用以下临时解决方案：

1. 修改 base 配置，移除尾部斜杠：

base: '/my/app'

2. 在 PWA 配置中明确禁用自动注册：

VitePWA({
  injectRegister: false
})

3. 使用环境变量获取 base URL：

const baseName = import.meta.env.BASE_URL;

最佳实践

为避免类似问题，建议开发者：

1. 始终使用最新版本的 vite-plugin-pwa
2. 使用 import.meta.env.BASE_URL 而非硬编码 base 路径
3. 在开发环境下仔细检查 Service Worker 的注册路径
4. 定期检查项目依赖的更新情况

该问题的修复体现了 vite-plugin-pwa 团队对开发体验的持续优化，确保开发者在使用自定义 base 路径时也能获得一致的开发体验。