Flutter：资源图片缺失时显示占位图的实现及报错解决

问题本质 #

你不能直接将返回Future<Widget>的函数作为Widget放进Widget树——Flutter要求Widget必须是同步创建的实例，而Future是异步操作的结果，需要专门的组件来处理异步状态与Widget树的衔接。

解决方案1：用FutureBuilder处理异步逻辑 #

通过FutureBuilder监听异步加载的状态，根据等待、成功、失败三种状态返回对应Widget：

// 构建带异步加载逻辑的图片Widget
Widget buildTeamImage(String image) {
  return FutureBuilder<Widget>(
    future: _getValidImage(image),
    builder: (context, snapshot) {
      // 加载中显示空占位或加载动画
      if (snapshot.connectionState == ConnectionState.waiting) {
        return ClipRRect(
          borderRadius: BorderRadius.circular(100),
          child: SizedBox(width: 60, height: 60),
        );
      }
      // 加载完成后返回对应Widget，失败时用默认占位
      return snapshot.data ?? ClipRRect(
        borderRadius: BorderRadius.circular(100),
        child: Image.asset(
          'assets/images/default_avatar.png', // 替换为你的占位图路径
          height: 60,
          width: 60,
          fit: BoxFit.fill,
        ),
      );
    },
  );
}

// 异步检查图片是否存在，返回对应Widget
Future<Widget> _getValidImage(String image) async {
  final assetPath = 'assets/team/${image}.png';
  try {
    await rootBundle.load(assetPath);
    return ClipRRect(
      borderRadius: BorderRadius.circular(100),
      child: Image.asset(
        assetPath,
        height: 60,
        width: 60,
        fit: BoxFit.fill,
      ),
    );
  } catch (_) {
    // 图片不存在时返回占位Widget
    return ClipRRect(
      borderRadius: BorderRadius.circular(100),
      child: Image.asset(
        'assets/images/default_avatar.png',
        height: 60,
        width: 60,
        fit: BoxFit.fill,
      ),
    );
  }
}

解决方案2：利用Image.asset自带的错误处理（更简洁） #

其实没必要手动做异步检查，Image.asset内置了errorBuilder参数，可以直接处理加载失败的场景，代码更精简：

ClipRRect(
  borderRadius: BorderRadius.circular(100),
  child: Image.asset(
    'assets/team/${image}.png',
    height: 60,
    width: 60,
    fit: BoxFit.fill,
    // 加载失败时触发，返回占位图
    errorBuilder: (context, error, stackTrace) {
      return Image.asset(
        'assets/images/default_avatar.png',
        height: 60,
        width: 60,
        fit: BoxFit.fill,
      );
    },
  ),
)

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