1. 先说结论进度条背后不是UI问题是下载任务的全生命周期管理早几年我做应用商店类项目时接了一个需求用户在主App里点击某个合作方的App就能直接下载并安装下载过程必须展示进度条。我当时第一反应是这有什么难的系统下载完了广播通知一下UI更新个百分比不就完事了。等真的动手才发现下载App的App这件事的复杂度比我想象中高一个量级。进度条只是用户看得见的那一层真正难的是背后一整条下载任务链路任务怎么创建、状态怎么同步、网络断了怎么恢复、安装包校验怎么处理、不同Android版本的安装权限怎么兼容。这些环节只要有一个没想清楚进度条就会表现出各种诡异行为卡在99%、下载完成进度条不到100%、通知栏显示100%但是App内部还在转圈。这篇文章就是从实际项目里抽出来的核心实现思路适合准备做应用内下载器、应用商店、工具类App以及任何需要下载外部APK并展示进度的Android开发者参考。我会把进度条的实现拆开讲清楚数据从哪来、怎么更新、怎么做状态管理以及那些真机上才踩得到的坑。1.1 一个能下载App的App到底要做什么从用户视角看下载只是点一下按钮然后看进度条涨但作为开发者我们要处理的是下面这一长串问题发起下载拿到APK的下载地址创建一个下载任务。进度更新把已下载字节数/总字节数实时换算成百分比并在UI上刷新。状态变化下载中、暂停、恢复、失败、成功每一种状态都要有对应的界面反馈。文件落盘下载好的APK存放在哪里目录权限怎么处理。安装触发下载完成后调起系统安装界面或者直接静默安装非Root环境基本不可行。异常处理下载中断、存储空间不足、URL失效、网络异常、安装包损坏。这些环节其实可以抽象成一个状态机。进度条只是这个状态机的外在表现。如果你一开始就把重点放在怎么画一条好看的进度条上后面大概率要返工。1.2 为什么很多人的进度条会卡在99%我见过不少初学者用OkHttp配合Flow直接写下载结果总在最后一步出问题文件写完了回调方法也执行了但UI进度条就是停在99%。原因其实很简单很多人计算进度用的是downloadedSize / totalSize但是文件的totalSize是先从Content-Length拿到的有些服务器不会返回这个字段或者返回的长度和实际写入的字节数对不上这样就算到了最后一个块除法结果也可能到不了1.0。还有一种情况是进度条的更新频率和文件写入频率不一致。你每收到一块数据就更新一次UI主线程被频繁调用尤其是当App正在做其他事情的时候UI刷新就被系统调度延后了看起来就像卡住了。解决思路是要么等文件完全写完后再强制设置100%要么把进度刷新的逻辑做节流。这些细节后面展开讲但核心结论可以先给出来进度条卡住基本不是UI组件的问题是你在上游数据到达时没做好状态对齐。2. 技术选型为什么我选了DownloadManager而不是自研下载器做这个需求之前我在团队里先拉了一个方案对比。当时手上有几个选择自己用OkHttp写下载封装、用开源的RxDownload/AriaDownloader、直接用系统自带的DownloadManager。很多做App开发的朋友一听到自研两个字就觉得更可控但在下载器这个场景里可控是有代价的。2.1 常见方案的横向对比我根据自己的项目具体需求列了一张对比表方便大家参考方案优点缺点适用场景系统DownloadManager无需自己管理连接、支持系统通知栏进度、有断点续传、代码量小进度获取需要轮询或广播部分ROM定制后行为不一致无法做复杂header控制标准的APK下载、应用内更新OkHttp/RxDownload自研完全可控可以拿到每块数据进度精准支持多样化需求需要自己处理断点、文件IO、通知栏、存活度代码量大容易踩坑对下载行为有强定制需求第三方库AriaDownloader等功能全面断点续传、批量下载、Task等都有依赖复杂维护和升级需要跟进部分库已不再活跃下载任务多、场景复杂且愿意引入大依赖我当时做的项目下载量不大但是要求稳定优先级最高的是别出幺蛾子。所以最终选了系统DownloadManager。它最大的优势是下载任务交给系统进程去跑即使App被用户划掉下载也不会中断通知栏里还能自动显示一条永久性的进度通知。这对于App下载App的场景来说太关键了因为用户很可能在下载过程中切到别的应用我们不能要求用户把App一直挂在后台。2.2 DownloadManager能做什么、做不了什么DownloadManager本质上是一个系统级下载服务它可以用DownloadManager.Request来配置下载地址、保存路径、网络条件、通知栏可见性等。做应用商店类项目时我用它做APK下载很少出大问题但也要明确它的边界它只能负责下载到一个文件不能直接安装APK。安装还是要自己调Intent。它下载到应用外部目录时Android 10及以上有分区存储限制需要把目标路径指到getExternalFilesDir或者公共下载目录否则可能拿不到正确的路径。它的进度通知栏是系统控制的如果你不需要这份通知可以在Request里设置setNotificationVisibility为VISIBILITY_HIDDEN但如果进程被回收App内UI就没法更新进度所以要么你们保留通知栏要么实现进程内前台Service来保证UI存活。它不支持自定义鉴权头里的Cookie和User-Agent之外的复杂逻辑如果要带签名下载可能得退回到OkHttp方案。我采纳的折中方案是下载链路用DownloadManagerApp内的进度展示用ContentObserver监听下载状态数据库。这样既拿到了系统级的稳定又能自己控制UI刷新。3. 进度条数据从哪里来DownloadManager的监听机制与轮询优化使用DownloadManager时第一个问题就是如何拿到下载进度不像OkHttp回调里直接把bytesTransferred给你DownloadManager不会主动往App里推送数据它只会在系统数据库里更新状态。我们必须主动去“读”。3.1 注册BroadcastReceiver拿到基础状态最简单的一步是注册一个BroadcastReceiver监听DownloadManager.ACTION_DOWNLOAD_COMPLETE。这个广播会在下载完成包括失败时发出我们在onReceive里可以通过downloadId去查询具体状态以此判断是成功还是失败。需要注意这个广播在Android 13及以上如果是动态注册也还是可以收到但必须在App运行时注册。如果App进程已经被杀系统任务完成时你的BroadcastReceiver不会被拉起这也是很多人说我没收到完成广播的原因。其实对于下载完成这个动作更稳妥的方案是使用DownloadManager.query主动查询不要只依赖广播。我会在进入前台、读取到了新下载任务、或者从后台恢复时都做一次主动查询确保UI状态不滞后。3.2 轮询 getBytesDownloaded / getTotalSizeBytes 的正确姿势进度数据可以通过DownloadManager.Query来获取核心是两行代码val cursor downloadManager.query(query) if (cursor.moveToFirst()) { val bytesDownloaded cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR)) val bytesTotal cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_TOTAL_SIZE_BYTES)) val status cursor.getInt(cursor.getColumnIndex(DownloadManager.COLUMN_STATUS)) }但你要注意不能在主线程上高频调用query因为每次query都是跨进程查数据库虽然单次不算慢但如果引入Handler循环每个100ms查一次主线程很容易掉帧。我一开始就是这么干的结果在低端机上进度条没卡界面滑动先卡了。后来我改成线程池里跑一个定长任务每500ms查询一次查询到进度后通过LiveData或StateFlow把数据抛到UI层。如果下载速度很快进度条变化明显500ms的刷新频率已经足够如果下载对象是高版本的小体积APK几百KB时可能几秒就下完了那时甚至不需要轮询只要监听完成广播再刷新成100%即可。3.3 实测下来性能最优的刷新频率我试过100ms、300ms、500ms、1000ms四组频率在纯下载场景下100ms和500ms给用户看到的进度条平滑度差异很小但是资源消耗差了近5倍。300ms是一个视觉和性能的平衡点。如果你用Compose的animateFloatAsState做了数值动画300ms的原始进度更新就足够了因为UI本身会做插值看起来很流畅。最终我的实现是下载任务进行中每300ms在子线程更新一次数据如果App处于后台可以不轮询等回到前台时重建查询一次。这样既不会漏掉关键状态也不会白白耗电。4. 下载完成的最后一公里APK安装与Android版本适配下载完成后进度条到了100%故事并没有结束。系统DownloadManager把APK文件拉下来了接下来要做的是拿到文件的绝对路径然后调起系统安装界面。但这一步的坑比下载过程多得多。4.1 FileProvider配置和授权安装从Android 7.0开始直接使用Uri.fromFile()去打开一个APK安装文件会直接抛FileUriExposedException。这不是崩溃错误而是一种安全限制。解决方案是使用FileProvider来生成一个带临时授权的内容URI。通常需要在AndroidManifest.xml里声明providerprovider android:nameandroidx.core.content.FileProvider android:authorities${applicationId}.fileprovider android:exportedfalse android:grantUriPermissionstrue meta-data android:nameandroid.support.FILE_PROVIDER_PATHS android:resourcexml/file_paths / /providerfile_paths.xml里要配置对外暴露的文件目录。如果下载到的文件在getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)下面就写成paths external-files-path nameapp_downloads pathDownload/ / /paths然后调起安装程序的代码是val intent Intent(Intent.ACTION_VIEW) intent.setDataAndType(fileUri, application/vnd.android.package-archive) intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION) context.startActivity(intent)这里有两个容易忽略的点一是file_paths里的path不要写错写成绝对路径容易导致找不到文件二是有些机型尤其是MIUI、EMUI会额外在系统设置里有个通过USB安装或安装未知应用的开关如果没打开Intent会被系统静默拦截或者弹一个无法安装的提示。4.2 Android 10及以上的安装来源限制Android 10API 29引入了一个比较严格的限制如果一个App要安装未知来源应用必须在系统设置里被授予ACTION_MANAGE_UNKNOWN_APP_SOURCES权限。这不是运行时权限不能通过常规的requestPermissions弹窗直接申请而是要跳转到对应的设置页。通常的交互是用户点击安装按钮时先判断packageManager.canRequestPackageInstalls()如果不满足就跳转到设置页面val intent Intent( Settings.ACTION_MANAGE_UNKNOWN_APP_SOURCES, Uri.parse(package:$packageName) ) startActivity(intent)这块体验上有个优化空间你可以在用户首次点击下载时就检查这个权限而不是等下载完成后再检查。因为下载花了几分钟最后却卡在安装权限上用户会很恼火。我是在点击下载按钮时先检查如果要下载的是一个APK而且canRequestPackageInstalls()返回false就直接引导去授权。等下载完成时大概率权限已经通过了直接走安装就行。4.3 分应用内更新与商店更新的差异如果你的App是做一个应用内更新功能也就是更新自身逻辑会稍有不同。大多时候我们不是从系统DownloadManager拿文件而是建议使用Google Play In-app Updates或者如果你的产品是国内的走自己的APK下载更新。对于更新自身这种场景更关键的是版本比较逻辑不能只看versionCode大小还要考虑渠道、架构、最低支持版本。我在项目里吃过亏下载了一个高版本APK结果它在Android 8上不支持用户装完再点旧版App直接闪退。源头就是没有在下载前校验minSdkVersion。在App下载另一个App这种场景里安装包不一定和你同源更要注意签名校验。如果下载的是合作方App至少要校验md5或sha256防止下载到被篡改的包。DownloadManager本身不提供校验能力需要在下载完成后对文件做一次哈希计算和服务端下发的哈希值对比不一致就删除并提示用户重新下载。5. 真实工程里容易翻车的几个坑代码写出来能跑和真机上不出问题是两回事。下载功能尤其明显因为它依赖网络、存储、系统调度、ROM定制等多个外部因素。我在这个项目里踩过的坑罗列几个比较有代表性的希望你能绕开。5.1 网络切换后DownloadManager的假死遇到过这样一个线上问题用户在Wi-Fi环境下开始下载进度走到60%然后用户走到了公司门口手机自动切换到了4G网络结果进度条再也不动了。查了很多日志DownloadManager的状态显示STATUS_RUNNINGbytesDownloaded也不再变化看起来像僵死。实际原因是DownloadManager在默认配置下不会在移动网络下继续下载除非你明确设置了setAllowedOverMetered(true)。解决方法是创建Request时把网络条件放开request.setAllowedOverMetered(true) request.setAllowedOverRoaming(false)这样Wi-Fi切到移动数据时下载不会中断。但如果你想做更细腻的用户引导也可以监听ConnectivityManager的网络变化提示用户当前已切换至移动网络是否继续下载用户确认后再更新下载策略。不过DownloadManager一旦创建任务做这种暂停/恢复操作需要调用DownloadManager.remove再重新建任务这会丢失已下载的进度体验不好。所以我建议在确认用户接受流量消耗的前提下直接允许DownloadManager使用移动网络。5.2 存储权限被拒绝后的降级方案早期版本里我习惯把APK下载到Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS)也就是系统公共下载目录这样用户能方便看到下载好的安装包。但这样做需要申请WRITE_EXTERNAL_STORAGE权限在Android 10以后即使申请到了写入公共目录也有限制。后来我改成优先使用getExternalFilesDir这个目录不需要存储权限应用卸载时会跟着删除。如果你想保留系统下载目录的可见性又要规避权限问题可以用MediaStore.Downloads去创建公共下载项但Android 10和11的API差异又让人头疼。我的建议是普通App下载APK不要纠结存到公共目录。用户唯一需要关心的是下载完能安装而不是能在文件管理器里看到这个APK。存在App私有外部目录下一样可以安装。如果你确实需要让用户在文件管理器里能看到做一个拷贝到公共目录的可选操作即可不要让权限阻碍主流程。5.3 用抓包定位下载失败原因有一次用户反馈某些下载地址在浏览器里能打开但是在App里DownloadManager直接报STATUS_FAILED没有错误码。我去服务器那边排查发现下载链接是HTTPS的但服务器的TLS配置对某些Android版本的访问会在握手阶段直接断开。这种问题用日志难查直接用抓包工具看网络请求最方便。我用的方式是先让手机连上代理用抓包软件截获DownloadManager发起的HTTP请求。注意DownloadManager默认的User-Agent是系统自带的不是我们App的很多服务器对UA有判断如果看到不是常用浏览器UA可能返回403。这也是一个隐蔽原因。排查之后发现我们的情况是服务器CDN对UA做了限制解决方式是给DownloadManager的Request手动设置一个User-Agentrequest.addRequestHeader(User-Agent, AppDownloader/1.0)这个问题解决后那个地址的下载就正常了。如果你们是下载自己服务端的APK建议在服务端日志里考虑记录DownloadManager的UA方便定位这一类问题。5.4 通知栏进度与App内进度不一致的问题开了系统DownloadManager的通知栏进度后有时候会出现通知栏已经显示100%且消失App内的进度条只走到了90%。这是因为系统写入数据库的完成状态和App轮询读取之间有一个时间差你这次轮询恰好读到了旧的字节数而下载实际已经完成。要解决这个问题不能只依赖定时轮询。最终我采用的方案是每次轮询的同时判断数据库COLUMN_STATUS字段。如果状态已经是STATUS_SUCCESSFUL就直接把进度Set到100并触发后续逻辑不再沿用上一次读到的bytesTotal做除法。同时在ACTION_DOWNLOAD_COMPLETE广播到达时也要强制同步一次UI状态避免轮询的滞后。6. 把进度条做得丝滑UI刷新、进度计算与状态切换到了这一步基础功能已经完整了。但用户感知好不好往往就差在进度条是否顺滑、状态切换是否正确。下面说一些关于UI层的细节。6.1 进度不是百分比那么简单如果你的APK有50MB服务器不给Content-Length那么bytesTotal一开始可能是0。这时候你如果按照bytesDownloaded / bytesTotal去算进度要么除零要么百分比显示成0%直到下完才跳到100%。更好的做法是当bytesTotal 0时进度条改成加载中状态不显示具体百分比一旦拿到有效总大小再切换成百分比模式。还可以根据已经下载的字节数预估一个临时百分比比如已下载12.3MB但界面别硬显示成数字百分比否则会让用户困惑。如果你的下载包很大还可以考虑使用TransferListener式的分段回调把进度条分成下载中和安装准备中两个阶段。下载阶段显示0%~100%下载完成但还没开始安装时进度条可以显示一个无穷动画提示用户安装包校验中。这样比直接跳到100%更真实因为从下载完成到安装界面弹出来的等待时间并不为0。6.2 避免进度条回退的正确计算方式有些小伙伴遇到过进度条明明走到80%突然又跳回60%。这个问题通常不是数据读错了而是下载任务重启了。比如网络断开后DownloadManager自动重试bytesDownloaded会被重置或者你把任务重新提交了一次旧的查询结果和新的查询结果混在了一起。为了规避这种回退我当时的做法是在下载开始时保存downloadId并且记录一个最大已下载字节数。每次轮询拿到新值时如果新值小于旧值说明发生了重置这时不更新UI进度而是等它超过旧值以后再正常更新。这个方法很土但在当时的业务下确实有效。更好的方案是使用文件级别的断点续传但DownloadManager不支持自定义分片只能接管它的文件那又是一个复杂度的大坑。如果你的项目对进度条不能回退有强要求还是建议在创建任务前先判断是否存在旧任务存在则先remove再创建新任务避免两个任务并行。6.3 状态流转下载中/暂停/失败/成功的边界处理我再分享一个状态机设计。下载任务的UI层我维护了5种状态IDLE未开始DOWNLOADING下载中PAUSED暂停这个状态DownloadManager实际没有一个可靠的暂停API一般我们用取消任务来实现FAILED失败SUCCESS成功在代码里每次查询到状态后统一走一个dispatchState(status, progress)方法。这个方法里只做一件事根据当前状态决定要切换UI还是更新进度。一定不要在外面散落地写很多if分支否则最后你根本不知道是哪个分支把状态改错了。另外要考虑用户手动取消的路径。使用DownloadManager时取消任务的API是remove(downloadId)。这个操作会删除已经下载的部分文件如果用户只是想暂停再继续那就别用这个API否则之前下载的进度全白费了。更友好的做法是提供取消按钮而不是暂停按钮。如果真要暂停后恢复需要自己维护URL、已下载文件偏移量然后结合下载库/OkHttp实现断点这就是另一套方案了。7. 针对不同App场景的适配建议不是所有需要下载App的产品都适合用同一套方案。我在项目里也根据具体场景做了几档调整这里按业务类型拆一下。7.1 单包体积与下载速度对进度刷新策略的影响如果你的产品主要下载一些几MB的小工具App根本不需要做300ms轮询更新UI。下载可能2秒就完成了你甚至可以让按钮从下载变成打开之前给用户一个100%的瞬时反馈中间不做连续动画。反而轮询太密App会显得耗电。如果下载的是大型游戏包几百MB甚至上GB进度条反而不是最重要的更关键的是上传测速、剩余时间估算以及用户断网后的恢复。这种场景我建议直接上成熟的下载库哪怕是引入较大的依赖因为你要处理的东西太多了分片、校验、离线任务队列、存储管理都是系统DownloadManager给不了你的。经验是包越大、下载任务越重越不要尝试用DownloadManager 轮询来搞定一切。它可以覆盖简单场景但超过100MB的下载最好用专业下载框架做任务管理。7.2 我的最终建议一个下载器功能如果你不想返工开始写代码前先把这四件事想清楚下载任务由谁管理、进度数据如何传递、文件落盘在哪里、安装时权限链路如何走通。这四个问题想清楚代码框架基本就有了雏形。我在实际项目中最终选型是这样的简单场景下载一个APK走DownloadManager 定时轮询 广播兜底复杂场景批量下载、多任务、大文件走OkHttp 自定义下载线程池 Room保存任务记录。两者的UI层进度条逻辑完全相同只是数据源不一样。最后再分享一个小技巧下载进度条的UI组件不要用单一的数字百分比最好同时展示已下载大小 / 总大小和速度。用户看到进度条最关心的往往不是百分比而是到底在不在动。展示3.2MB/s这种实时速度比单纯让进度条往前跑更能建立安全感。我们上线这个版本后用户关于下载卡住的反馈肉眼可见少了很多。这里面的坑基本都是一步一步踩出来的。你如果能提前绕开应该能省下不少调试时间。
1. 先说结论进度条背后不是UI问题是下载任务的全生命周期管理早几年我做应用商店类项目时接了一个需求用户在主App里点击某个合作方的App就能直接下载并安装下载过程必须展示进度条。我当时第一反应是这有什么难的系统下载完了广播通知一下UI更新个百分比不就完事了。等真的动手才发现下载App的App这件事的复杂度比我想象中高一个量级。进度条只是用户看得见的那一层真正难的是背后一整条下载任务链路任务怎么创建、状态怎么同步、网络断了怎么恢复、安装包校验怎么处理、不同Android版本的安装权限怎么兼容。这些环节只要有一个没想清楚进度条就会表现出各种诡异行为卡在99%、下载完成进度条不到100%、通知栏显示100%但是App内部还在转圈。这篇文章就是从实际项目里抽出来的核心实现思路适合准备做应用内下载器、应用商店、工具类App以及任何需要下载外部APK并展示进度的Android开发者参考。我会把进度条的实现拆开讲清楚数据从哪来、怎么更新、怎么做状态管理以及那些真机上才踩得到的坑。1.1 一个能下载App的App到底要做什么从用户视角看下载只是点一下按钮然后看进度条涨但作为开发者我们要处理的是下面这一长串问题发起下载拿到APK的下载地址创建一个下载任务。进度更新把已下载字节数/总字节数实时换算成百分比并在UI上刷新。状态变化下载中、暂停、恢复、失败、成功每一种状态都要有对应的界面反馈。文件落盘下载好的APK存放在哪里目录权限怎么处理。安装触发下载完成后调起系统安装界面或者直接静默安装非Root环境基本不可行。异常处理下载中断、存储空间不足、URL失效、网络异常、安装包损坏。这些环节其实可以抽象成一个状态机。进度条只是这个状态机的外在表现。如果你一开始就把重点放在怎么画一条好看的进度条上后面大概率要返工。1.2 为什么很多人的进度条会卡在99%我见过不少初学者用OkHttp配合Flow直接写下载结果总在最后一步出问题文件写完了回调方法也执行了但UI进度条就是停在99%。原因其实很简单很多人计算进度用的是downloadedSize / totalSize但是文件的totalSize是先从Content-Length拿到的有些服务器不会返回这个字段或者返回的长度和实际写入的字节数对不上这样就算到了最后一个块除法结果也可能到不了1.0。还有一种情况是进度条的更新频率和文件写入频率不一致。你每收到一块数据就更新一次UI主线程被频繁调用尤其是当App正在做其他事情的时候UI刷新就被系统调度延后了看起来就像卡住了。解决思路是要么等文件完全写完后再强制设置100%要么把进度刷新的逻辑做节流。这些细节后面展开讲但核心结论可以先给出来进度条卡住基本不是UI组件的问题是你在上游数据到达时没做好状态对齐。2. 技术选型为什么我选了DownloadManager而不是自研下载器做这个需求之前我在团队里先拉了一个方案对比。当时手上有几个选择自己用OkHttp写下载封装、用开源的RxDownload/AriaDownloader、直接用系统自带的DownloadManager。很多做App开发的朋友一听到自研两个字就觉得更可控但在下载器这个场景里可控是有代价的。2.1 常见方案的横向对比我根据自己的项目具体需求列了一张对比表方便大家参考方案优点缺点适用场景系统DownloadManager无需自己管理连接、支持系统通知栏进度、有断点续传、代码量小进度获取需要轮询或广播部分ROM定制后行为不一致无法做复杂header控制标准的APK下载、应用内更新OkHttp/RxDownload自研完全可控可以拿到每块数据进度精准支持多样化需求需要自己处理断点、文件IO、通知栏、存活度代码量大容易踩坑对下载行为有强定制需求第三方库AriaDownloader等功能全面断点续传、批量下载、Task等都有依赖复杂维护和升级需要跟进部分库已不再活跃下载任务多、场景复杂且愿意引入大依赖我当时做的项目下载量不大但是要求稳定优先级最高的是别出幺蛾子。所以最终选了系统DownloadManager。它最大的优势是下载任务交给系统进程去跑即使App被用户划掉下载也不会中断通知栏里还能自动显示一条永久性的进度通知。这对于App下载App的场景来说太关键了因为用户很可能在下载过程中切到别的应用我们不能要求用户把App一直挂在后台。2.2 DownloadManager能做什么、做不了什么DownloadManager本质上是一个系统级下载服务它可以用DownloadManager.Request来配置下载地址、保存路径、网络条件、通知栏可见性等。做应用商店类项目时我用它做APK下载很少出大问题但也要明确它的边界它只能负责下载到一个文件不能直接安装APK。安装还是要自己调Intent。它下载到应用外部目录时Android 10及以上有分区存储限制需要把目标路径指到getExternalFilesDir或者公共下载目录否则可能拿不到正确的路径。它的进度通知栏是系统控制的如果你不需要这份通知可以在Request里设置setNotificationVisibility为VISIBILITY_HIDDEN但如果进程被回收App内UI就没法更新进度所以要么你们保留通知栏要么实现进程内前台Service来保证UI存活。它不支持自定义鉴权头里的Cookie和User-Agent之外的复杂逻辑如果要带签名下载可能得退回到OkHttp方案。我采纳的折中方案是下载链路用DownloadManagerApp内的进度展示用ContentObserver监听下载状态数据库。这样既拿到了系统级的稳定又能自己控制UI刷新。3. 进度条数据从哪里来DownloadManager的监听机制与轮询优化使用DownloadManager时第一个问题就是如何拿到下载进度不像OkHttp回调里直接把bytesTransferred给你DownloadManager不会主动往App里推送数据它只会在系统数据库里更新状态。我们必须主动去“读”。3.1 注册BroadcastReceiver拿到基础状态最简单的一步是注册一个BroadcastReceiver监听DownloadManager.ACTION_DOWNLOAD_COMPLETE。这个广播会在下载完成包括失败时发出我们在onReceive里可以通过downloadId去查询具体状态以此判断是成功还是失败。需要注意这个广播在Android 13及以上如果是动态注册也还是可以收到但必须在App运行时注册。如果App进程已经被杀系统任务完成时你的BroadcastReceiver不会被拉起这也是很多人说我没收到完成广播的原因。其实对于下载完成这个动作更稳妥的方案是使用DownloadManager.query主动查询不要只依赖广播。我会在进入前台、读取到了新下载任务、或者从后台恢复时都做一次主动查询确保UI状态不滞后。3.2 轮询 getBytesDownloaded / getTotalSizeBytes 的正确姿势进度数据可以通过DownloadManager.Query来获取核心是两行代码val cursor downloadManager.query(query) if (cursor.moveToFirst()) { val bytesDownloaded cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR)) val bytesTotal cursor.getLong(cursor.getColumnIndex(DownloadManager.COLUMN_TOTAL_SIZE_BYTES)) val status cursor.getInt(cursor.getColumnIndex(DownloadManager.COLUMN_STATUS)) }但你要注意不能在主线程上高频调用query因为每次query都是跨进程查数据库虽然单次不算慢但如果引入Handler循环每个100ms查一次主线程很容易掉帧。我一开始就是这么干的结果在低端机上进度条没卡界面滑动先卡了。后来我改成线程池里跑一个定长任务每500ms查询一次查询到进度后通过LiveData或StateFlow把数据抛到UI层。如果下载速度很快进度条变化明显500ms的刷新频率已经足够如果下载对象是高版本的小体积APK几百KB时可能几秒就下完了那时甚至不需要轮询只要监听完成广播再刷新成100%即可。3.3 实测下来性能最优的刷新频率我试过100ms、300ms、500ms、1000ms四组频率在纯下载场景下100ms和500ms给用户看到的进度条平滑度差异很小但是资源消耗差了近5倍。300ms是一个视觉和性能的平衡点。如果你用Compose的animateFloatAsState做了数值动画300ms的原始进度更新就足够了因为UI本身会做插值看起来很流畅。最终我的实现是下载任务进行中每300ms在子线程更新一次数据如果App处于后台可以不轮询等回到前台时重建查询一次。这样既不会漏掉关键状态也不会白白耗电。4. 下载完成的最后一公里APK安装与Android版本适配下载完成后进度条到了100%故事并没有结束。系统DownloadManager把APK文件拉下来了接下来要做的是拿到文件的绝对路径然后调起系统安装界面。但这一步的坑比下载过程多得多。4.1 FileProvider配置和授权安装从Android 7.0开始直接使用Uri.fromFile()去打开一个APK安装文件会直接抛FileUriExposedException。这不是崩溃错误而是一种安全限制。解决方案是使用FileProvider来生成一个带临时授权的内容URI。通常需要在AndroidManifest.xml里声明providerprovider android:nameandroidx.core.content.FileProvider android:authorities${applicationId}.fileprovider android:exportedfalse android:grantUriPermissionstrue meta-data android:nameandroid.support.FILE_PROVIDER_PATHS android:resourcexml/file_paths / /providerfile_paths.xml里要配置对外暴露的文件目录。如果下载到的文件在getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)下面就写成paths external-files-path nameapp_downloads pathDownload/ / /paths然后调起安装程序的代码是val intent Intent(Intent.ACTION_VIEW) intent.setDataAndType(fileUri, application/vnd.android.package-archive) intent.addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION) context.startActivity(intent)这里有两个容易忽略的点一是file_paths里的path不要写错写成绝对路径容易导致找不到文件二是有些机型尤其是MIUI、EMUI会额外在系统设置里有个通过USB安装或安装未知应用的开关如果没打开Intent会被系统静默拦截或者弹一个无法安装的提示。4.2 Android 10及以上的安装来源限制Android 10API 29引入了一个比较严格的限制如果一个App要安装未知来源应用必须在系统设置里被授予ACTION_MANAGE_UNKNOWN_APP_SOURCES权限。这不是运行时权限不能通过常规的requestPermissions弹窗直接申请而是要跳转到对应的设置页。通常的交互是用户点击安装按钮时先判断packageManager.canRequestPackageInstalls()如果不满足就跳转到设置页面val intent Intent( Settings.ACTION_MANAGE_UNKNOWN_APP_SOURCES, Uri.parse(package:$packageName) ) startActivity(intent)这块体验上有个优化空间你可以在用户首次点击下载时就检查这个权限而不是等下载完成后再检查。因为下载花了几分钟最后却卡在安装权限上用户会很恼火。我是在点击下载按钮时先检查如果要下载的是一个APK而且canRequestPackageInstalls()返回false就直接引导去授权。等下载完成时大概率权限已经通过了直接走安装就行。4.3 分应用内更新与商店更新的差异如果你的App是做一个应用内更新功能也就是更新自身逻辑会稍有不同。大多时候我们不是从系统DownloadManager拿文件而是建议使用Google Play In-app Updates或者如果你的产品是国内的走自己的APK下载更新。对于更新自身这种场景更关键的是版本比较逻辑不能只看versionCode大小还要考虑渠道、架构、最低支持版本。我在项目里吃过亏下载了一个高版本APK结果它在Android 8上不支持用户装完再点旧版App直接闪退。源头就是没有在下载前校验minSdkVersion。在App下载另一个App这种场景里安装包不一定和你同源更要注意签名校验。如果下载的是合作方App至少要校验md5或sha256防止下载到被篡改的包。DownloadManager本身不提供校验能力需要在下载完成后对文件做一次哈希计算和服务端下发的哈希值对比不一致就删除并提示用户重新下载。5. 真实工程里容易翻车的几个坑代码写出来能跑和真机上不出问题是两回事。下载功能尤其明显因为它依赖网络、存储、系统调度、ROM定制等多个外部因素。我在这个项目里踩过的坑罗列几个比较有代表性的希望你能绕开。5.1 网络切换后DownloadManager的假死遇到过这样一个线上问题用户在Wi-Fi环境下开始下载进度走到60%然后用户走到了公司门口手机自动切换到了4G网络结果进度条再也不动了。查了很多日志DownloadManager的状态显示STATUS_RUNNINGbytesDownloaded也不再变化看起来像僵死。实际原因是DownloadManager在默认配置下不会在移动网络下继续下载除非你明确设置了setAllowedOverMetered(true)。解决方法是创建Request时把网络条件放开request.setAllowedOverMetered(true) request.setAllowedOverRoaming(false)这样Wi-Fi切到移动数据时下载不会中断。但如果你想做更细腻的用户引导也可以监听ConnectivityManager的网络变化提示用户当前已切换至移动网络是否继续下载用户确认后再更新下载策略。不过DownloadManager一旦创建任务做这种暂停/恢复操作需要调用DownloadManager.remove再重新建任务这会丢失已下载的进度体验不好。所以我建议在确认用户接受流量消耗的前提下直接允许DownloadManager使用移动网络。5.2 存储权限被拒绝后的降级方案早期版本里我习惯把APK下载到Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_DOWNLOADS)也就是系统公共下载目录这样用户能方便看到下载好的安装包。但这样做需要申请WRITE_EXTERNAL_STORAGE权限在Android 10以后即使申请到了写入公共目录也有限制。后来我改成优先使用getExternalFilesDir这个目录不需要存储权限应用卸载时会跟着删除。如果你想保留系统下载目录的可见性又要规避权限问题可以用MediaStore.Downloads去创建公共下载项但Android 10和11的API差异又让人头疼。我的建议是普通App下载APK不要纠结存到公共目录。用户唯一需要关心的是下载完能安装而不是能在文件管理器里看到这个APK。存在App私有外部目录下一样可以安装。如果你确实需要让用户在文件管理器里能看到做一个拷贝到公共目录的可选操作即可不要让权限阻碍主流程。5.3 用抓包定位下载失败原因有一次用户反馈某些下载地址在浏览器里能打开但是在App里DownloadManager直接报STATUS_FAILED没有错误码。我去服务器那边排查发现下载链接是HTTPS的但服务器的TLS配置对某些Android版本的访问会在握手阶段直接断开。这种问题用日志难查直接用抓包工具看网络请求最方便。我用的方式是先让手机连上代理用抓包软件截获DownloadManager发起的HTTP请求。注意DownloadManager默认的User-Agent是系统自带的不是我们App的很多服务器对UA有判断如果看到不是常用浏览器UA可能返回403。这也是一个隐蔽原因。排查之后发现我们的情况是服务器CDN对UA做了限制解决方式是给DownloadManager的Request手动设置一个User-Agentrequest.addRequestHeader(User-Agent, AppDownloader/1.0)这个问题解决后那个地址的下载就正常了。如果你们是下载自己服务端的APK建议在服务端日志里考虑记录DownloadManager的UA方便定位这一类问题。5.4 通知栏进度与App内进度不一致的问题开了系统DownloadManager的通知栏进度后有时候会出现通知栏已经显示100%且消失App内的进度条只走到了90%。这是因为系统写入数据库的完成状态和App轮询读取之间有一个时间差你这次轮询恰好读到了旧的字节数而下载实际已经完成。要解决这个问题不能只依赖定时轮询。最终我采用的方案是每次轮询的同时判断数据库COLUMN_STATUS字段。如果状态已经是STATUS_SUCCESSFUL就直接把进度Set到100并触发后续逻辑不再沿用上一次读到的bytesTotal做除法。同时在ACTION_DOWNLOAD_COMPLETE广播到达时也要强制同步一次UI状态避免轮询的滞后。6. 把进度条做得丝滑UI刷新、进度计算与状态切换到了这一步基础功能已经完整了。但用户感知好不好往往就差在进度条是否顺滑、状态切换是否正确。下面说一些关于UI层的细节。6.1 进度不是百分比那么简单如果你的APK有50MB服务器不给Content-Length那么bytesTotal一开始可能是0。这时候你如果按照bytesDownloaded / bytesTotal去算进度要么除零要么百分比显示成0%直到下完才跳到100%。更好的做法是当bytesTotal 0时进度条改成加载中状态不显示具体百分比一旦拿到有效总大小再切换成百分比模式。还可以根据已经下载的字节数预估一个临时百分比比如已下载12.3MB但界面别硬显示成数字百分比否则会让用户困惑。如果你的下载包很大还可以考虑使用TransferListener式的分段回调把进度条分成下载中和安装准备中两个阶段。下载阶段显示0%~100%下载完成但还没开始安装时进度条可以显示一个无穷动画提示用户安装包校验中。这样比直接跳到100%更真实因为从下载完成到安装界面弹出来的等待时间并不为0。6.2 避免进度条回退的正确计算方式有些小伙伴遇到过进度条明明走到80%突然又跳回60%。这个问题通常不是数据读错了而是下载任务重启了。比如网络断开后DownloadManager自动重试bytesDownloaded会被重置或者你把任务重新提交了一次旧的查询结果和新的查询结果混在了一起。为了规避这种回退我当时的做法是在下载开始时保存downloadId并且记录一个最大已下载字节数。每次轮询拿到新值时如果新值小于旧值说明发生了重置这时不更新UI进度而是等它超过旧值以后再正常更新。这个方法很土但在当时的业务下确实有效。更好的方案是使用文件级别的断点续传但DownloadManager不支持自定义分片只能接管它的文件那又是一个复杂度的大坑。如果你的项目对进度条不能回退有强要求还是建议在创建任务前先判断是否存在旧任务存在则先remove再创建新任务避免两个任务并行。6.3 状态流转下载中/暂停/失败/成功的边界处理我再分享一个状态机设计。下载任务的UI层我维护了5种状态IDLE未开始DOWNLOADING下载中PAUSED暂停这个状态DownloadManager实际没有一个可靠的暂停API一般我们用取消任务来实现FAILED失败SUCCESS成功在代码里每次查询到状态后统一走一个dispatchState(status, progress)方法。这个方法里只做一件事根据当前状态决定要切换UI还是更新进度。一定不要在外面散落地写很多if分支否则最后你根本不知道是哪个分支把状态改错了。另外要考虑用户手动取消的路径。使用DownloadManager时取消任务的API是remove(downloadId)。这个操作会删除已经下载的部分文件如果用户只是想暂停再继续那就别用这个API否则之前下载的进度全白费了。更友好的做法是提供取消按钮而不是暂停按钮。如果真要暂停后恢复需要自己维护URL、已下载文件偏移量然后结合下载库/OkHttp实现断点这就是另一套方案了。7. 针对不同App场景的适配建议不是所有需要下载App的产品都适合用同一套方案。我在项目里也根据具体场景做了几档调整这里按业务类型拆一下。7.1 单包体积与下载速度对进度刷新策略的影响如果你的产品主要下载一些几MB的小工具App根本不需要做300ms轮询更新UI。下载可能2秒就完成了你甚至可以让按钮从下载变成打开之前给用户一个100%的瞬时反馈中间不做连续动画。反而轮询太密App会显得耗电。如果下载的是大型游戏包几百MB甚至上GB进度条反而不是最重要的更关键的是上传测速、剩余时间估算以及用户断网后的恢复。这种场景我建议直接上成熟的下载库哪怕是引入较大的依赖因为你要处理的东西太多了分片、校验、离线任务队列、存储管理都是系统DownloadManager给不了你的。经验是包越大、下载任务越重越不要尝试用DownloadManager 轮询来搞定一切。它可以覆盖简单场景但超过100MB的下载最好用专业下载框架做任务管理。7.2 我的最终建议一个下载器功能如果你不想返工开始写代码前先把这四件事想清楚下载任务由谁管理、进度数据如何传递、文件落盘在哪里、安装时权限链路如何走通。这四个问题想清楚代码框架基本就有了雏形。我在实际项目中最终选型是这样的简单场景下载一个APK走DownloadManager 定时轮询 广播兜底复杂场景批量下载、多任务、大文件走OkHttp 自定义下载线程池 Room保存任务记录。两者的UI层进度条逻辑完全相同只是数据源不一样。最后再分享一个小技巧下载进度条的UI组件不要用单一的数字百分比最好同时展示已下载大小 / 总大小和速度。用户看到进度条最关心的往往不是百分比而是到底在不在动。展示3.2MB/s这种实时速度比单纯让进度条往前跑更能建立安全感。我们上线这个版本后用户关于下载卡住的反馈肉眼可见少了很多。这里面的坑基本都是一步一步踩出来的。你如果能提前绕开应该能省下不少调试时间。
