要实现带“版本镜像”功能的离线持久化策略，核心是将service worker作为可控缓存代理层，按语义化版本（如v1.2.3）隔离缓存、预载资源、静默更新，全程纯前端可控。

要实现带“版本镜像”功能的离线持久化策略，核心是把 Service Worker 当作一个可控的缓存代理层，按语义化版本（如 v1.2.3）组织缓存空间，并确保每次版本变更时旧缓存自动清理、新资源精准预载、线上更新可后台静默完成。整个过程不依赖后端接口，纯前端可控。

版本命名与缓存隔离

每个应用版本对应唯一缓存名称，避免跨版本污染。例如：

• 缓存名格式建议为 `${APP_NAME}-v${VERSION}`，如 "gh-mirrors-de-v1.5.0"
• 在 install 事件中打开该缓存，只添加当前版本明确声明的资源列表
• 禁止复用旧缓存名，哪怕仅 patch 号变化（如 v1.5.0 → v1.5.1）也应启用新缓存名，保证强一致性

预缓存 + 版本清单校验

构建阶段生成一份静态 manifest.json，包含该版本所有需离线可用的资源路径及哈希值。Service Worker 加载时做两件事：

• 读取 manifest.json，调用 caches.open(cacheName).addAll() 预缓存全部条目
• 对关键 HTML 文件（如 /index.html）额外执行哈希比对：若缓存中 HTML 内容哈希与清单不符，拒绝使用该缓存，强制走网络回退（防止 HTML 被意外覆盖但缓存未更新）

fetch 拦截中的版本路由逻辑

在 fetch 事件中，根据请求目标和当前激活的缓存版本，动态决定响应来源：

• 对 document 类型请求（页面导航），始终优先匹配当前激活缓存中的 HTML；若缺失或校验失败，则发起网络请求，并在响应成功后克隆写入当前版本缓存
• 对 script/style/image 等静态资源，只查当前版本缓存；不命中则报 404，不降级到旧版本缓存（避免混用导致 JS/CSS 不兼容）
• 对 API 接口类请求（destination === 'empty' 且 URL 匹配 /api/），默认走网络，失败时可 fallback 到 IndexedDB 中按版本存储的模拟响应（需业务层配合）

版本切换与平滑过渡

当新版 Service Worker 安装完成，需协调页面更新行为：

• 在 waiting 状态时，通过 navigator.serviceWorker.addEventListener('controllerchange') 监听激活完成
• 向用户提示“新版本已就绪，刷新页面立即生效”，或自动触发 window.location.reload(true)
• 在 activate 事件中，遍历 caches.keys()，删除所有不含当前版本号的缓存（如 gh-mirrors-de-v1.4.*），释放空间