系统自动更新说明

背景

前端项目发版后，浏览器标签页中运行的仍是发版前加载的旧资源，若不做处理，用户可能长时间停留在旧版本页面，甚至因新旧接口不兼容出现异常。公司内部主要有两套系统承载这一能力：商家系统（对外，商家使用）与 BOSS 系统（对内，运营/客服使用），二者的更新体验目前并不一致，因此整理本说明统一认知，避免排查问题时被“为什么商家系统有提示、BOSS 系统没有”这类差异干扰。

商家系统 vs BOSS 系统对比

系统自动更新现状

商家系统

• 通过轮询检测首页版本变化，触发 更新提示框，提醒用户执行更新；
• 新版本发布后通常可较快感知，不需要长时间等待；
• 用户可选择「立即更新」或「稍后更新」，减少因强制刷新导致的表单数据丢失风险，减少手动刷新操作。

BOSS 系统

• 新版本发布后，需等待静态资源拉取完成后才会自动刷新，等待时间相对较长；
• 当前没有 更新提示框；
• 该提示能力曾有规划，但因优先级调整暂未落地；
• 若要与商家系统体验一致，需同步更新策略与缓存策略，并补充「稍后更新」这类不打断用户操作的交互。

PWA 模式说明

两个系统均依赖离线缓存/PWA 插件，该插件基于 Service Worker 管理静态资源缓存，支持两种更新模式：

两种模式的取舍本质上是「打断用户操作 vs 及时更新」之间的权衡：

• 自动更新适合无长表单、操作链路短的场景（如 BOSS 系统的管理类操作页面通常可重新进入不丢数据）；
• 手动提示更新适合有长表单、长流程的场景（如商家系统下单、编辑类页面），避免用户正在填表时被强制刷新导致数据丢失。

关于两种模式的技术实现细节（Service Worker 注册、registerType: 'prompt' 与 autoUpdate 的选型依据、needRefresh/updateServiceWorker 用法等），可参考知识库中的专题文章：

• 网站更新：发版后提示用户刷新（轮询与 PWA）

技术实现示意

两种更新模式在 Service Worker 层的核心差异，可以用下面的配置示意来说明（具体字段以实际使用的 PWA 插件版本为准）：

// vite.config.ts（示意）
VitePWA({
  registerType: "autoUpdate", // BOSS 系统：新版本资源就位后自动切换
  // registerType: "prompt", // 商家系统：需用户确认后再切换
  workbox: {
    cleanupOutdatedCaches: true,
  },
});

商家系统在 prompt 模式下，前端通常需要监听 needRefresh 状态并手动触发 updateServiceWorker()：

const needRefresh = ref(false);

// 由 PWA 插件注册回调触发
function onNeedRefresh() {
  needRefresh.value = true; // 驱动更新提示框展示
}

function confirmUpdate() {
  updateServiceWorker(true); // 用户点击「立即更新」后执行
}

BOSS 系统在 autoUpdate 模式下无需上述交互层代码，新资源缓存完成后由插件自动完成切换与刷新。

推荐策略

1. 两端更新模式应与页面操作风险匹配：长表单/长流程页面优先用 prompt 手动确认；纯查看/短操作页面可考虑 autoUpdate，但仍建议保留最基础的用户感知（如提示条），避免用户完全无感知地被刷新；
2. 同一项目不要叠加两套检测方案（如轮询版本号 + PWA Service Worker 同时启用），否则会出现重复弹窗，参考 网站更新：发版后提示用户刷新 中的实践检查清单；
3. BOSS 系统若要补齐提示框，建议直接复用商家系统已验证的手动提示更新模式，保持两个系统更新体验一致，降低内部用户的认知负担；
4. 发版流程中应明确旧 chunk 的保留策略：发版后短期内保留旧的静态资源，减少已打开页面的用户遇到 404 或加载失败的概率；
5. 不使用离线缓存/PWA 插件的场景，版本发布后用户可能需要手动清理缓存或强制刷新页面，应在发版公告中明确提示，作为兜底说明。

回归检查清单

• 商家系统发布新版本后，更新提示框 能正常弹出，点击「立即更新」后页面刷新至新版本；
• 商家系统点击「稍后更新」后，提示框可正常关闭，且不影响当前表单内容与操作流程；
• BOSS 系统发布新版本后，静态资源拉取完成能自动刷新到新版本，刷新时机在可接受等待范围内；
• 两套系统均不存在「轮询版本号 + PWA 自动检测」同时启用导致重复弹窗/重复刷新的情况；
• 发版后短期内旧 chunk 仍可访问，已打开页面的用户切换路由或提交表单时不出现 404 或资源加载失败；
• 弱网环境下验证更新提示框展示与「立即更新」按钮响应正常，不出现长时间卡死。

常见疑问

1. 为什么不直接把 BOSS 系统也改成手动提示更新？
   BOSS 系统页面大多为内部管理操作，多数场景下重新进入不会丢失用户数据，采用自动更新可以让内部用户始终使用最新版本，减少「用旧版本反馈问题」的沟通成本；改为手动提示反而会增加内部用户的多余操作。
2. 两套更新机制会不会导致内部用户使用体验割裂？
   目前确实存在体验差异，这也是文中建议 BOSS 系统补齐提示框的原因；在补齐之前，建议在内部培训或帮助文档中说明两者差异，避免用户误以为 BOSS 系统「有 bug 不提示更新」。
3. 发版后多久可以下线旧版本的静态资源？
   建议至少保留一个观察周期（如覆盖到公司作息的完整一到两个工作日），确保绝大多数已打开页面的用户已完成一次自然刷新或主动更新后，再考虑清理旧资源。

总结

1. 两套系统的更新能力都建立在离线缓存/PWA 插件基础之上，商家系统采用手动提示更新，BOSS 系统采用自动更新，二者机制不同源于业务操作风险的差异；
2. 若要统一体验，优先方向是让 BOSS 系统补齐更新提示框，而不是让商家系统改为自动更新（因其存在长表单场景，强刷风险更高）；
3. 具体的技术方案选型与实现细节，请参考知识库《网站更新（一）（二）》两篇专题文章，避免重复摸索已验证过的方案。

相关链接

• 网站更新：发版后提示用户刷新（轮询与 PWA）
• 新商家系统性能优化实践
• 同业主重复单提醒规则