是什么
cached_network_image是一个 网络图片加载 + 本地缓存 的库。相比 Image.network，它会 自动缓存图片到本地磁盘，下次再加载时优先读取缓存，从而减少流量、加快显示速度。
核心功能：
- 图片缓存：首次加载时下载并保存到本地，之后直接读取缓存。
- 加载占位图：图片未加载完成时可以显示
placeholder。 - 加载错误图：如果图片地址错误或网络失败，显示
errorWidget。 - 缓存策略：支持自定义缓存大小、过期时间。
适用场景：
- 头像、商品图、文章配图等需要频繁加载的网络图片。
- 提升性能，避免每次都重新下载图片。
常用参数
| 参数名 | 类型 | 作用 | 示例 |
|---|---|---|---|
imageUrl |
String |
图片的网络地址（必填） | "https://example.com/image.jpg" |
placeholder |
Widget Function(BuildContext, String)? |
占位图（加载中时显示） | (ctx, url) => CircularProgressIndicator() |
errorWidget |
Widget Function(BuildContext, String, dynamic)? |
错误图（加载失败时显示） | (ctx, url, err) => Icon(Icons.error) |
width |
double? |
图片宽度 | 200 |
height |
double? |
图片高度 | 200 |
fit |
BoxFit? |
图片适配方式 | BoxFit.cover |
fadeInDuration |
Duration |
淡入动画时长 | Duration(milliseconds: 500) |
fadeOutDuration |
Duration |
淡出动画时长 | Duration(milliseconds: 100) |
cacheKey |
String? |
自定义缓存 key（默认用 url） | "user_profile_pic" |
httpHeaders |
Map<String, String>? |
自定义 HTTP 请求头 | {"Authorization": "Bearer xxx"} |
placeholder
字面意思：占位图。
作用：当图片还在 下载 / 解码 过程中时显示的 Widget。
典型用法：
- 加载进度条 (
CircularProgressIndicator) - 灰色占位背景
- 默认图片
placeholder: (context, url) => Center(
child: CircularProgressIndicator(), // 正在加载时显示转圈
)
errorWidget
字面意思：错误时显示的 Widget。
作用：当图片加载 失败（比如网络断开、404 链接错误）时显示。
典型用法：
- 错误图标 (
Icon(Icons.error)) - 默认替代图片
- 提示文字
errorWidget: (context, url, error) => Icon(
Icons.error,
color: Colors.red,
size: 50,
)
过程理解
图片加载的三个阶段：
- 正在加载中 → 显示
placeholder - 加载成功 → 显示目标图片
- 加载失败 → 显示
errorWidget
比如有个商品列表，每张图都要从网络获取：
用户网络慢 → 显示加载圈圈（
placeholder）。图片 404 → 显示一个红色错误图标（
errorWidget）。图片加载成功 → 显示真实商品图。
缓存存在哪里
在 cached_network_image 里，**缓存其实是由 flutter_cache_manager 这个库负责管理**的。
缓存的图片会存到 本地磁盘（不是内存里），具体路径因平台而异：
Android：存在应用的 临时缓存目录（
/data/data/<package_name>/cache/），比如：/data/data/com.example.myapp/cache/libCachedImageData/iOS：存在 App 的 Caches 目录（
NSCachesDirectory），比如：/var/mobile/Containers/Data/Application/<UUID>/Library/Caches/libCachedImageData/
此外，这是 应用级缓存，当用户清除应用缓存/卸载应用时，缓存会被删除。如果超过默认最大缓存大小（一般是200 MB），超过会自动清理。
使用
首先需要安装包：
flutter pub add cached_network_image
代码使用
import 'package:cached_network_image/cached_network_image.dart';
CachedNetworkImage(
imageUrl: "https://example.com/image.jpg",
placeholder: (context, url) => CircularProgressIndicator(), // 占位图
errorWidget: (context, url, error) => Icon(Icons.error), // 错误图
width: 200,
height: 200,
fit: BoxFit.cover,
)
