简介面向Android开发者的后台下载Demo示例系统梳理IntentService、AsyncTask、JobScheduler三种后台下载方案的实现思路与适用场景并针对低版本适配给出了JobIntentService、GcmNetworkManager与自定义Service等扩展方向。压缩包共67个文件以Java源码、XML布局与配置文件、Gradle工程配置为主辅以少量资源文件与构建脚本整体仅376KB结构紧凑可直接导入Android Studio分析。该Demo的工程目录清晰核心逻辑集中在app模块下便于快速定位。已有518人学习下载。借助项目源码可对照三种异步任务机制在生命周期、线程调度、电量优化方面的异同学习如何根据业务需求选择最合适的下载方式同时还能了解API 21以下设备的兼容处理、网络与电量条件约束以及更精细的后台任务管理思路适合正在学习Android后台任务或需要快速落地下载功能的开发者参考。1. Android 后台下载功能简单需求背后藏着最难拿捏的五处细节Android 后台下载功能是移动端需求里最容易被低估的模块产品文档里通常只有一句“退出页面继续下载、断网自动续传”真正跑真机时通知栏、分区存储、锁屏网络、省电策略这些隐性约束全都会凑上来要答案。常用的方案有 DownloadManager、WorkManager、前台服务三条路线选错一个后续就要从流程上返工。这篇笔记按照实际工程的推进顺序把选型依据、核心参数、进度刷新、文件完整性的坑位全部拆开文中的代码片段可以直接复用到自己的下载模块里帮助你把最常见的返工环节提前避开。2. 选型与首版接入DownloadManager 能做什么、不能做什么2.1 三条技术路线的设计差异与适用场景在贴代码之前先明确路线。DownloadManager 是系统级下载服务应用进程退到后台甚至被划掉之后下载任务依然在系统进程里执行UI 只需要在下次启动时查询一次状态适合对下载行为没有特殊定制要求的场景。WorkManager 是任务调度框架解决的是“在满足约束的条件下执行有保证的任务”但它不会让任务脱离应用进程应用被强制停止之后任务也会停下次进程启动时才恢复。前台服务则是一个“保证进程优先级”的载体下载逻辑本身仍然写在应用进程里所以还要自己处理网络流和文件写入。在实际工程里我见过三类项目。第一类是公司内网工具只下载一个 APK 更新包用 DownloadManager 就能解决全部需求代码量最小也不用考虑进程优先级。第二类是在线教育类应用要下载几百 MB 的视频课件下载中允许暂停继续下载完成后还要做解密或转码DownloadManager 虽然也能做但要对系统通知和文件校验做大量补偿反而比自己在前台服务里控制网络流更繁琐。第三类是离线地图或离线语料包文件动辄几个 GB必须支持断点续传和并发控制这种场景我会直接用 OkHttp 在前台服务里自己写下载器完全绕过 DownloadManager 的黑匣子。另一个判断依据是任务生命周期。下面是三条路线在关键属性上的对比这个表在我每次选型时都会过一遍方案进程归属应用被划掉是否继续适合场景DownloadManager系统进程继续简单文件下载、应用更新包WorkManager应用进程停止下次启动恢复可延迟的一次性任务、重试任务前台服务应用进程停止进程重建后可能恢复长任务、需要自定义进度和业务控制如果下载任务需要“用户彻底退出应用之后还能继续”DownloadManager 是默认选择如果需要业务层深度控制下载过程则选前台服务方案。2.2 DownloadManager 请求构造URL、路径与网络策略DownloadManager.Request request new DownloadManager.Request(Uri.parse(downloadUrl)); request.setTitle(系统更新包); request.setDescription(正在后台下载更新文件); request.setNotificationVisibility( DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED); request.setAllowedOverMetered(false); request.setAllowedOverRoaming(false); request.setDestinationInExternalPublicDir( Environment.DIRECTORY_DOWNLOADS, update-latest.apk); DownloadManager manager (DownloadManager) context.getSystemService(Context.DOWNLOAD_SERVICE); long downloadId manager.enqueue(request);这段代码里每一行都有讲究。setTitle 与 setDescription 是通知栏展示用的文案title 出现在状态栏下拉通知的标题行description 在通知的正文行。默认情况下用户点击通知拉起的是系统“下载内容”界面如果希望点击后跳转自己 App 的下载管理页需要额外用 PendingIntent 覆盖通知点击行为。setNotificationVisibility 控制通知的显示策略VISIBILITY_VISIBLE_NOTIFY_COMPLETED 表示从下载开始到结束一直展示进度并在完成后弹一次“下载完成”的通知VISIBILITY_VISIBLE 只显示进度完成后不弹通知VISIBILITY_HIDDEN 是完全不显示系统通知。这里有个教训VISIBILITY_HIDDEN 在部分系统定制版本上被当作不合法值表现是任务一直在排队但永远不开始原因是这些系统的 DownloadManager 实现里把隐藏任务挂在专用调度队列上。我在三款国产 ROM 上都遇到过后面统一改成了 VISIBILITY_VISIBLE 加应用内通知屏蔽。setAllowedOverMetered(false) 和 setAllowedOverRoaming(false) 分别控制计流量网络和漫游网络的下载权限。两个都设为 false在 Wi-Fi 条件下可下载在移动网络下任务会停留在 PENDING 状态而不是报错。这个状态非常容易让人误判成“系统没有响应”实际是调度器还在等待合适的网络。如果需求是“用户在下载页手动允许移动网络下载”就要在设置页保存选项下载时动态地写入请求。漫游开关只在移动网络且处于漫游时生效普通移动网络不受影响所以业务上只需提供“是否允许使用移动网络”一个开关就够了。setDestinationInExternalPublicDir 把文件写入公共 Downloads 目录。下载任务提交后系统会按文件名去重同一个名字会生成 1.apk、2.apk 这类后缀所以文件名最好用业务层唯一 ID 拼出来避免用户下次下载时拿到一个带数字后缀的副本。Android 10 之后分区存储对这个 API 的影响比较隐蔽公共目录下的文件对 App 来说变成不可直接 File 访问但 DownloadManager 记录本身会在 COLUMN_MEDIA_STORE_URI 里保留一个 MediaStore 引用查询这个字段可以拿回 Uri 并载入自己应用后面的避坑章节会具体展开。2.3 状态查询从 Cursor 读出进度、状态与失败原因DownloadManager.Query query new DownloadManager.Query(); query.setFilterById(downloadId); Cursor cursor null; try { cursor manager.query(query); if (cursor ! null cursor.moveToFirst()) { int status cursor.getInt( cursor.getColumnIndex(DownloadManager.COLUMN_STATUS)); long bytesDownloaded cursor.getLong( cursor.getColumnIndex(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR)); long bytesTotal cursor.getLong( cursor.getColumnIndex(DownloadManager.COLUMN_TOTAL_SIZE_BYTES)); int reason cursor.getInt( cursor.getColumnIndex(DownloadManager.COLUMN_REASON)); switch (status) { case DownloadManager.STATUS_RUNNING: long percent bytesTotal 0 ? bytesDownloaded * 100 / bytesTotal : 0; // 更新 ViewModel 中的进度值 break; case DownloadManager.STATUS_SUCCESSFUL: String fileUri cursor.getString( cursor.getColumnIndex(DownloadManager.COLUMN_LOCAL_URI)); // 通知 UI 显示“已完成” break; case DownloadManager.STATUS_FAILED: // reason 的取值可查阅 DownloadManager 的常量定义 break; } } } finally { if (cursor ! null) { cursor.close(); } }查询返回的 Cursor 字段与 DownloadManager 内部数据库公开的视图一一对应。COLUMN_STATUS 取值有五类这里最容易混淆的是 PENDING 和 PAUSEDPENDING 表示还在等待调度网络条件不满足或系统资源受限时会停留在这里PAUSED 表示已经开始但被系统主动中断比如网络断开、存储空间不足、Wi-Fi 切换。如果任务长时间停在 PENDING多数是网络策略或系统后台限制导致不是 DownloadManager 本身挂了。COLUMN_LOCAL_URI 这个字段有坑在部分厂商定制系统上任务成功后返回的格式不一定是 file:// 开头有的返回 content://有的直接返回 null。安全做法是同时读 COLUMN_URI 和 COLUMN_LOCAL_URI 两个字段兜底取到值之后统一交给 FileProvider 转成 content URI 再给其他组件用。轮询间隔我一般设在 500ms 到 1000ms通过页面 Lifecycle 控制起停避免页面不可见时还在空转。如果只是单个任务也可以注册 BroadcastReceiver 监听 ACTION_DOWNLOAD_COMPLETE 替代轮询但多任务场景下广播里要自己解析 extra 里的下载 ID轮询反而更直接。3. 多任务下载与进度管理队列、通知栏与 UI 刷新3.1 多任务下载建立 URL 到任务 ID 的映射与去重产品说“一次下载多个文件”的瞬间代码复杂度就开始膨胀。第一步是去重同一个 URL 如果前一任务还没完成再次点击下载时最粗暴的做法是直接禁用按钮但产品往往要求“重新下载也可以”于是要建立一个以 URL 为 key 的任务表。下载任务提交后DownloadManager 返回一个 long 类型的 ID业务层必须要用这个 ID 作为后续查询、取消、重新下载的唯一凭证。public class DownloadTask { final long id; // DownloadManager 返回的任务 ID final String url; // 原始下载地址 final String fileName; // 目标文件名 long totalBytes; long downloadedBytes; int status; }用内存表维护当前任务还不够任务 ID 与 URL 的映射要持久化到 SharedPreferences。原因是应用进程可能在下载中途被系统杀掉重新启动后如果只从内存读任务列表就会把“正在下载”错判成“没有任务”。持久化之后冷启动时先从 SharedPreferences 读出每个 URL 对应的下载 ID再去 DownloadManager 查状态就能把未完成的任务重新接管回来。// 保存任务映射 SharedPreferences sp context.getSharedPreferences(download_tasks, Context.MODE_PRIVATE); sp.edit().putLong(url, downloadId).apply(); // 冷启动恢复 long savedId sp.getLong(url, -1); if (savedId ! -1) { DownloadManager.Query query new DownloadManager.Query(); query.setFilterById(savedId); Cursor cursor manager.query(query); // 判断状态已完成且文件校验通过的删除映射未完成的继续展示进度 }这里有一个业务决策点已完成的下载文件是否保留如果不保留任务映射可以删掉如果保留建议把文件名、URL、文件大小、SHA-256 写进一个 JSON 缓存文件和实际文件放同一目录校验时优先比对大小和摘要。我在项目里就是这么做的用户可以随时在下载页看到“文件已存在上次校验通过”避免每次冷启动都重新下载一遍。3.2 进度刷新ContentObserver 替代轮询顺带算实时速率DownloadManager 没有提供进度回调给业务层进度刷新主要有两种方式定时器轮询和 ContentObserver 监听。轮询代码简单直接但每隔几百毫秒执行一次数据库查询对电量和 IO 都不友好ContentObserver 是在下载数据库的下载条目发生变化时触发相当于系统回调更省资源。Uri downloadUri Uri.parse(content://downloads/my_downloads); getContentResolver().registerContentObserver( downloadUri, true, new DownloadObserver(new Handler(Looper.getMainLooper()))); class DownloadObserver extends ContentObserver { Override public void onChange(boolean selfChange, Uri uri) { super.onChange(selfChange, uri); // 下载过程中回调非常频繁这里要做 500ms 级别的节流 refreshProgress(); } }ContentObserver 的 onChange 在下载过程中会被高频触发收到的 uri 可能有多种变体不要在回调里直接做耗时操作。正确做法是把最新状态拷到 ViewModelUI 层再从 ViewModel 读数据。注意在页面销毁时调用 unregisterContentObserver否则极端内存紧张场景下会造成 ContentProvider 泄漏这个问题在低端机上非常容易出现。进度计算还有一种需求显示实时下载速度。速度不能直接用“下载量差值除以时间”因为间隔太短时系统缓存和网络波动会导致数值剧烈抖动。我一般取最近 3 秒的下载字节数做平均再换算成 bps 展示。long speedBytesPerSec 0; long elapsedTimeMs latestTimestamp - previousTimestamp; if (elapsedTimeMs 0) { speedBytesPerSec (latestBytes - previousBytes) * 1000L / elapsedTimeMs; }时间戳这里特别注意要用 SystemClock.elapsedRealtime()不要用 System.currentTimeMillis()。后者受系统时间修改的影响用户在下载过程中手动调整系统时间速率会算成负数界面上直接展示出“-3 MB/s”这种问题查起来非常玄学。3.3 通知栏体验自定义进度通知与系统通知的二选一DownloadManager 默认通知文案是系统固定的要改成“下载中剩余 xx 秒”这类自定义内容通常的做法是让 DownloadManager 保持静默自己发一条带进度条的通知。保留系统通知的同时再发自定义通知会出现两条进度不一致的通知用户看着非常乱。自定义进度通知的建设思路很简单下载状态变化时重建通知用同一个 NOTIFY_ID 调用 notify 更新NotificationCompat.Builder builder new NotificationCompat.Builder(context, CHANNEL_ID) .setContentTitle(下载应用更新包) .setContentText(进度 percent %) .setProgress(100, percent, false) .setSmallIcon(R.mipmap.ic_launcher) .setOnlyAlertOnce(true); notificationManager.notify(NOTIFY_ID, builder.build());setProgress 的第三个参数表示进度是否为不确定模式这里传 false 表示确定进度。如果下载阶段还没拿到总大小比如服务器没返回 Content-LengthCOLUMN_TOTAL_SIZE_BYTES 会是 0此时要传 true 显示不确定进度条等拿到总大小再切换回确定进度。用 DownloadManager 时还要注意任务被系统取消后系统通知可能消失但自定义通知不会要在查询状态发现任务已不在数据库时立刻 cancel 通知。4. 从 DownloadManager 切到 WorkManager何时切换、怎么切换4.1 切换触发条件业务控制、并发与断点续传业务面出现两种情况时我会把下载从 DownloadManager 迁移到 WorkManager 加前台服务。第一种是下载任务需要对业务层完全可控比如下载前要做登录态校验、下载后要做解压合并文件处理链路长DownloadManager 的“只管下载”模型满足不了。第二种是需要精细控制并发数、断点续传和重试策略DownloadManager 的内部调度对业务层是个黑匣子无法定制重试节奏也无法在应用内管理多个下载任务的优先级。WorkManager 解决的是“在满足约束条件时执行一次有保证的任务”它不是为“长时间且需要持续网络流”设计的所以实现长下载必须配合前台服务由 WorkManager 创建并持有前台服务在 doWork 里启动服务任务完成后再停掉。这样既享受 WorkManager 的重试和约束调度又拿到前台服务的进程优先级。整个过程里 WorkManager 负责调度前台服务负责面向用户的可见性两者协同。4.2 前台服务类型声明与权限适配从 targetSdk 33 到 34Android 12API 31开始强制要求为前台服务声明类型Android 14API 34进一步要求为部分类型申请细分权限。下载场景属于 dataSync 类型Manifest 里的写法如下service android:name.download.DownloadForegroundService android:exportedfalse android:foregroundServiceTypedataSync / uses-permission android:nameandroid.permission.FOREGROUND_SERVICE / uses-permission android:nameandroid.permission.FOREGROUND_SERVICE_DATA_SYNC /第二个权限是 Android 14 开始强制要求的targetSdk 34 以下可以不加但把 targetSdk 提到 34 之后不加会直接抛 SecurityException。这里有一个版本适配顺序的问题先把 targetSdk 提到 33确认前台服务类型声明在 Manifest 里生效再提 34 加细分权限。如果反过来旧 Manifest 没有声明类型直接上 Android 14 设备前台服务一启动就崩而且是只有真机才能复现的崩溃。4.3 实现一个可重试并能断点续传的下载 WorkerWorkManager 的 Worker 使用 CoroutineWorker 会比普通 Worker 更适合 IO 操作因为 doWork 是 suspend 函数可以直接用 OkHttp 的异步调用。下面是最小可用的下载 Worker 实现class DownloadWorker( context: Context, params: WorkerParameters ) : CoroutineWorker(context, params) { override suspend fun doWork(): Result { val fileUrl inputData.getString(KEY_URL) ?: return Result.failure() val fileName inputData.getString(KEY_FILE_NAME) ?: default.bin val targetFile File( applicationContext.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS), fileName ) val notificationManager applicationContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager // 提升为前台服务保证任务期间进程优先级 val notification buildNotification(0, 0) setForegroundAsync( createForegroundInfo( NOTIFICATION_ID, notification ) ) return try { downloadWithOkHttp(fileUrl, targetFile, notificationManager) Result.success() } catch (e: IOException) { Result.retry() } } }setForegroundAsync 会在 Worker 执行期间启动关联的前台服务。任务执行到一半进程被系统杀掉之后WorkManager 会在下次满足约束条件时重新调度但重新执行时文件已经写了一半如果直接重写整个文件会浪费大量流量。断点续传的常见做法是每次下载前先查 targetFile.length()如果大于 0 说明之前中断过用 OkHttp 的 Range 头从文件末尾续传val request Request.Builder() .url(fileUrl) .header(Range, bytes$startByte-) .build() val response okHttpClient.newCall(request).execute() val input response.body?.byteStream() val output FileOutputStream(targetFile, append true) input?.copyTo(output)Range 续传必须对服务器做兼容性判断。有些 CDN 不认 Range 头直接返回 200 全量数据这时如果继续往文件末尾追加就会把新数据接到旧文件后面生成一个损坏文件。所以写文件前先判断 response.code206 表示分段返回可以续写200 表示服务端忽略 Range 头此时要删除原文件重新下载。这段判断逻辑漏掉的后果是用户下载完成但校验永远失败百思不得其解。5. 避坑下载场景最常见的 5 类问题与排查方法5.1 下载状态显示成功但文件大小为 0现象DownloadManager 查询返回 STATUS_SUCCESSFUL但目标目录中文件大小是 0 字节或者文件根本不存在。原因这是分区存储与 DownloadManager 路径策略叠加导致的问题。Android 10 以后如果目标路径指向公共目录DownloadManager 会把文件写入系统 Downloads 集合应用直接用 File 路径访问会因分区存储隔离而失败文件大小为 0 的另一个常见原因是服务器返回了 Content-Length: 0 且 HTTP 状态码为 200DownloadManager 把这种响应判定为下载成功。解决下载完成后不要依赖文件路径判断结果通过查询 COLUMN_MEDIA_STORE_URI 拿到最终落地位置同时在发起正式下载前先请求一次 HEAD确认 Content-Length 大于 0 再入队。如果服务端本身不稳定还要在下载完成后把文件实际大小与 Content-Length 比对不一致时主动进入重试分支不要直接展示“下载完成”。5.2 锁屏后下载被挂起进程重启也无法恢复现象手机锁屏放一晚上第二天打开应用下载任务一直处于 PAUSED 状态或者 WorkManager 任务报错日志里找不到明显异常。原因锁屏后系统进入 Doze 模式Wi-Fi 可能被暂停。DownloadManager 对 Doze 的适配比应用内任务好一些但仍躲不过厂商定制系统的“深度休眠”机制省电策略会把后台进程的网络栈挂起。WorkManager 在 Doze 模式下默认只在维护窗口执行任务长时间无网络导致任务失败。解决下载任务所在的进程要持有 PARTIAL_WAKE_LOCK任务完成或失败时释放同时在用户首次发起大文件下载时走一次系统电量优化白名单的引导流程。这个引导需要用 ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS 拉起系统设置页文案写清楚“不加入白名单可能导致下载中断”。这一步是产品决策但技术侧必须把入口埋好否则锁屏断下载的问题无法根治。5.3 DownloadManager 通知栏残留点击后也不消失现象任务完成后系统通知一直驻留在通知栏用户点击通知后没有反应通知也不消失。原因DownloadManager 在 setNotificationVisibility 设置为 VISIBILITY_VISIBLE_NOTIFY_COMPLETED 时系统通知的点击行为依赖于 ACTION_DOWNLOAD_COMPLETE 广播。如果应用没有注册对应的 BroadcastReceiver通知不会自动清理部分定制系统甚至不会发送这个广播。解决在 Manifest 中注册一个 BroadcastReceiver 接收 ACTION_DOWNLOAD_COMPLETE在 onReceive 里用 NotificationManager.cancel(downloadId) 清理通知。receiver android:name.dl.DownloadCompleteReceiver android:exportedtrue intent-filter action android:nameandroid.intent.action.DOWNLOAD_COMPLETE / /intent-filter /receiver注意 receiver 的 exported 属性必须设置为 true否则系统广播无法到达应用。兼容性兜底是在查询状态发现任务已不在数据库时主动 cancel 所有与本任务关联的通知防止出现长期残留。5.4 系统通知与自定义通知重复出现进度两边不一致现象同一个下载任务既有系统通知又有应用内自定义通知两端进度条显示不一致用户看着很混乱。原因业务层在 DownloadManager 未设置静默的情况下又创建了自定义进度通知两套通知同时展示。自定义通知的进度用轮询刷新网络波动时应用内进度条可能先跳后回退与系统通知的进度天然不同步。解决DownloadManager 请求里把 setNotificationVisibility 固定为 VISIBILITY_VISIBLE并屏蔽系统通知的声音和震动由应用完全接管通知展示。如果目标设备上 VISIBILITY_HIDDEN 也能正常工作也可以直接使用 HIDDEN但要提前做机型判断。进度跳动则需要在更新时做差值限制单次进度差超过 5% 才刷新通知低于 5% 只更新内存数据避免通知栏高频通知造成电量和视觉的双重开销。5.5 下载了一半重新进入页面又从零开始现象用户从下载页面退出再进来同一个文件重新走一遍下载流程前面已经下载的部分被丢弃。原因页面进入时直接调用了 manager.enqueue()没有先查询历史任务状态相当于每次进入页面都新建了下载任务。DownloadManager 并不会对相同 URL 自动去重旧任务未取消新任务又启动磁盘上最终可能出现多个重复文件。解决严格建立“URL 到 downloadId”映射表进入页面时先查映射已存在的任务直接绑定状态并展示进度只有任务状态为 SUCCESSFUL 且文件校验通过时才允许发起新下载。代码层面再叠加一层保护查询状态时如果发现任务 ID 对应的 lastModified 时间在 5 秒内有更新说明下载仍在进行直接禁止创建新任务。从那以后我每次给下载模块加功能都强制先走一遍“先查旧任务、再校验文件、最后更新通知”的流程少了很多半夜被叫起来改 Bug 的次数。6. 下载完成不等于成功文件完整性校验与收尾习惯6.1 用 HEAD 请求拿到元数据再用 SHA-256 收尾下载完成后的第一件事不是弹 Toast而是校验文件。最轻量的方案是下载前发一次 HEAD 请求记录 Content-Length 和服务器返回的 ETag下载完成后比对大小和摘要。如果服务器没有提供 MD5 或 ETag就在应用内计算 SHA-256fun verifyFile(file: File, expectedSize: Long, expectedSha256: String?): Boolean { if (file.length() ! expectedSize) return false if (expectedSha256 null) return true val digest MessageDigest.getInstance(SHA-256) file.inputStream().use { input - val buffer ByteArray(8192) while (true) { val len input.read(buffer) if (len -1) break digest.update(buffer, 0, len) } } return digest.digest().joinToString() { %02x.format(it) } expectedSha256 }这个函数里 buffer 取 8192 字节是折中选择避免一次读入过大文件把内存顶上去。对大文件计算哈希是 IO 密集操作要放在协程或线程池里跑不能直接在主线程执行。6.2 我固定下来的下载模块收尾清单从这个项目开始我给每个下载需求都定了四步收尾第一步URL 到任务 ID 的映射落盘第二步文件写入后立刻比对大小与摘要第三步通知栏状态与任务状态同步失败或取消时移除通知第四步检查失败重试策略是否有上限避免无限重试消耗用户流量。这套习惯是从一次真实的线上事故里总结出来的。某个下载需求上线后用户反馈“下载完成但安装失败”排查到最后发现是服务器返回了错误页面但状态码是 200DownloadManager 把 HTML 当成了目标文件。加了摘要校验之后这种问题会在用户看到“下载完成”之前就被拦截。从那以后我每次做完下载模块都强制把校验链路走一遍再交付测试。希望这套思路能帮你在做自己的下载功能时少踩几个坑。本文还有配套的精品资源点击获取
简介面向Android开发者的后台下载Demo示例系统梳理IntentService、AsyncTask、JobScheduler三种后台下载方案的实现思路与适用场景并针对低版本适配给出了JobIntentService、GcmNetworkManager与自定义Service等扩展方向。压缩包共67个文件以Java源码、XML布局与配置文件、Gradle工程配置为主辅以少量资源文件与构建脚本整体仅376KB结构紧凑可直接导入Android Studio分析。该Demo的工程目录清晰核心逻辑集中在app模块下便于快速定位。已有518人学习下载。借助项目源码可对照三种异步任务机制在生命周期、线程调度、电量优化方面的异同学习如何根据业务需求选择最合适的下载方式同时还能了解API 21以下设备的兼容处理、网络与电量条件约束以及更精细的后台任务管理思路适合正在学习Android后台任务或需要快速落地下载功能的开发者参考。1. Android 后台下载功能简单需求背后藏着最难拿捏的五处细节Android 后台下载功能是移动端需求里最容易被低估的模块产品文档里通常只有一句“退出页面继续下载、断网自动续传”真正跑真机时通知栏、分区存储、锁屏网络、省电策略这些隐性约束全都会凑上来要答案。常用的方案有 DownloadManager、WorkManager、前台服务三条路线选错一个后续就要从流程上返工。这篇笔记按照实际工程的推进顺序把选型依据、核心参数、进度刷新、文件完整性的坑位全部拆开文中的代码片段可以直接复用到自己的下载模块里帮助你把最常见的返工环节提前避开。2. 选型与首版接入DownloadManager 能做什么、不能做什么2.1 三条技术路线的设计差异与适用场景在贴代码之前先明确路线。DownloadManager 是系统级下载服务应用进程退到后台甚至被划掉之后下载任务依然在系统进程里执行UI 只需要在下次启动时查询一次状态适合对下载行为没有特殊定制要求的场景。WorkManager 是任务调度框架解决的是“在满足约束的条件下执行有保证的任务”但它不会让任务脱离应用进程应用被强制停止之后任务也会停下次进程启动时才恢复。前台服务则是一个“保证进程优先级”的载体下载逻辑本身仍然写在应用进程里所以还要自己处理网络流和文件写入。在实际工程里我见过三类项目。第一类是公司内网工具只下载一个 APK 更新包用 DownloadManager 就能解决全部需求代码量最小也不用考虑进程优先级。第二类是在线教育类应用要下载几百 MB 的视频课件下载中允许暂停继续下载完成后还要做解密或转码DownloadManager 虽然也能做但要对系统通知和文件校验做大量补偿反而比自己在前台服务里控制网络流更繁琐。第三类是离线地图或离线语料包文件动辄几个 GB必须支持断点续传和并发控制这种场景我会直接用 OkHttp 在前台服务里自己写下载器完全绕过 DownloadManager 的黑匣子。另一个判断依据是任务生命周期。下面是三条路线在关键属性上的对比这个表在我每次选型时都会过一遍方案进程归属应用被划掉是否继续适合场景DownloadManager系统进程继续简单文件下载、应用更新包WorkManager应用进程停止下次启动恢复可延迟的一次性任务、重试任务前台服务应用进程停止进程重建后可能恢复长任务、需要自定义进度和业务控制如果下载任务需要“用户彻底退出应用之后还能继续”DownloadManager 是默认选择如果需要业务层深度控制下载过程则选前台服务方案。2.2 DownloadManager 请求构造URL、路径与网络策略DownloadManager.Request request new DownloadManager.Request(Uri.parse(downloadUrl)); request.setTitle(系统更新包); request.setDescription(正在后台下载更新文件); request.setNotificationVisibility( DownloadManager.Request.VISIBILITY_VISIBLE_NOTIFY_COMPLETED); request.setAllowedOverMetered(false); request.setAllowedOverRoaming(false); request.setDestinationInExternalPublicDir( Environment.DIRECTORY_DOWNLOADS, update-latest.apk); DownloadManager manager (DownloadManager) context.getSystemService(Context.DOWNLOAD_SERVICE); long downloadId manager.enqueue(request);这段代码里每一行都有讲究。setTitle 与 setDescription 是通知栏展示用的文案title 出现在状态栏下拉通知的标题行description 在通知的正文行。默认情况下用户点击通知拉起的是系统“下载内容”界面如果希望点击后跳转自己 App 的下载管理页需要额外用 PendingIntent 覆盖通知点击行为。setNotificationVisibility 控制通知的显示策略VISIBILITY_VISIBLE_NOTIFY_COMPLETED 表示从下载开始到结束一直展示进度并在完成后弹一次“下载完成”的通知VISIBILITY_VISIBLE 只显示进度完成后不弹通知VISIBILITY_HIDDEN 是完全不显示系统通知。这里有个教训VISIBILITY_HIDDEN 在部分系统定制版本上被当作不合法值表现是任务一直在排队但永远不开始原因是这些系统的 DownloadManager 实现里把隐藏任务挂在专用调度队列上。我在三款国产 ROM 上都遇到过后面统一改成了 VISIBILITY_VISIBLE 加应用内通知屏蔽。setAllowedOverMetered(false) 和 setAllowedOverRoaming(false) 分别控制计流量网络和漫游网络的下载权限。两个都设为 false在 Wi-Fi 条件下可下载在移动网络下任务会停留在 PENDING 状态而不是报错。这个状态非常容易让人误判成“系统没有响应”实际是调度器还在等待合适的网络。如果需求是“用户在下载页手动允许移动网络下载”就要在设置页保存选项下载时动态地写入请求。漫游开关只在移动网络且处于漫游时生效普通移动网络不受影响所以业务上只需提供“是否允许使用移动网络”一个开关就够了。setDestinationInExternalPublicDir 把文件写入公共 Downloads 目录。下载任务提交后系统会按文件名去重同一个名字会生成 1.apk、2.apk 这类后缀所以文件名最好用业务层唯一 ID 拼出来避免用户下次下载时拿到一个带数字后缀的副本。Android 10 之后分区存储对这个 API 的影响比较隐蔽公共目录下的文件对 App 来说变成不可直接 File 访问但 DownloadManager 记录本身会在 COLUMN_MEDIA_STORE_URI 里保留一个 MediaStore 引用查询这个字段可以拿回 Uri 并载入自己应用后面的避坑章节会具体展开。2.3 状态查询从 Cursor 读出进度、状态与失败原因DownloadManager.Query query new DownloadManager.Query(); query.setFilterById(downloadId); Cursor cursor null; try { cursor manager.query(query); if (cursor ! null cursor.moveToFirst()) { int status cursor.getInt( cursor.getColumnIndex(DownloadManager.COLUMN_STATUS)); long bytesDownloaded cursor.getLong( cursor.getColumnIndex(DownloadManager.COLUMN_BYTES_DOWNLOADED_SO_FAR)); long bytesTotal cursor.getLong( cursor.getColumnIndex(DownloadManager.COLUMN_TOTAL_SIZE_BYTES)); int reason cursor.getInt( cursor.getColumnIndex(DownloadManager.COLUMN_REASON)); switch (status) { case DownloadManager.STATUS_RUNNING: long percent bytesTotal 0 ? bytesDownloaded * 100 / bytesTotal : 0; // 更新 ViewModel 中的进度值 break; case DownloadManager.STATUS_SUCCESSFUL: String fileUri cursor.getString( cursor.getColumnIndex(DownloadManager.COLUMN_LOCAL_URI)); // 通知 UI 显示“已完成” break; case DownloadManager.STATUS_FAILED: // reason 的取值可查阅 DownloadManager 的常量定义 break; } } } finally { if (cursor ! null) { cursor.close(); } }查询返回的 Cursor 字段与 DownloadManager 内部数据库公开的视图一一对应。COLUMN_STATUS 取值有五类这里最容易混淆的是 PENDING 和 PAUSEDPENDING 表示还在等待调度网络条件不满足或系统资源受限时会停留在这里PAUSED 表示已经开始但被系统主动中断比如网络断开、存储空间不足、Wi-Fi 切换。如果任务长时间停在 PENDING多数是网络策略或系统后台限制导致不是 DownloadManager 本身挂了。COLUMN_LOCAL_URI 这个字段有坑在部分厂商定制系统上任务成功后返回的格式不一定是 file:// 开头有的返回 content://有的直接返回 null。安全做法是同时读 COLUMN_URI 和 COLUMN_LOCAL_URI 两个字段兜底取到值之后统一交给 FileProvider 转成 content URI 再给其他组件用。轮询间隔我一般设在 500ms 到 1000ms通过页面 Lifecycle 控制起停避免页面不可见时还在空转。如果只是单个任务也可以注册 BroadcastReceiver 监听 ACTION_DOWNLOAD_COMPLETE 替代轮询但多任务场景下广播里要自己解析 extra 里的下载 ID轮询反而更直接。3. 多任务下载与进度管理队列、通知栏与 UI 刷新3.1 多任务下载建立 URL 到任务 ID 的映射与去重产品说“一次下载多个文件”的瞬间代码复杂度就开始膨胀。第一步是去重同一个 URL 如果前一任务还没完成再次点击下载时最粗暴的做法是直接禁用按钮但产品往往要求“重新下载也可以”于是要建立一个以 URL 为 key 的任务表。下载任务提交后DownloadManager 返回一个 long 类型的 ID业务层必须要用这个 ID 作为后续查询、取消、重新下载的唯一凭证。public class DownloadTask { final long id; // DownloadManager 返回的任务 ID final String url; // 原始下载地址 final String fileName; // 目标文件名 long totalBytes; long downloadedBytes; int status; }用内存表维护当前任务还不够任务 ID 与 URL 的映射要持久化到 SharedPreferences。原因是应用进程可能在下载中途被系统杀掉重新启动后如果只从内存读任务列表就会把“正在下载”错判成“没有任务”。持久化之后冷启动时先从 SharedPreferences 读出每个 URL 对应的下载 ID再去 DownloadManager 查状态就能把未完成的任务重新接管回来。// 保存任务映射 SharedPreferences sp context.getSharedPreferences(download_tasks, Context.MODE_PRIVATE); sp.edit().putLong(url, downloadId).apply(); // 冷启动恢复 long savedId sp.getLong(url, -1); if (savedId ! -1) { DownloadManager.Query query new DownloadManager.Query(); query.setFilterById(savedId); Cursor cursor manager.query(query); // 判断状态已完成且文件校验通过的删除映射未完成的继续展示进度 }这里有一个业务决策点已完成的下载文件是否保留如果不保留任务映射可以删掉如果保留建议把文件名、URL、文件大小、SHA-256 写进一个 JSON 缓存文件和实际文件放同一目录校验时优先比对大小和摘要。我在项目里就是这么做的用户可以随时在下载页看到“文件已存在上次校验通过”避免每次冷启动都重新下载一遍。3.2 进度刷新ContentObserver 替代轮询顺带算实时速率DownloadManager 没有提供进度回调给业务层进度刷新主要有两种方式定时器轮询和 ContentObserver 监听。轮询代码简单直接但每隔几百毫秒执行一次数据库查询对电量和 IO 都不友好ContentObserver 是在下载数据库的下载条目发生变化时触发相当于系统回调更省资源。Uri downloadUri Uri.parse(content://downloads/my_downloads); getContentResolver().registerContentObserver( downloadUri, true, new DownloadObserver(new Handler(Looper.getMainLooper()))); class DownloadObserver extends ContentObserver { Override public void onChange(boolean selfChange, Uri uri) { super.onChange(selfChange, uri); // 下载过程中回调非常频繁这里要做 500ms 级别的节流 refreshProgress(); } }ContentObserver 的 onChange 在下载过程中会被高频触发收到的 uri 可能有多种变体不要在回调里直接做耗时操作。正确做法是把最新状态拷到 ViewModelUI 层再从 ViewModel 读数据。注意在页面销毁时调用 unregisterContentObserver否则极端内存紧张场景下会造成 ContentProvider 泄漏这个问题在低端机上非常容易出现。进度计算还有一种需求显示实时下载速度。速度不能直接用“下载量差值除以时间”因为间隔太短时系统缓存和网络波动会导致数值剧烈抖动。我一般取最近 3 秒的下载字节数做平均再换算成 bps 展示。long speedBytesPerSec 0; long elapsedTimeMs latestTimestamp - previousTimestamp; if (elapsedTimeMs 0) { speedBytesPerSec (latestBytes - previousBytes) * 1000L / elapsedTimeMs; }时间戳这里特别注意要用 SystemClock.elapsedRealtime()不要用 System.currentTimeMillis()。后者受系统时间修改的影响用户在下载过程中手动调整系统时间速率会算成负数界面上直接展示出“-3 MB/s”这种问题查起来非常玄学。3.3 通知栏体验自定义进度通知与系统通知的二选一DownloadManager 默认通知文案是系统固定的要改成“下载中剩余 xx 秒”这类自定义内容通常的做法是让 DownloadManager 保持静默自己发一条带进度条的通知。保留系统通知的同时再发自定义通知会出现两条进度不一致的通知用户看着非常乱。自定义进度通知的建设思路很简单下载状态变化时重建通知用同一个 NOTIFY_ID 调用 notify 更新NotificationCompat.Builder builder new NotificationCompat.Builder(context, CHANNEL_ID) .setContentTitle(下载应用更新包) .setContentText(进度 percent %) .setProgress(100, percent, false) .setSmallIcon(R.mipmap.ic_launcher) .setOnlyAlertOnce(true); notificationManager.notify(NOTIFY_ID, builder.build());setProgress 的第三个参数表示进度是否为不确定模式这里传 false 表示确定进度。如果下载阶段还没拿到总大小比如服务器没返回 Content-LengthCOLUMN_TOTAL_SIZE_BYTES 会是 0此时要传 true 显示不确定进度条等拿到总大小再切换回确定进度。用 DownloadManager 时还要注意任务被系统取消后系统通知可能消失但自定义通知不会要在查询状态发现任务已不在数据库时立刻 cancel 通知。4. 从 DownloadManager 切到 WorkManager何时切换、怎么切换4.1 切换触发条件业务控制、并发与断点续传业务面出现两种情况时我会把下载从 DownloadManager 迁移到 WorkManager 加前台服务。第一种是下载任务需要对业务层完全可控比如下载前要做登录态校验、下载后要做解压合并文件处理链路长DownloadManager 的“只管下载”模型满足不了。第二种是需要精细控制并发数、断点续传和重试策略DownloadManager 的内部调度对业务层是个黑匣子无法定制重试节奏也无法在应用内管理多个下载任务的优先级。WorkManager 解决的是“在满足约束条件时执行一次有保证的任务”它不是为“长时间且需要持续网络流”设计的所以实现长下载必须配合前台服务由 WorkManager 创建并持有前台服务在 doWork 里启动服务任务完成后再停掉。这样既享受 WorkManager 的重试和约束调度又拿到前台服务的进程优先级。整个过程里 WorkManager 负责调度前台服务负责面向用户的可见性两者协同。4.2 前台服务类型声明与权限适配从 targetSdk 33 到 34Android 12API 31开始强制要求为前台服务声明类型Android 14API 34进一步要求为部分类型申请细分权限。下载场景属于 dataSync 类型Manifest 里的写法如下service android:name.download.DownloadForegroundService android:exportedfalse android:foregroundServiceTypedataSync / uses-permission android:nameandroid.permission.FOREGROUND_SERVICE / uses-permission android:nameandroid.permission.FOREGROUND_SERVICE_DATA_SYNC /第二个权限是 Android 14 开始强制要求的targetSdk 34 以下可以不加但把 targetSdk 提到 34 之后不加会直接抛 SecurityException。这里有一个版本适配顺序的问题先把 targetSdk 提到 33确认前台服务类型声明在 Manifest 里生效再提 34 加细分权限。如果反过来旧 Manifest 没有声明类型直接上 Android 14 设备前台服务一启动就崩而且是只有真机才能复现的崩溃。4.3 实现一个可重试并能断点续传的下载 WorkerWorkManager 的 Worker 使用 CoroutineWorker 会比普通 Worker 更适合 IO 操作因为 doWork 是 suspend 函数可以直接用 OkHttp 的异步调用。下面是最小可用的下载 Worker 实现class DownloadWorker( context: Context, params: WorkerParameters ) : CoroutineWorker(context, params) { override suspend fun doWork(): Result { val fileUrl inputData.getString(KEY_URL) ?: return Result.failure() val fileName inputData.getString(KEY_FILE_NAME) ?: default.bin val targetFile File( applicationContext.getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS), fileName ) val notificationManager applicationContext.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager // 提升为前台服务保证任务期间进程优先级 val notification buildNotification(0, 0) setForegroundAsync( createForegroundInfo( NOTIFICATION_ID, notification ) ) return try { downloadWithOkHttp(fileUrl, targetFile, notificationManager) Result.success() } catch (e: IOException) { Result.retry() } } }setForegroundAsync 会在 Worker 执行期间启动关联的前台服务。任务执行到一半进程被系统杀掉之后WorkManager 会在下次满足约束条件时重新调度但重新执行时文件已经写了一半如果直接重写整个文件会浪费大量流量。断点续传的常见做法是每次下载前先查 targetFile.length()如果大于 0 说明之前中断过用 OkHttp 的 Range 头从文件末尾续传val request Request.Builder() .url(fileUrl) .header(Range, bytes$startByte-) .build() val response okHttpClient.newCall(request).execute() val input response.body?.byteStream() val output FileOutputStream(targetFile, append true) input?.copyTo(output)Range 续传必须对服务器做兼容性判断。有些 CDN 不认 Range 头直接返回 200 全量数据这时如果继续往文件末尾追加就会把新数据接到旧文件后面生成一个损坏文件。所以写文件前先判断 response.code206 表示分段返回可以续写200 表示服务端忽略 Range 头此时要删除原文件重新下载。这段判断逻辑漏掉的后果是用户下载完成但校验永远失败百思不得其解。5. 避坑下载场景最常见的 5 类问题与排查方法5.1 下载状态显示成功但文件大小为 0现象DownloadManager 查询返回 STATUS_SUCCESSFUL但目标目录中文件大小是 0 字节或者文件根本不存在。原因这是分区存储与 DownloadManager 路径策略叠加导致的问题。Android 10 以后如果目标路径指向公共目录DownloadManager 会把文件写入系统 Downloads 集合应用直接用 File 路径访问会因分区存储隔离而失败文件大小为 0 的另一个常见原因是服务器返回了 Content-Length: 0 且 HTTP 状态码为 200DownloadManager 把这种响应判定为下载成功。解决下载完成后不要依赖文件路径判断结果通过查询 COLUMN_MEDIA_STORE_URI 拿到最终落地位置同时在发起正式下载前先请求一次 HEAD确认 Content-Length 大于 0 再入队。如果服务端本身不稳定还要在下载完成后把文件实际大小与 Content-Length 比对不一致时主动进入重试分支不要直接展示“下载完成”。5.2 锁屏后下载被挂起进程重启也无法恢复现象手机锁屏放一晚上第二天打开应用下载任务一直处于 PAUSED 状态或者 WorkManager 任务报错日志里找不到明显异常。原因锁屏后系统进入 Doze 模式Wi-Fi 可能被暂停。DownloadManager 对 Doze 的适配比应用内任务好一些但仍躲不过厂商定制系统的“深度休眠”机制省电策略会把后台进程的网络栈挂起。WorkManager 在 Doze 模式下默认只在维护窗口执行任务长时间无网络导致任务失败。解决下载任务所在的进程要持有 PARTIAL_WAKE_LOCK任务完成或失败时释放同时在用户首次发起大文件下载时走一次系统电量优化白名单的引导流程。这个引导需要用 ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZATIONS 拉起系统设置页文案写清楚“不加入白名单可能导致下载中断”。这一步是产品决策但技术侧必须把入口埋好否则锁屏断下载的问题无法根治。5.3 DownloadManager 通知栏残留点击后也不消失现象任务完成后系统通知一直驻留在通知栏用户点击通知后没有反应通知也不消失。原因DownloadManager 在 setNotificationVisibility 设置为 VISIBILITY_VISIBLE_NOTIFY_COMPLETED 时系统通知的点击行为依赖于 ACTION_DOWNLOAD_COMPLETE 广播。如果应用没有注册对应的 BroadcastReceiver通知不会自动清理部分定制系统甚至不会发送这个广播。解决在 Manifest 中注册一个 BroadcastReceiver 接收 ACTION_DOWNLOAD_COMPLETE在 onReceive 里用 NotificationManager.cancel(downloadId) 清理通知。receiver android:name.dl.DownloadCompleteReceiver android:exportedtrue intent-filter action android:nameandroid.intent.action.DOWNLOAD_COMPLETE / /intent-filter /receiver注意 receiver 的 exported 属性必须设置为 true否则系统广播无法到达应用。兼容性兜底是在查询状态发现任务已不在数据库时主动 cancel 所有与本任务关联的通知防止出现长期残留。5.4 系统通知与自定义通知重复出现进度两边不一致现象同一个下载任务既有系统通知又有应用内自定义通知两端进度条显示不一致用户看着很混乱。原因业务层在 DownloadManager 未设置静默的情况下又创建了自定义进度通知两套通知同时展示。自定义通知的进度用轮询刷新网络波动时应用内进度条可能先跳后回退与系统通知的进度天然不同步。解决DownloadManager 请求里把 setNotificationVisibility 固定为 VISIBILITY_VISIBLE并屏蔽系统通知的声音和震动由应用完全接管通知展示。如果目标设备上 VISIBILITY_HIDDEN 也能正常工作也可以直接使用 HIDDEN但要提前做机型判断。进度跳动则需要在更新时做差值限制单次进度差超过 5% 才刷新通知低于 5% 只更新内存数据避免通知栏高频通知造成电量和视觉的双重开销。5.5 下载了一半重新进入页面又从零开始现象用户从下载页面退出再进来同一个文件重新走一遍下载流程前面已经下载的部分被丢弃。原因页面进入时直接调用了 manager.enqueue()没有先查询历史任务状态相当于每次进入页面都新建了下载任务。DownloadManager 并不会对相同 URL 自动去重旧任务未取消新任务又启动磁盘上最终可能出现多个重复文件。解决严格建立“URL 到 downloadId”映射表进入页面时先查映射已存在的任务直接绑定状态并展示进度只有任务状态为 SUCCESSFUL 且文件校验通过时才允许发起新下载。代码层面再叠加一层保护查询状态时如果发现任务 ID 对应的 lastModified 时间在 5 秒内有更新说明下载仍在进行直接禁止创建新任务。从那以后我每次给下载模块加功能都强制先走一遍“先查旧任务、再校验文件、最后更新通知”的流程少了很多半夜被叫起来改 Bug 的次数。6. 下载完成不等于成功文件完整性校验与收尾习惯6.1 用 HEAD 请求拿到元数据再用 SHA-256 收尾下载完成后的第一件事不是弹 Toast而是校验文件。最轻量的方案是下载前发一次 HEAD 请求记录 Content-Length 和服务器返回的 ETag下载完成后比对大小和摘要。如果服务器没有提供 MD5 或 ETag就在应用内计算 SHA-256fun verifyFile(file: File, expectedSize: Long, expectedSha256: String?): Boolean { if (file.length() ! expectedSize) return false if (expectedSha256 null) return true val digest MessageDigest.getInstance(SHA-256) file.inputStream().use { input - val buffer ByteArray(8192) while (true) { val len input.read(buffer) if (len -1) break digest.update(buffer, 0, len) } } return digest.digest().joinToString() { %02x.format(it) } expectedSha256 }这个函数里 buffer 取 8192 字节是折中选择避免一次读入过大文件把内存顶上去。对大文件计算哈希是 IO 密集操作要放在协程或线程池里跑不能直接在主线程执行。6.2 我固定下来的下载模块收尾清单从这个项目开始我给每个下载需求都定了四步收尾第一步URL 到任务 ID 的映射落盘第二步文件写入后立刻比对大小与摘要第三步通知栏状态与任务状态同步失败或取消时移除通知第四步检查失败重试策略是否有上限避免无限重试消耗用户流量。这套习惯是从一次真实的线上事故里总结出来的。某个下载需求上线后用户反馈“下载完成但安装失败”排查到最后发现是服务器返回了错误页面但状态码是 200DownloadManager 把 HTML 当成了目标文件。加了摘要校验之后这种问题会在用户看到“下载完成”之前就被拦截。从那以后我每次做完下载模块都强制把校验链路走一遍再交付测试。希望这套思路能帮你在做自己的下载功能时少踩几个坑。本文还有配套的精品资源点击获取
