2026-11-03-miniapp-force-update.md 6.4 KB

小程序新版本强制更新功能设计

  • 日期:2026-11-03
  • 状态:设计定稿(待派发)
  • 需求方:廖总
  • 来源:「小程序增加新版本强制更新功能,在有新版本发布时,如果用户本地还是老版本,提醒用户强制升级」

0. 现状核查(只读)

  • cfc-frontend 全仓 grep getUpdateManager 零命中 → 当前无任何版本更新检测逻辑。
  • manifest.json 有 versionName: 1.0.0 / versionCode: 100,但代码未读取利用(前端不依赖此值做判断)。
  • App.vue 的 onLaunch 已承载:splash 跳转、登录态恢复、分享参数捕获、跨小程序 SSO。更新检测应尽早接入,且 applyUpdate() 会重启整个小程序,须独立于路由逻辑。
  • 微信小程序代码包更新仅微信官方机制可触发(wx.getUpdateManager / uni.getUpdateManager),前端无法自行感知"线上已发新版"。

1. 方案选型

推荐:纯前端 · 官方 UpdateManager(本次实现)

微信官方机制 uni.getUpdateManager():

API 触发时机 用途
manager.onCheckForUpdate(cb) 启动后微信自动检查 回调 { hasUpdate }(仅日志用)
manager.onUpdateReady(cb) 新版本代码包下载完成 弹窗引导 → applyUpdate()
manager.onUpdateFailed(cb) 新版本下载失败(弱网/被拒) 提示删除重进
manager.applyUpdate() 主动调用 强制重启小程序并应用新包(官方"强制更新"手段)

微信在冷启动时自动检查代码包更新并静默下载,下载完成后才触发 onUpdateReady。applyUpdate() 会立即重启整机小程序用上新包——这是微信生态下"强制更新"的标准且唯一手段。

不采用:后端版本门禁(列为后续可选增强,本次不做)

"硬阻断老版本"(接口级拒绝旧版)需后端配合:接口返回特定 code(如 4999 版本过旧)→ api.js 拦截 → 弹窗引导升级。适用于接口重大不兼容。本次需求用前端标准方案即可覆盖,硬阻断待主理人拍板后单独立项。

2. 实现设计

2.1 新增 cfc-frontend/utils/checkAppUpdate.js

// 小程序新版本强制更新(微信官方 UpdateManager 机制)
// 文档:docs/superpowers/specs/2026-11-03-miniapp-force-update.md
export function checkAppUpdate() {
  // 能力探测:部分基础库/平台不支持
  if (typeof uni.getUpdateManager !== 'function') {
    console.warn('[update] 当前环境不支持 getUpdateManager,跳过更新检测')
    return
  }

  const manager = uni.getUpdateManager()

  manager.onCheckForUpdate(function (res) {
    // res.hasUpdate:仅用于日志,无新版本时不需要任何交互
    console.log('[update] 检查更新:', res.hasUpdate ? '有新版本' : '已是最新')
  })

  manager.onUpdateReady(function () {
    // 新版本下载完毕 → 强制弹窗(无取消按钮)→ 用户点确定即重启应用新包
    uni.showModal({
      title: '发现新版本',
      content: '小程序已发布新版本,点击「立即更新」后即可使用最新功能。',
      showCancel: false,        // 强制:用户必须更新才能继续
      confirmText: '立即更新',
      success: function () {
        manager.applyUpdate()   // 强制重启小程序并应用新版本代码包
      }
    })
  })

  manager.onUpdateFailed(function () {
    // 下载失败(弱网/存储不足/被微信拒)
    uni.showModal({
      title: '更新失败',
      content: '新版本下载失败,请检查网络后删除小程序重新进入。',
      showCancel: false,
      confirmText: '我知道了'
    })
  })
}

2.2 App.vue 接入

在 onLaunch 开头(任何路由跳转/页面逻辑之前)调用一次:

import { checkAppUpdate } from '@/utils/checkAppUpdate.js'

export default {
  onLaunch: function (options) {
    // 尽早检测新版本:applyUpdate 会重启整机,须在路由逻辑前
    checkAppUpdate()
    // ... 既有 syncFontScale / restoreSession / splash 逻辑保持不变
  }
}

3. 关键约束与边界(开发必读)

  1. 环境限制(重要):onUpdateReady 仅体验版 / 正式版触发;开发版(envVersion=develop)因每次编译即最新,不会触发——属微信正常行为,非缺陷。开发自测时控制台会打印 [update] 已是最新 / 当前环境不支持,属预期。
  2. "强制"语义:通过 showCancel: false 实现软强制——用户不点「立即更新」就不能继续用当前页面,但已运行的老版本进程在重启前不会被系统杀掉。真正的"硬阻断"(完全禁止老版本)需后端门禁(见 §1),本次不做。
  3. 调用幂等:onLaunch 整个生命周期仅一次,无需防重。
  4. 不依赖 manifest 版本号:判断由微信后台代码包版本自动完成,versionName/versionCode 仅作发布运维规范(建议每次发布递增),前端逻辑不读取。
  5. 失败静默不阻塞:getUpdateManager 不可用 / 下载失败时只提示,不影响主流程。
  6. 不改既有业务逻辑:仅在 onLaunch 增加一行调用 + 新增一个 utils 文件,不动 splash / 登录 / 路由。

4. 测试与验证

  • 开发版不可测(微信限制):必须在体验版或正式版验证 onUpdateReady 弹窗与 applyUpdate 重启。
  • 验证路径:提交新版本代码包到微信后台 → 旧版冷启动 → 后台静默下载 → 弹出「发现新版本」→ 点「立即更新」→ 小程序重启并应用新包。
  • 弱网模拟:断网/弱网下 onUpdateFailed 应弹出"更新失败"提示。
  • 可在 checkAppUpdate 首行加 console.warn('[update] develop 跳过') 便于排查(production 下无影响)。

5. 任务书

  • 编号 T40(P1,module=cfc-frontend)
  • spec = 本文件
  • 改动文件:cfc-frontend/utils/checkAppUpdate.js(新增)、cfc-frontend/App.vue(onLaunch 接入一行)
  • 验收:npx vue-cli-service lint(或 uni 编译)通过;体验版部署后旧包冷启动能弹出强制更新弹窗并 applyUpdate 生效。

6. 待主理人拍板(非阻断)

  • 是否需要硬阻断(后端版本门禁,接口级拒绝老版本)?当前仅实现软强制(前端弹窗引导)。
  • 发布版本号递增规范是否纳入发布 checklist(manifest versionCode 每次 +1)。