Vite PWA 在 Vercel 部署中的缓存问题解决方案

在使用 Vite PWA 插件开发渐进式 Web 应用时，许多开发者在 Vercel 平台上部署时会遇到一个常见的缓存问题：每次新版本部署后，浏览器仍然加载旧版本的 index.html 和资源文件，导致 MIME 类型错误或 404 错误。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象分析

当开发者在 Vercel 上部署 Vite PWA 应用的新版本时，用户浏览器可能会出现以下两种典型错误：

1. MIME 类型错误：浏览器控制台显示"Failed to load module script: Expected a JavaScript module script but the server responded with a MIME type of 'text/html'"错误
2. 资源加载失败：某些资源文件返回 404 状态码

这些问题的根本原因是浏览器缓存机制与 Service Worker 更新机制之间的冲突。Vercel 默认会对静态资源进行缓存优化，而 PWA 的 Service Worker 也会缓存资源，两者叠加导致了版本更新时的资源不一致问题。

解决方案详解

要彻底解决这个问题，需要在 Vercel 部署配置中正确设置缓存控制头。以下是经过验证的有效配置方案：

vercel.json 配置

{
  "headers": [
    {
      "source": "/(.*).html",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "no-store"
        }
      ]
    },
    {
      "source": "/sw.js",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "public, max-age=0, must-revalidate"
        }
      ]
    },
    {
      "source": "/manifest.webmanifest",
      "headers": [
        {
          "key": "Content-Type",
          "value": "application/manifest+json"
        }
      ]
    },
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}

配置解析

1. HTML 文件缓存控制：将 index.html 设置为 no-store，确保浏览器总是从服务器获取最新的 HTML 文件
2. Service Worker 文件：对 sw.js 设置 max-age=0 和 must-revalidate，强制浏览器检查更新
3. Web Manifest 文件：明确设置正确的 Content-Type，避免 MIME 类型问题
4. 静态资源文件：对 assets 目录下的资源设置长期缓存（1年）并标记为 immutable，优化加载性能

部署后操作

配置完成后，还需要在 Vercel 仪表板中执行以下操作：

1. 进入项目设置
2. 找到"存储"或"缓存"相关选项
3. 手动清除 Vercel 的数据缓存

这一步骤确保服务器端的缓存也被清除，避免新旧版本资源混合的问题。

本地开发注意事项

即使在本地开发环境中使用 vite preview 命令时，也可能遇到类似问题。这是因为：

1. 浏览器缓存了旧版本的 Service Worker
2. 预览服务器可能没有正确配置缓存头

解决方案是在开发者工具中手动点击"Skip Waiting"按钮，或者完全卸载旧的 Service Worker。

最佳实践建议

1. 在开发阶段，保持 Chrome 开发者工具中的"Disable cache"选项启用
2. 实现完善的更新提示机制，引导用户刷新页面获取新版本
3. 考虑使用 workbox-window 库来更精细地控制 Service Worker 的更新流程
4. 对于关键资源，可以在文件名中加入内容哈希，确保浏览器能正确识别版本变化

通过以上配置和措施，可以确保 Vite PWA 应用在 Vercel 平台上能够平滑地进行版本更新，避免缓存导致的各种问题，同时又不牺牲应用的加载性能。