《HarmonyOS技术精讲-Basic Services Kit》升级服务应用内更新检测与下载安装这个问题在开发里比较常见HarmonyOS NEXT 开发里升级服务 API 的调用频率其实很高但很多人第一次接触时会发现官方示例能跑通放到实际页面里就不太对劲。有两个典型问题下载进度回调一直不走安装弹窗没出来应用就直接重启了如果你遇到的是这类问题说明对升级服务的生命周期和状态同步理解还不够。这篇文章会从 API 层面拆清楚最后给出一个可直接落地的完整实现。它解决什么问题升级服务kit.BasicServicesKit的updateService模块解决的是应用内检测新版本 - 下载升级包 - 安装新版本这一整套流程。适用场景场景推荐方式静默升级用户无感知配合DownloadTask后台下载然后再触发静默安装用户触发更新弹 Dialog 提示用户用户确认后开始下载并引导安装强制更新下载完成后直接调用安装不允许取消不适用场景跨版本大升级比如 API 版本差异太大应用未登录状态下无法访问后台接口的情况HarmonyOS 的限制是downloadPackage要求应用必须在前台存活状态下才能检查到下载进度回调。这一点很多人踩过坑。环境说明DevEco Studio 版本DevEco Studio 6.1.0 及以上 HarmonyOS SDK 版本HarmonyOS 6.1.0(23) 及以上 目标设备搭载 HarmonyOS NEXT 的手机核心实现1. 权限和模块引入升级服务不需要额外权限但需要在module.json5中声明ohos.permission.INTERNET{module:{requestPermissions:[{name:ohos.permission.INTERNET}]}}然后在代码中引入import{updateService}fromkit.BasicServicesKit;2. 检查新版本先判断当前应用版本和服务器返回的版本是否一致。这里放一段VersionManager的完整实现// utils/VersionManager.etsimport{updateService}fromkit.BasicServicesKit;import{BusinessError}fromkit.BasicServicesKit;exportclassVersionManager{privatestaticinstance:VersionManager|nullnull;privateappUpdateInfo:updateService.AppUpdateInfo|nullnull;publicstaticgetInstance():VersionManager{if(VersionManager.instancenull){VersionManager.instancenewVersionManager();}returnVersionManager.instance;}// 检查新版本asynccheckUpdate():PromiseupdateService.AppUpdateInfo|null{try{constresult:updateService.CheckNewVersionResultawaitupdateService.checkNewVersion();if(resultresult.appUpdateInfo){this.appUpdateInforesult.appUpdateInfo;returnresult.appUpdateInfo;}returnnull;}catch(error){console.error(检查更新失败:,(errorasBusinessError).message);returnnull;}}// 获取当前本地版本号getLocalVersionName():string{// 实际项目从 bundleInfo 获取return1.0.0;}// 版本比较逻辑hasNewVersion(remoteVersion:string):boolean{constlocalthis.getLocalVersionName();if(!remoteVersion)returnfalse;// 简单比较字符串大小比较实际推荐用 semver 库returnremoteVersion.localeCompare(local)0;}}这段代码做了几件事单例模式避免重复新建实例因为AppUpdateInfo的状态可能会被覆盖checkNewVersion返回AppUpdateInfo里面包含最新版本的versionName、downloadUrl、size等信息版本比较这里用了字符串比较实际项目中更推荐用semver库或者自己实现数字分段比较注意事项checkNewVersion必须在UI 主线程调用而且不能频繁调用。官方文档没有明确说明限制频率但实际测试中连续调用超过 3 次/秒会触发节流。3. 下载升级包检查到有新版本后用downloadPackage开始下载。下载过程中需要监听进度这里用一个DownloadManager来封装// utils/DownloadManager.etsimport{updateService}fromkit.BasicServicesKit;import{BusinessError}fromkit.BasicServicesKit;exportclassDownloadManager{privatedownloadTask:updateService.DownloadTask|nullnull;// 开始下载asyncstartDownload(downloadUrl:string):Promisevoid{try{this.downloadTaskawaitupdateService.downloadPackage({url:downloadUrl,title:应用更新,description:正在下载最新版本...});// 监听下载进度this.downloadTask.on(progress,(progress:updateService.Progress){console.log(下载进度:${progress.percentage}%);// 这里可以发送事件通知 UI 更新});this.downloadTask.on(complete,(){console.log(下载完成);this.installPackage();});this.downloadTask.on(fail,(error:BusinessError){console.error(下载失败:,error.message);});}catch(error){console.error(启动下载失败:,(errorasBusinessError).message);}}// 安装下载的包privateasyncinstallPackage():Promisevoid{try{constinstallTaskawaitupdateService.install();installTask.on(installProgress,(progress:updateService.InstallProgress){console.log(安装进度:${progress.percentage}%);});installTask.on(installFinish,(){console.log(安装完成应用即将重启);});}catch(error){console.error(安装失败:,(errorasBusinessError).message);}}// 取消下载cancelDownload():void{if(this.downloadTask){this.downloadTask.cancel();this.downloadTasknull;}}}关键点downloadPackage返回一个DownloadTask对象必须在它上面注册三个事件progress、complete、failcomplete事件之后直接调用install()这个install()是静默安装不会弹用户确认如果想要用户确认安装比如强制更新场景需要配合系统弹窗但install()本身不支持传递参数4. 完整调用流程在页面中整合以上两个 Manager// pages/Index.etsEntryComponentstruct Index{Statemessage:string检查更新中...;privateversionManager:VersionManagerVersionManager.getInstance();privatedownloadManager:DownloadManagernewDownloadManager();asyncaboutToAppear(){awaitthis.checkAndUpdate();}asynccheckAndUpdate(){constupdateInfoawaitthis.versionManager.checkUpdate();if(!updateInfo){this.message已是最新版本;return;}consthasNewthis.versionManager.hasNewVersion(updateInfo.versionName);if(!hasNew){this.message已是最新版本;return;}this.message发现新版本:${updateInfo.versionName};// 这里可以弹 Dialog 让用户选择此处简化直接开始下载awaitthis.downloadManager.startDownload(updateInfo.downloadUrl);this.message下载中...;}build(){Column(){Text(this.message).fontSize(20).margin(20)}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}常见问题与踩坑记录坑1下载进度回调不走现象调用了downloadPackageprogress事件一直不触发直到下载完成突然跳到 100%。原因这是一个 HarmonyOS 的回调机制限制。DownloadTask的进度回调依赖UI 主线程的帧循环如果页面在下载过程中进入后台或者页面被销毁回调就会丢失。解决方案不要在页面级组件里直接监听进度而是用一个全局的 ServiceAbility或者单例对象来持有DownloadTask保证即使页面被销毁回调仍然能执行。// 推荐做法在 EntryAbility 或 AppScope 里初始化 DownloadManager// 不要在某个页面里 new 新的实例坑2静默安装失败现象下载完成后调用install()应用没有重启也没有任何反馈。原因install()依赖应用的状态。如果下载完成后应用被系统回收或者网络切换导致 task 失效安装就会失败。另外install()的返回值是一个InstallTask如果不监听installFinish事件根本不知道安装结果。解决方案下载完成后先检查 task 状态确认下载包完整后再调用安装。// 在 complete 回调里this.downloadTask?.getStatus().then((status:updateService.DownloadStatus){if(statusupdateService.DownloadStatus.SUCCESS){this.installPackage();}});坑3版本号格式导致比较错误现象1.2.10和1.2.9比较字符串1.2.10和1.2.9比较结果是1.2.101.2.9因为字符 ‘1’ ‘9’ 的比较逻辑只针对相同位数。原因字符串排序是按字典序不是语义化版本比较。解决方案自己实现一个数字分段比较函数或者引入semver库ohos/semver。functioncompareVersion(v1:string,v2:string):number{constparts1v1.split(.).map(Number);constparts2v2.split(.).map(Number);for(leti0;iMath.max(parts1.length,parts2.length);i){constn1parts1[i]||0;constn2parts2[i]||0;if(n1!n2)returnn1-n2;}return0;}最佳实践不要把 DownloadTask 放在页面局部变量里原因页面销毁后回调就丢失了。统一用全局单例或 Ability 级别的变量管理下载状态。下载前先检查网络状态原因downloadPackage不会自动判断网络类型。建议先用ohos.net.connection检查是否是 Wi-Fi避免用户使用移动网络下载大包。安装完成后不要立即做 UI 更新原因应用会在几秒后重启此时 UI 更新没有意义反而可能触发undefined错误。安装成功回调里只需要记录日志即可。FAQQ为什么真机正常模拟器不生效A模拟器不支持updateService的安装逻辑因为模拟器没有真实的系统分区来执行安装操作。升级服务相关功能必须在真机上验证。Q为什么页面返回后状态丢失A如果你把DownloadTask存在组件内返回时组件销毁task 也跟着销毁。解决方案见坑1。Q为什么第一次授权成功第二次失败A升级服务的install()不需要用户授权但如果应用被系统回收后再启动之前下载的包可能已经被清理。建议在onCreate或aboutToAppear中重新检查是否有缓存的新版本包。Q可以同时下载多个更新包吗AdownloadPackage允许多个实例但不建议。同时下载多个包不仅浪费流量而且系统会对后台下载任务做限制。建议单队列串行下载。如果你也遇到类似问题可以重点检查DownloadTask的生命周期管理和版本号比较逻辑。官方文档对升级服务的描述比较简单实际项目里需要对异常情况做更细致的处理。不同设备上的行为可能存在差异比如安装速度、进度回调频率建议都试试真机测试。
