Flutter如何实现AssetImage加载失败显示备用兜底图片

不要用全局自定义AssetBundle实现这类需求，该方案对全局逻辑侵入性极强，很容易因代理逻辑疏漏导致所有资源加载异常。直接利用Flutter自带的组件错误回调能力即可实现稳定的兜底效果，不会影响正常资源加载。

可复用兜底组件封装 #

核心逻辑是通过Image组件内置的errorBuilder参数，监听资源加载异常，异常触发时自动渲染预设的备用资源，同时对兜底资源本身增加异常防护，避免兜底资源加载失败导致红屏。

import 'package:flutter/widgets.dart';

class FallbackAssetImage extends StatelessWidget {
  const FallbackAssetImage({
    super.key,
    required this.assetPath,
    required this.fallbackAssetPath,
    this.width,
    this.height,
    this.fit,
    this.alignment = Alignment.center,
    this.repeat = ImageRepeat.noRepeat,
  });

  /// 待加载的目标资源路径
  final String assetPath;
  /// 兜底资源路径，需提前在pubspec.yaml中正确声明
  final String fallbackAssetPath;
  final double? width;
  final double? height;
  final BoxFit? fit;
  final Alignment alignment;
  final ImageRepeat repeat;

  @override
  Widget build(BuildContext context) {
    return Image(
      image: AssetImage(assetPath),
      width: width,
      height: height,
      fit: fit,
      alignment: alignment,
      repeat: repeat,
      errorBuilder: (context, error, stackTrace) {
        // 加载失败时渲染兜底图
        return Image(
          image: AssetImage(fallbackAssetPath),
          width: width,
          height: height,
          fit: fit,
          alignment: alignment,
          repeat: repeat,
          errorBuilder: (context, _, __) {
            // 兜底图也加载失败时返回空容器，避免红屏
            return SizedBox(width: width, height: height);
          },
        );
      },
    );
  }
}

使用方式 #

直接替换项目中原有加载Asset图片的Image组件即可，例如原代码：

Image(image: AssetImage('images/myImage.png'))

替换为：

FallbackAssetImage(
  assetPath: 'images/myImage.png',
  fallbackAssetPath: 'images/fallbackImage.png',
  width: 100,
  height: 100,
  fit: BoxFit.cover,
)

自定义AssetBundle方案失效原因 #

• 多数自定义AssetBundle的错误实现，重写load/loadString方法时没有将非目标资源的加载请求正确代理给系统默认的rootBundle，所有资源读取请求被拦截后无法正常返回数据，直接导致原本存在的正常资源加载失败
• 全局自定义AssetBundle会影响应用内所有资源加载逻辑，只要存在逻辑疏漏就会引发全局资源异常，排查成本极高，不适合用来实现单类资源的兜底逻辑

进阶全局默认配置（可选） #

如果不想每次调用都传入兜底路径，可以封装全局默认兜底配置，统一使用指定的备用图片：

/// 全局默认兜底资源路径
const String kDefaultFallbackImgPath = 'images/fallbackImage.png';

class CommonAssetImage extends StatelessWidget {
  const CommonAssetImage({
    super.key,
    required this.assetPath,
    this.fallbackPath = kDefaultFallbackImgPath,
    this.width,
    this.height,
    this.fit,
  });

  final String assetPath;
  final String fallbackPath;
  final double? width;
  final double? height;
  final BoxFit? fit;

  @override
  Widget build(BuildContext context) {
    return FallbackAssetImage(
      assetPath: assetPath,
      fallbackAssetPath: fallbackPath,
      width: width,
      height: height,
      fit: fit,
    );
  }
}

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