flutter pub add background_downloader基于插件公开信息、社区数据与项目使用情况整理的选型参考。
一个跨平台的 Flutter 包，可在 Android、iOS、macOS、Windows 和 Linux 上实现后台文件下载和上传。它允许开发者定义下载/上传任务，将其排队执行，并实时监控进度。设计注重可靠性和效率，可处理网络中断，并在应用重启后继续任务。适用于需要大文件传输且不阻塞 UI 的应用。
以下为关联源码仓库的 README 原文快照，最新内容请访问源码仓库。
A robust, multi-platform background file transfer plugin for Flutter supporting background downloads, uploads, and data tasks across iOS, Android, MacOS, Windows, and Linux.
Uses native URLSession on iOS and MacOS, and DownloadWorker (WorkManager) / JobService (UIDT) on Android, ensuring transfers continue even when your app is in the background or terminated by the OS.
The easiest and most powerful way to use background_downloader is via the Transfer API.
On app startup (e.g. in main() or your top-level initState()), call FileDownloader().start(autoCleanDatabase: true) to activate persistent database tracking, automatically purge old task records, and reconcile transfers that completed or were interrupted while the app was suspended or closed. Then simply define a DownloadTask or UploadTask, start it using FileDownloader().transfers.start, and receive a reactive Transfer handle:
// 1. Activate database tracking & auto-cleanup on app launch (recommended)
await FileDownloader().start(autoCleanDatabase: true);
// 2. Configure notifications (recommended for userInitiated / UIDT tasks)
FileDownloader().configureNotification(
running: const TaskNotification('Downloading', '{filename}'),
complete: const TaskNotification('Complete', '{filename}'),
progressBar: true,
tapOpensFile: true,
);
// 3. Define the task with smart hints
final task = DownloadTask(
url: 'https://example.com/large_video.mp4',
filename: 'video.mp4',
transferHints: {TransferHint.userInitiated, TransferHint.largeFile},
);
// 4. Start the transfer
final transfer = await FileDownloader().transfers.start(task);
// 5. Directly await the completed File:
final file = await transfer.file;
print('Downloaded to: ${file.path}');
Transfer?transfer.file for the completed File, transfer.result for the TaskStatusUpdate, or transfer.responseBody for server response text.ValueNotifier bindings for Flutter widgets: transfer.progressNotifier (clean 0.0–1.0), transfer.statusNotifier, transfer.networkSpeedNotifier, transfer.timeRemainingNotifier, and transfer.notificationTapNotifier.TransferProgressBar, TransferButton, and TransferListTile.await transfer.pause(), await transfer.resume(), await transfer.cancel().FileDownloader().transfers.startAll(tasks, onProgress: ...).TransferHint (userInitiated, largeFile, smallFile, lowPriority, useSuggestedFilename, binaryUpload) to configure optimal priority, Android 14+ UIDT, and pause resilience automatically.transfer.notificationTapNotifier or open downloaded files automatically with tapOpensFile: true.FileDownloader.scoped('my_feature').stallTimeout).👉 Read the complete Transfers Guide
For specialized workflows or legacy integration, FileDownloader continues to provide direct lower-level methods:
download)Execute a task and wait for completion in a single call with inline callbacks:
final result = await FileDownloader().download(
task,
onProgress: (progress) => print('Progress: ${progress * 100}%'),
onStatus: (status) => print('Status: $status'),
);
if (result.status == TaskStatus.complete) {
print('Download finished!');
}
enqueue / enqueueAll)For pipeline architectures where you monitor tasks centrally via a global stream or callbacks:
// 1. Listen centrally to task updates (typically in initState)
FileDownloader().updates.listen((update) {
switch (update) {
case TaskStatusUpdate():
print('Task ${update.task.taskId} status: ${update.status}');
case TaskProgressUpdate():
print('Task ${update.task.taskId} progress: ${update.progress * 100}%');
}
});
// 2. Start the downloader and activate persistent database tracking
FileDownloader().start();
// 3. Enqueue background tasks
final enqueued = await FileDownloader().enqueue(task);
To ensure file paths work robustly across platform restarts (especially on iOS and Android where container paths can change between app launches), the downloader uses a combination of BaseDirectory, directory (subdirectory) and filename:
BaseDirectory: One of .applicationDocuments, .temporary, .applicationSupport, or .applicationLibrary.directory: An optional subdirectory within the base directory.filename: The name of the file (or DownloadTask.suggestedFilename / '?' to use the server's Content-Disposition header).See File Storage for details on shared and scoped storage.
Check the Topic Index or specific guides:
Transfer handles, reactive notifiers, UI widgets, batches, and scoping.No setup is required for Windows or Linux.
Requires Kotlin 2.1.0 or above. For modern Flutter projects, ensure your android/settings.gradle has:
plugins {
id "org.jetbrains.kotlin.android" version "2.1.0" apply false
}
No special setup is required. By default iOS requires HTTPS connections (see Apple ATS Configuration if HTTP is required).
Add the client network entitlement to macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:
<key>com.apple.security.network.client</key>
<true/>
allowPause: true (or TransferHint.largeFile / userInitiated), which automatically resumes across 9-minute cycles, or set priority: 0 on Android 14+ to use UIDT (see parameters.md).依赖清单 8 项
^2.6.0^1.15.0>=6.1.3 <8.0.0^1.1.0^1.0.2^2.0.0^1.8.1^2.0.2