Flutter实现网络图片加载失败时显示本地资源图片的方法

方案1：利用Image.network的errorBuilder（原生无依赖） #

这是最轻量化的原生实现方式，通过Image.network自带的错误回调，在网络图片加载失败时返回本地资源图片。

String imageNetworkLink = "someUnstableLink";

Image.network(
  imageNetworkLink,
  // 可选：加载过程中显示的占位组件
  loadingBuilder: (context, child, loadingProgress) {
    if (loadingProgress == null) return child;
    return const Center(child: CircularProgressIndicator());
  },
  // 加载失败时渲染本地图片
  errorBuilder: (context, error, stackTrace) {
    return Image.asset('assets/images/error_placeholder.png');
    // 也可以用AssetImage的形式：
    // return const Image(image: AssetImage('assets/images/error_placeholder.png'));
  },
  fit: BoxFit.cover,
);

注意：本地资源必须在pubspec.yaml中正确声明，示例配置如下：

flutter:
  assets:
    - assets/images/error_placeholder.png

方案2：使用FadeInImage实现过渡+ fallback（原生无依赖） #

FadeInImage原生支持占位图与目标图的渐显过渡，同时可以通过imageErrorBuilder处理加载失败的情况，兼顾用户体验与容错逻辑。

String imageNetworkLink = "someUnstableLink";

FadeInImage(
  // 加载中和加载失败的基础占位图
  placeholder: const AssetImage('assets/images/loading_placeholder.png'),
  // 目标网络图片
  image: NetworkImage(imageNetworkLink),
  // 网络图加载失败时替换为错误占位图
  imageErrorBuilder: (context, error, stackTrace) {
    return Image.asset('assets/images/error_placeholder.png');
  },
  fit: BoxFit.cover,
);

方案3：第三方包cached_network_image（适合复杂场景） #

如果需要图片缓存、更灵活的占位/错误逻辑，cached_network_image是不错的选择，它内置了完整的错误 fallback 机制，还能自动缓存已加载的网络图片。

首先在pubspec.yaml中添加依赖：

dependencies:
  cached_network_image: ^3.2.3 # 请使用最新版本

然后实现代码：

String imageNetworkLink = "someUnstableLink";

CachedNetworkImage(
  imageUrl: imageNetworkLink,
  placeholder: (context, url) => const CircularProgressIndicator(),
  // 加载失败时显示本地图片
  errorWidget: (context, url, error) => Image.asset('assets/images/error_placeholder.png'),
  fit: BoxFit.cover,
);

内容的提问来源于stack exchange，提问作者Gwhyyy