Flutter 缓存管理库 flutter_cache_manager 详解
flutter_cache_manager 是 Flutter 应用中用于下载和管理文件缓存的常用库。它支持将文件存储在应用的缓存目录中,并通过配置控制缓存的有效期和数量。该库利用 HTTP 的 Cache-Control 头部来高效地提取和验证文件。
核心功能与用法
基础文件获取
CacheManager 提供了多种方式来获取文件,开发者可以根据具体场景选择合适的方法。
- 获取单个文件:最简单的方式是调用
getSingleFile。var file = await DefaultCacheManager().getSingleFile(url); - 流式获取:
getFileStream返回一个流,第一个结果是已缓存的文件(如果有),后续结果包含正在下载的文件。// 仅获取缓存或开始下载 Stream<FileResponse> stream = cacheManager.getFileStream(url); // 带进度回调,当缓存未命中时触发下载进程 Stream<FileResponse> streamWithProgress = cacheManager.getFileStream(url, withProgress: true); - 直接下载:
downloadFile直接从网络下载文件,不优先检查缓存。 - 仅从缓存读取:
getFileFromCache只尝试从本地缓存提取。如果缓存中没有文件,则返回空值(no file)。 - 手动添加文件:
putFile允许向缓存中添加一个新文件,无需经过网络下载流程。 - 清理操作:
removeFile:移除指定的单个文件。emptyCache:清空所有缓存文件。
图片缓存 (ImageCacheManager)
对于图片资源,可以使用 ImageCacheManager Mixin(DefaultCacheManager 默认已集成)。它提供了 getImageFile 方法,支持在缓存前对图像进行尺寸调整。
Stream<FileResponse> getImageFile(String url, {
String key,
Map<String, String> headers,
bool withProgress,
int maxHeight, // 目标最大高度
int maxWidth, // 目标最大宽度
})
- 尺寸调整:URL 获取的图像会根据配置参数自动调整大小,调整后的图像会被存储到缓存中。通常它会保持现有的图片比例。
- 原始缓存:如果使用其他高度/宽度参数,原始图像也会被缓存并用于调整,确保在不同显示需求下都能提供最佳质量。
自定义配置
可以通过创建新的 CacheManager 实例来实现更精细的管理。注意:不要使用相同的 key 创建多个 CacheManager 实例,否则会导致缓存冲突。
通常建议将管理器作为单例创建,或者通过 Provider 等状态管理方案在应用顶层提供。
配置参数说明
构造方法的 key 参数是强制性的,其他变量均为可选。以下是一个完整的自定义配置示例:
class CustomCacheManager {
static const key = 'customCacheKey';
static CacheManager instance = CacheManager(
Config(
key,
// 缓存过期时间:7 天后视为过期
stalePeriod: const Duration(days: 7),
// 缓存对象最大数量:最多保留 20 个文件
maxNrOfCacheObjects: 20,
// 元数据存储仓库:使用 SQLite 数据库存储缓存信息
repo: JsonCacheInfoRepository(databaseName: key),
// 文件系统实现:IOFileSystem 表示使用本地文件系统
fileSystem: IOFileSystem(key),
// 文件服务:HttpFileService 负责网络请求
fileService: HttpFileService(),
),
);
}


