Vite-PWA 项目中视频缓存问题的深度解析与解决方案

前言

在基于 Vite-PWA 构建渐进式 Web 应用时，开发者经常会遇到视频资源缓存的问题。本文将深入探讨这一常见问题的成因，并提供多种可行的解决方案。

问题现象

当尝试通过 Service Worker 缓存视频资源时，开发者通常会遇到以下错误提示："Failed to execute 'put' on 'Cache': Partial response (status code 206) is unsupported"。这表明浏览器无法将部分响应(206状态码)存入缓存。

问题根源

这个问题的本质在于 HTTP 范围请求(Range Requests)机制。现代浏览器在播放视频时会采用流式加载技术，通过发送带有 Range 头的请求来分段获取视频内容。服务器会响应 206 Partial Content 状态码和相应的内容范围。

Service Worker 的 Cache API 设计上不支持直接存储部分响应，这就导致了上述错误。这种机制虽然优化了视频播放体验，却给缓存带来了挑战。

解决方案

方案一：配置 Workbox 参数

通过合理配置 Workbox 可以解决大部分视频缓存问题：

1. 启用 rangeRequests 选项
2. 设置适当的 cacheableResponse 状态码(包含 206)
3. 调整 maximumFileSizeToCacheInBytes 参数以适应视频大小

方案二：服务器端配置调整

确保服务器返回正确的响应头：

1. Access-Control-Expose-Headers 必须包含 content-range
2. 考虑禁用 accept-ranges 头以强制完整响应

方案三：客户端处理策略

1. 延迟视频加载直到 Service Worker 准备就绪
2. 使用 poster 属性提供占位图像
3. 通过 Blob 和对象 URL 手动处理视频资源

高级实现方案

对于需要更精细控制的场景，可以考虑实现自定义 Workbox 插件：

1. 拦截 206 响应并获取完整视频
2. 将完整视频存入缓存
3. 根据请求提供部分或完整内容

最佳实践建议

1. 对于小型视频，优先考虑预缓存
2. 大型视频采用运行时缓存策略
3. 始终提供适当的加载状态和回退方案
4. 在 manifest 中明确声明视频资源

总结

Vite-PWA 项目中的视频缓存问题虽然复杂，但通过理解 HTTP 协议细节和合理配置 Workbox，完全可以实现稳定可靠的视频缓存方案。开发者应根据具体项目需求选择最适合的解决方案，在性能和用户体验之间取得平衡。