鸿蒙内置版本升级模块:更新检测、下载、安装适配
- 2026-10-27 16:42:37
应用上线之后，版本迭代是常态。新版本修了bug、加了功能，怎么推给用户？自己做一套更新系统，要搭服务器、存安装包、写下载逻辑、处理断点续传，工作量不小。鸿蒙内置了版本升级模块，从检测更新、下载安装到升级策略，全套能力都提供了，不用自己从头造轮子。
本文基于最新鸿蒙API，把版本升级的完整流程讲清楚：怎么检测新版本、下载进度怎么监听、安装怎么适配，代码可以直接复制到项目里跑。
01 版本升级能力概览
鸿蒙的版本升级能力由@kit.UpgradeKit提供，核心是UpdateClient客户端。它帮你处理了几件事：
更新检测：查询当前应用有没有可用的新版本
下载安装包：后台下载APK/HAP，支持断点续传
状态监听：下载进度、安装状态、错误回调
升级策略：强制更新、可选更新、静默升级
底层依赖华为应用市场的升级通道，安装包托管在华为服务器上，不用自己搭文件服务。开发者只需要在AppGallery Connect后台上传新版本，代码里调用接口就能检测和下载。
使用前需要先在module.json5里配置权限：
"requestPermissions": [{"name": "ohos.permission.INTERNET","reason": "{this.downloadProgress}%`).fontSize(16).margin({ bottom: 10 })Progress({ value: this.downloadProgress, total: 100, type: ProgressType.Linear }).width('80%')} else {Button('立即更新').width('60%').onClick(() => {this.startDownload(getContext(this));})}}.width('100%').height('100%').justifyContent(FlexAlign.Center)}}
下载进度是百分比数值，0到100，直接绑定到进度条组件上就行。系统会自动处理断点续传，下载中途网络断了，下次打开会接着下，不用自己实现。
还有一个注意点：下载大安装包的时候，建议提示用户在WiFi环境下下载，不然流量费用户会投诉。可以判断当前网络类型，如果是蜂窝网络，先弹个提示确认再开始下载。
04 安装与升级策略
下载完成之后，系统会自动弹出安装界面，用户确认后开始安装。安装过程中应用会退出，安装完成后自动打开新版本。
升级策略有两种，按业务需要选：
可选更新：用户可以选择"稍后再说"，不强制升级。大部分普通版本用这种，用户体验好。
强制更新：老版本有严重bug，不升级不能用。这时候用户不更新就退出应用，不能跳过。
async function checkUpdateAndPrompt(context: common.Context) {const client = update.createUpdateClient(context);client.on('eventInfo', (result: update.UpdateResult) => {if (result.installState === 1) {// 判断是否强制更新，这个标识从服务器配置或者版本标记里来const isForceUpdate = result.versionCode > 100; // 示例：高于某版本号强制if (isForceUpdate) {// 强制更新：弹不可关闭的弹窗showForceUpdateDialog(context, result);} else {// 可选更新：弹可以关闭的弹窗showOptionalUpdateDialog(context, result);}}});await client.checkUpdate();}// 强制更新弹窗function showForceUpdateDialog(context: common.Context, info: update.UpdateResult) {// 自定义弹窗，不允许点击外部关闭// 内容：有新版本必须更新才能继续使用// 按钮：只有"立即更新"，没有"稍后"console.info('强制更新弹窗');}// 可选更新弹窗function showOptionalUpdateDialog(context: common.Context, info: update.UpdateResult) {// 自定义弹窗，可以关闭// 按钮："立即更新" 和 "稍后再说"console.info('可选更新弹窗');}
强制更新的标识不是升级接口给的，是自己定义的。一般做法是后端返回一个最低支持版本号，当前版本低于这个号就强制更新。或者在AppGallery后台上传版本的时候，标记这个版本是强制升级。
05 完整升级流程封装
把检测、下载、弹窗、策略都封装到一个工具类里，项目里直接调用。
import { update } from '@kit.UpgradeKit';import { common } from '@kit.AbilityKit';import { promptAction } from '@kit.ArkUI';class UpdateManager {private static instance: UpdateManager;private updateClient: update.UpdateClient | null = null;static getInstance(): UpdateManager {if (!UpdateManager.instance) {UpdateManager.instance = new UpdateManager();}return UpdateManager.instance;}// 检查更新，自动弹提示async checkAndPrompt(context: common.Context) {this.updateClient = update.createUpdateClient(context);this.updateClient.on('eventInfo', async (result) => {if (result.installState !== 1) {promptAction.showToast({ message: '当前已是最新版本' });return;}// 这里可以根据result判断是强制还是可选const needForce = result.versionCode >= 200;if (needForce) {await this.forceUpdateFlow(result);} else {await this.optionalUpdateFlow(result);}});try {await this.updateClient.checkUpdate();} catch (e) {console.error('检查更新失败:', e);}}// 可选更新流程private async optionalUpdateFlow(result: update.UpdateResult) {// 弹确认框，用户点确认再下载console.info('可选更新，用户确认后下载');// 实际项目里用AlertDialog实现}// 强制更新流程private async forceUpdateFlow(result: update.UpdateResult) {// 弹不可关闭的弹窗console.info('强制更新，必须下载安装');}// 开始下载async startDownload() {if (!this.updateClient) return;this.updateClient.on('downloadProgress', (progress) => {console.info('下载进度:', progress);});this.updateClient.on('installStatus', (status) => {if (status === update.InstallStatus.INSTALL_SUCCESS) {promptAction.showToast({ message: '更新完成' });}});await this.updateClient.startDownload();}}// 使用方式：在EntryAbility的onCreate里调用// UpdateManager.getInstance().checkAndPrompt(context);
这样封装之后，页面里只需要调一个checkAndPrompt方法，剩下的检测、弹窗、下载逻辑都在内部处理。
落地注意事项
**检测时机要合理。**不要一打开APP就弹更新提示，用户刚进来就被打断体验不好。建议在首页加载完成、用户操作了几秒之后静默检测，有更新再弹。
**大安装包提示WiFi。**安装包超过100M的话，蜂窝网络下下载会耗流量。开始下载前判断一下当前网络，如果是流量，弹个提示问用户要不要继续。
**更新日志要写清楚。**弹更新弹窗的时候，把版本更新说明列出来，用户知道更新了什么才愿意更。不要只写"新版本上线"，太敷衍了。
**失败要有重试。**下载失败了不能直接结束，要给用户重试的机会。网络波动很正常，失败点个按钮重新下就行。
小结
鸿蒙内置的版本升级模块，把检测、下载、安装这套流程都封装好了，不用自己搭服务、写断点续传。开发者只需要在AppGallery后台上传新版本，代码里调几个接口就能完成完整的升级流程。
实际项目中，把升级逻辑封装到统一的工具类，检测时机选好，强制和可选策略分清楚，下载进度给用户看明白。用户升级体验好了，新版本的覆盖率自然就上去了。
