简介面向 Android 系统开发者与 ROM 定制工程师这份资源围绕 OTA 在线升级中的升级包下载环节提供可直接参考的 DownloadFile 工程实现。工程内部按标准 Android 项目组织包含下载任务的文件获取、校验与落盘逻辑也关联 OTA 更新中签名验证、增量更新、A/B 分区等关键机制适合用来理解设备端如何从更新服务器拉取并准备升级包。包体共 46 个文件以 10 个 Java 源码和 19 个 class 编译产物为主配合 7 个 XML 配置/布局、3 个 PNG 图标以及 Android.mk、jar 依赖库等构建文件整体约 603KB。资源目录层次清晰既便于阅读核心下载代码也能通过资源文件看清界面与配置。目前已有 5840 人学习下载。通过阅读源码与布局可以较快掌握 OTA 下载模块的工程组织方式、网络请求与文件处理的基本流程理解升级包从检测、下载到校验的完整链路为二次开发或调试提供实用参考。很多技术人员第一次接触OTA升级都觉得下载升级包这事简单一个URL丢给DownloadManagerenqueue完事。我以前也这么干过直到真正接手一个量产Android设备的OTA模块才发现“升级包下载”是整条升级链路里看起来最简单、实际埋坑最多的一环。这篇文章不聊Recovery怎么刷分区也不聊服务端怎么生成增量包只聚焦“升级包下载”这一件事从选型、路径、断点、校验到下完包之后紧接着的验签和触发升级把那些文档里不写、但量产必踩的点过一遍。虽然题目是Android但做嵌入式方向的朋友看ESP32 OTA时会发现底层逻辑几乎一样拉固件、验包、跳转只是平台栈不同。适合两类人看一是刚接手系统升级模块的应用层开发二是想搞明白自家设备OTA总失败的整机或系统工程师。1. 先看懂OTA全链路再动手写下载逻辑1.1 一次升级是怎么从服务器走到批处理脚本的标准的Android OTA在线升级通常由三端协作完成服务端负责生成升级包、下发元数据版本号、包大小、md5/sha256、下载地址。客户端系统升级App负责拿元数据、下载升级包、校验并触发安装。Recovery或Updater负责真正执行安装动作解析升级脚本、校验签名、写分区、清缓存。这里有个常见误解很多人把“OTA在线升级”等同于“下载”。实际上下载只是中间环节真正定义升级成败的是后面两段。但如果下载这一段出了岔子后面根本走不到。1.2 下载模块的职责边界别越界也别少干下载模块的职责就四个字稳、全、验、传。稳断点能续、网络切换不崩、电量低能暂停。全文件不能缺字节几十KB的差池就可能导致升级脚本解析失败。验下载完成后必须做完整性校验和签名校验。传把正确的文件路径交给安装模块不阻塞、不重复。很多自研方案的毛病就是越界下载模块顺手做了解压、做了版本判断、甚至做了安装逻辑结果出了问题根本定位不到是哪一段造成的。下载就是下载把文件闭合好、校验好再交给上层这是最不容易出错的边界设计。2. 下载方案选型我为什么从自研又换回了DownloadManager2.1 三种方案的优劣一张表看完方案优点缺点适合场景系统DownloadManager系统级断点续传、网络约束、通知栏、免权限存储回调粒度粗、进度刷新不及时、部分ROM有阉割绝大多数量产设备的OTA包下载OkHttp/HttpURLConnection自研可控性强、能对接私有协议、能拿到精确进度断点续传、生命周期管理、异常恢复全要自己写有个性化下载需求或私有加密通道的定制项目IntentService文件流逻辑直观后台限制、断点困难、电量控制弱基本不建议2.2 自研下载的真正代价断点续传远没你想的简单早期我接手过一个项目下载模块是前任用OkHttp写的。功能看起来没问题能下载、有进度条、失败了会重试。但量产之后问题不断最典型的是用户下载到80%切换Wi-Fi连接断了OkHttp抛异常重试逻辑从0开始。App被系统回收下载任务直接消失。下载过程中系统休眠TCP连接被内核断开毫无征兆。断点续传不是“断了我重新连上”这么简单它要求你保存已下载字节数、记录文件偏移量、处理服务端是否支持Range、校验每段数据是否错位。一套完整的断点续传下来至少要写几百行状态管理代码。而DownloadManager在系统层面把这些全做了——Wi-Fi切换、连接断开、服务重启之后系统会尝试恢复下载任务。2.3 什么情况下才值得自研一句话除非升级包不走普通HTTP通道否则别自研。我见过需要自研的场景基本是这几类升级包经过私有加密要先从服务端拉一个密钥再解包下载。服务端是私有协议不走标准HTTP。产品需要把下载和UI展示深度绑定比如极致的进度动画。除此之外直接用DownloadManager是投入产出比最高的方案。哪怕你是做车机或电视盒子这种大屏设备系统级下载管理依然是最稳的选择。3. 下载实战路径、空间、状态监听与断点恢复3.1 存储路径优先私有目录绕开分区存储的坑Android 10之后分区存储成了硬性要求直接往公共Download目录写文件要么需要SAF授权要么会触发权限弹窗在无人值守的OTA场景里这是致命的。我的建议是升级包优先放在应用私有外部目录。File otaDir context.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS); File targetFile new File(otaDir, ota/ota.zip);这样写的原因很简单getExternalFilesDir路径不需要任何运行时权限用户卸载App系统会回收这个目录且这个路径对系统升级模块来说天然有访问权限。要注意的是部分定制ROM对/data/media的文件权限做过特殊处理实测中有极少数机型会出现“下载成功但Recovery读不到”的问题。遇到这种情况把目标目录显式改成/data/ota_package或/cache这类系统路径但前提是你的App有系统权限。3.2 下载前的空间预检按1.5倍冗余算升级包下载失败的隐藏头号原因不是网络是存储空间不足。尤其全量包经常几个GB解压、校验、写分区都需要临时空间。下载之前必须做空间预检StatFs stat new StatFs(targetDir.getAbsolutePath()); long availableBytes stat.getAvailableBytes(); if (availableBytes packageSize * 1.5) { // 提示用户清理空间或直接走“先下载到外置SD卡”的逻辑 }为什么不按1倍算因为DownloadManager下载到一半会先写临时文件安装时系统还要对升级包做解压和校验这些操作需要额外的临时空间。按1.5倍冗余实测能覆盖绝大多数热插拔存储的极端情况。3.3 状态监听onReceive里能拿到什么发送下载请求DownloadManager.Request request new DownloadManager.Request(Uri.parse(url)); // 关键点仅Wi-Fi下载避免用户流量被干光 request.setAllowedOverMetered(false); request.setAllowedOverRoaming(false); // 关键点目标路径用私有外部目录 request.setDestinationInExternalFilesDir(context, Environment.DIRECTORY_DOWNLOADS, ota/ota.zip); request.setNotificationVisibility(DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED); request.setTitle(系统升级包); request.setDescription(正在后台下载更新...); DownloadManager dm (DownloadManager) context.getSystemService(Context.DOWNLOAD_SERVICE); long enqueueId dm.enqueue(request);监听完成状态要注册广播接收者并在onReceive里做状态查询BroadcastReceiver receiver new BroadcastReceiver() { Override public void onReceive(Context context, Intent intent) { long id intent.getLongExtra(DownloadManager.EXTRA_DOWNLOAD_ID, -1); if (id ! enqueueId) return; DownloadManager.Query query new DownloadManager.Query().setFilterById(id); Cursor cursor dm.query(query); if (cursor.moveToFirst()) { int status cursor.getInt(cursor.getColumnIndex(DownloadManager.COLUMN_STATUS)); if (status DownloadManager.STATUS_SUCCESSFUL) { String localUri cursor.getString(cursor.getColumnIndex(DownloadManager.COLUMN_LOCAL_URI)); // 这里开始走校验流程 } else if (status DownloadManager.STATUS_FAILED) { int reason cursor.getInt(cursor.getColumnIndex(DownloadManager.COLUMN_REASON)); // 打印reason通常能直接看出原因空间不足、网络失败、文件重复 } } cursor.close(); } };这里有三个实测心得第一COLUMN_REASON是个会被严重低估的字段。空间不足、网络超时、服务端返回错误码都能从reason里拿到具体值排查问题比瞎猜强太多。第二DownloadManager返回的COLUMN_LOCAL_URI是file://形式直接传给后续模块没问题但如果你同时用了FileProvider要先把URI转换成File再封装不要在中间层混用两种URI。第三DownloadManager的下载任务在系统重启后不一定自动恢复。实测中有的设备会恢复有的不会。所以建议在升级App的启动器里定期检查当前是否有未完成任务若有且文件不完整主动重新enqueue。4. 下载完成的瞬间真正的考验才开始4.1 完整性校验md5对不上升级百分之百失败下载成功只代表“字节拉完了”不代表“字节是对的”。服务端断点续传出错、CDN缓存损坏、传输过程被劫持都可能让包不完整或内容被替换。所以下载完成后第一件事就是做哈希比对。大多数OTA服务端在下发元数据时会带md5或sha256没有就要求服务端加上。public static String sha256(File file) throws Exception { MessageDigest digest MessageDigest.getInstance(SHA-256); try (FileInputStream in new FileInputStream(file)) { byte[] buffer new byte[8192]; int len; while ((len in.read(buffer)) ! -1) { digest.update(buffer, 0, len); } } return bytesToHex(digest.digest()); }校验失败的最常见原因有两个服务端下发的哈希值和包实际哈希对不上——通常是发布流程出了bug打包机器和服务端不是同一份产物。这个要跟服务端同学确认别自己默默重下。下载过程不完整文件少了几KB。这种在DownloadManager的STATUS_SUCCESSFUL状态下也会发生因为系统认为任务成功但文件在写入缓存时被中断过。所以务必以哈希校验结果为准不要信DownloadManager的成功状态。4.2 验签OTA包为什么要验公钥哈希保证“文件完整”但保证不了“文件是官方出的”。中间人攻击、恶意升级包注入都会让终端设备变砖甚至被植入恶意程序。所以正规OTA升级包都有签名Android上用的是RSA/ECDSA 证书链这套体系。加签验签在车机、嵌入式设备上尤其严格因为一旦被刷入恶意固件物理损害都算小的数据泄露才是大问题。Android里触发安装前Recovery本身会做一边签名校验但客户端在下载完成后提前做一次验签可以更早发现问题避免重启进Recovery才发现占用不可用。客户端验签的关键点// 拿到OTA包的全路径后 // 1. 从包内读取 META-INF 下的签名文件 // 2. 用内置公钥验签不能用服务器下发的公钥 PublicKey publicKey loadEmbeddedPublicKey(); boolean valid verifySignature(publicKey, otaFile);内置公钥这道防线是核心验签用的公钥必须编译在App里或存在设备安全硬件里。如果公钥也是从服务器拉的那整个验签就是摆设。4.3 触发安装一把只有系统应用才配拥有的钥匙哈希和签名都过了接下来就是把升级包交给Recovery。Android系统应用有signature权限或系统签名可以走RecoverySystem.installPackage(context, new File(/data/ota_package/ota.zip));这个方法会通知系统进入Recovery模式并传入--update_package...参数。普通第三方App没权限调用它这也是为什么正规厂商的升级App都是系统应用或系统签名的原因。触发之后要注意不要在回调里立刻杀进程或做任何清理。installPackage只是提交请求系统会稍后重启。如果你在同一个进程里立刻做文件清理或Activity跳转可能导致升级请求没来得及写入misc分区设备直接重启进正常系统用户感受就是“点了升级结果只是重启了一下”。5. 下了包升级仍失败回滚机制与量产踩坑记录5.1 失败最常见的三个原因原因一存储空间在下载期间被占满。下载前预检通过了但用户下载期间继续装App、拍视频、收微信文件磁盘瞬间又满了。所以下载完成后的校验阶段也要做一次空间判断空间不足就直接提示别硬走到Recovery。原因二下载任务被系统自动清理。这是低内存设备上最常见的问题。DownloadManager任务在极端低内存下可能被系统回收文件只下了一半状态还是STATUS_SUCCESSFUL。哈希校验能抓住这个问题但根本解决方式是升级期间提示用户关闭后台应用或者尽量在设备空闲时段下载。原因三校验算法与服务端不一致。升级包用的是SHA-256服务端给你的却是md5两边对不上白白浪费用户流量。这种问题一旦出现第一个要查的是发布流程不是设备端写的判断逻辑。5.2 回滚机制为什么系统升级允许“后悔”热词搜索里有个说法叫“OTA有回滚”这确实是系统级升级不可或缺的一环。在非A/B分区的设备上Recovery在执行升级时如果某一步写分区失败、脚本解析失败、或升级包校验不通过Recovery会通过BCBBootloader Control Block记录失败状态下次启动时自动回滚到旧系统或进入Recovery恢复界面。这种机制保证了“升级失败不会直接变砖”。在A/B分区设备上机制更优雅系统把新系统写入空闲分区写入完成后通过切换slot生效。如果新系统启动失败bootloader会切换回原slot实现无缝回滚。下载模块和这套回滚机制的关系在于无论哪种方案升级包都必须在触发前保证完整可用否则Recovery层拿到的就是一个垃圾输入回滚功能再强也没法用。5.3 几个直接抄的参数建议与自查清单setAllowedOverMetered(false)默认禁止移动网络除非产品明确允许。setAllowedOverRoaming(false)漫游打死不开流量资费不是你能预测的。setNotificationVisibility(VISIBILITY_VISIBLE_NOTIFY_COMPLETED)下载中可见完成有通知用户能感知。触发安装前检查电量低于30%不建议触发升级低于15%直接禁止。记录下载日志包括enqueueId、服务端下发的包大小、实际文件大小、哈希比对结果、触发安装时间。出了问题先看日志别让人把手机寄回来。做了这么久OTA升级模块我个人最大的体会是下载是最容易被轻视、却最直接影响用户体验的一环。用户不会管你升级脚本写得有多优雅他们只知道“点了个升级结果等半天下载失败”。把下载链路做稳、校验做全、异常路径都覆盖到比在Recovery脚本上炫技值钱得多。最后再分享一个小技巧每次发布新版升级App前拿一个老版本系统实际跑一遍“下载到80%切网、下载到90%杀进程、整包下载完模拟空间不足”这三个场景能挡住90%的线上事故。本文还有配套的精品资源点击获取