#微信小程序更新提示

在 uni-app 中实现微信小程序更新提示，核心就是调用 uni.getUpdateManager() 获取更新管理器，然后监听 3 个关键事件：

• onCheckForUpdate：检查服务端是否存在新版本
• onUpdateReady：新版本已经下载完成，可以提示用户重启
• onUpdateFailed：新版本下载失败，方便记录日志或兜底处理

这套能力只在微信小程序端可用，因此实现时要加上平台判断，避免影响其他端。

#适用场景

当你发布了新的小程序版本后，已经打开旧版本的小程序用户并不会立刻感知到更新。此时就需要在应用启动阶段主动检测更新，在新版本下载完成后弹窗提示用户重启小程序。

常见诉求有两个：

• 用户进入小程序时自动检查新版本
• 检测到新版本后，给出“立即更新”提示

#实现思路

官方更新流程并不复杂：

1. 应用启动时获取 updateManager
2. 监听是否存在新版本
3. 新版本下载完成后，弹出确认框
4. 用户点击确认后调用 applyUpdate()，小程序会重启并应用新版本

uni-app 官方文档里明确说明，uni.getUpdateManager() 返回的是“全局唯一”的版本更新管理器对象，所以这段逻辑更适合放在应用启动阶段统一注册，而不是分散到多个页面中重复监听。

#封装 checkUpdate

可以把更新逻辑抽成一个独立工具函数，例如 utils/checkUpdate.js：

let hasRegisteredUpdateManager = false

export function checkUpdate() {
  // 只在微信小程序端执行
  // #ifndef MP-WEIXIN
  return
  // #endif

  if (!uni.canIUse('getUpdateManager')) {
    console.warn('当前微信版本过低，无法使用更新管理能力')
    return
  }

  // updateManager 是全局唯一对象，避免重复注册事件
  if (hasRegisteredUpdateManager) return
  hasRegisteredUpdateManager = true

  const updateManager = uni.getUpdateManager()

  updateManager.onCheckForUpdate(res => {
    console.log('检查更新结果：', res)

    if (res.hasUpdate) {
      console.log('检测到新版本，正在后台下载更新包')
    }
  })

  updateManager.onUpdateReady(() => {
    uni.showModal({
      title: '更新提示',
      content: '发现新版本，是否立即重启小程序并更新？',
      confirmText: '立即更新',
      cancelText: '稍后再说',
      success: res => {
        if (res.confirm) {
          updateManager.applyUpdate()
        }
      }
    })
  })

  updateManager.onUpdateFailed(error => {
    console.error('新版本下载失败：', error)
  })
}

#代码说明

#1. uni.canIUse('getUpdateManager')

先做兼容判断，避免低版本微信基础库或特殊环境下直接调用报错。

#2. hasRegisteredUpdateManager

虽然很多项目会把更新检查放在 App.vue 的 onLaunch 中，只执行一次，但实际开发里也经常会把它抽到公共初始化流程中。如果没有这层保护，重复调用时就可能重复绑定事件，导致弹出多次更新提示。

#3. onCheckForUpdate

这个回调只负责告诉你“有没有新版本”，并不代表更新包已经可以使用。真正可以提示用户更新的时机，是 onUpdateReady。

#4. onUpdateReady

当新版本已经下载完成后，弹出 uni.showModal。用户确认后调用 applyUpdate()，小程序会立即重启并应用新版本。

#5. onUpdateFailed

下载失败通常不会影响当前版本继续使用，但建议至少记录日志，方便排查网络异常、包体异常或发布流程问题。

#在 App.vue 中接入

更新检测推荐放在应用启动时执行一次。

<script>
import { checkUpdate } from '@/utils/checkUpdate'

export default {
  onLaunch() {
    checkUpdate()
  }
}
</script>

如果你的项目是其他初始化入口，也可以在应用级启动逻辑里调用，但原则不变：

• 尽量只注册一次
• 不要放在每个页面的 onLoad 里重复执行

#一个更稳妥的放置建议

如果你的项目有登录态初始化、远程配置拉取、埋点注册等应用级逻辑，可以把 checkUpdate() 归类到“应用启动初始化”阶段统一调用。这样更容易维护，也更符合更新检测的职责边界。

#注意事项

#1. 仅微信小程序端生效

uni.getUpdateManager() 不是跨端通用能力，文档里也标明它只适用于小程序平台能力范围内的更新管理。对于 uni-app 多端项目，建议通过条件编译或平台判断隔离这段逻辑。

#2. 不要把它理解成 App 热更新

这套能力管理的是微信小程序版本更新，不适用于 App 端整包升级，也不是 wgt 热更新方案。App 端更新要使用各自的升级方案。

#3. 用户取消后不会立即更新

当用户点击“稍后再说”时，当前版本会继续运行。通常下次冷启动小程序时，微信会再次进入更新检测流程，所以这里的交互文案要尽量清晰，不要让用户误以为已经完成升级。

#4. 真机验证更可靠

开发者工具里可以验证代码逻辑，但更新提示是否符合真实发布流程，最好还是结合体验版、开发版或线上版本在真机环境确认一遍。

#完整接入流程

1. 新建 utils/checkUpdate.js
2. 按上面的方式封装更新检测逻辑
3. 在 App.vue 的 onLaunch 中调用 checkUpdate()
4. 发布新版本后，在真机上验证更新弹窗和重启流程

#总结

在 uni-app 中实现微信小程序更新提示，本质上就是基于 uni.getUpdateManager() 做一次应用级封装：

• 启动时注册更新管理器
• 下载完成后弹窗提示用户更新
• 用户确认后调用 applyUpdate() 完成升级

如果你的项目已经有公共初始化模块，那么把这段逻辑抽成单独的 checkUpdate() 会更清晰，也更方便后续维护。

#参考资料

• uni.getUpdateManager() | uni-app 官网
• UpdateManager | 微信开放文档