Flutter使用Image.network加载头像时遇连接握手终止错误怎么办？

问题场景 #

使用Flutter的Image.network加载Gravatar头像时，出现以下错误：

Failed host lookup
Connection terminated during handshake

原代码片段：

Widget authorAvatarName() {
  return Row(
    children: [
      Image.network('https://secure.gravatar.com/avatar/675e8f6e91740a40a4c12abbbd03ef75?s=96&d=https%3A%2F%2Fshiftdelete.net%2Fwp-content%2Fthemes%2Fshiftdelete%2Fassets%2Fimg%2Favatar.png&r=g',
        width: 32,
        height: 32,
        fit: BoxFit.cover,
        loadingBuilder: (context, child, loadingProgress) {
          if (loadingProgress == null) {
            return child;
          }
          return Center(
            child: CircularProgressIndicator(),
          );
        },
      ),
      const SizedBox(width: 8),
      Text(
        postDetailProvider.authorName,
        style: TextStyles.smallTextStyle.copyWith(
          color: isDarkMode == true
              ? ColorConstants.lightGrey
              : ColorConstants.darkBlack,
        ),
      )
    ],
  );
}

核心原因 #

原URL中包含HTML转义字符&，Flutter的Image.network无法正确解析这种转义后的URL，导致主机查找失败；另外Gravatar的URL可能存在重定向，原生Image.network的处理能力有限。

解决步骤 #

1. 修复URL中的转义字符

将URL里所有的&替换为普通的&，这是最直接的修复方式。修复后的URL：
https://secure.gravatar.com/avatar/675e8f6e91740a40a4c12abbbd03ef75?s=96&d=https%3A%2F%2Fshiftdelete.net%2Fwp-content%2Fthemes%2Fshiftdelete%2Fassets%2Fimg%2Favatar.png&r=g

修改后的代码（增加错误处理方便排查）：

Widget authorAvatarName() {
  return Row(
    children: [
      Image.network(
        'https://secure.gravatar.com/avatar/675e8f6e91740a40a4c12abbbd03ef75?s=96&d=https%3A%2F%2Fshiftdelete.net%2Fwp-content%2Fthemes%2Fshiftdelete%2Fassets%2Fimg%2Favatar.png&r=g',
        width: 32,
        height: 32,
        fit: BoxFit.cover,
        loadingBuilder: (context, child, loadingProgress) {
          if (loadingProgress == null) return child;
          return const Center(child: CircularProgressIndicator());
        },
        // 添加错误占位，避免页面崩溃
        errorBuilder: (context, error, stackTrace) {
          return const Icon(Icons.person, size: 32);
        },
      ),
      const SizedBox(width: 8),
      Text(
        postDetailProvider.authorName,
        style: TextStyles.smallTextStyle.copyWith(
          color: isDarkMode ? ColorConstants.lightGrey : ColorConstants.darkBlack,
        ),
      )
    ],
  );
}

2. 用第三方包优化图片加载（可选）

如果修复URL后仍存在重定向或加载不稳定问题，推荐使用cached_network_image包，它专门处理图片缓存、重定向和错误情况：

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

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

• 替换Image.network为CachedNetworkImage：

import 'package:cached_network_image/cached_network_image.dart';

Widget authorAvatarName() {
  return Row(
    children: [
      CachedNetworkImage(
        imageUrl: 'https://secure.gravatar.com/avatar/675e8f6e91740a40a4c12abbbd03ef75?s=96&d=https%3A%2F%2Fshiftdelete.net%2Fwp-content%2Fthemes%2Fshiftdelete%2Fassets%2Fimg%2Favatar.png&r=g',
        width: 32,
        height: 32,
        fit: BoxFit.cover,
        placeholder: (context, url) => const CircularProgressIndicator(),
        errorWidget: (context, url, error) => const Icon(Icons.person, size: 32),
      ),
      const SizedBox(width: 8),
      Text(
        postDetailProvider.authorName,
        style: TextStyles.smallTextStyle.copyWith(
          color: isDarkMode ? ColorConstants.lightGrey : ColorConstants.darkBlack,
        ),
      )
    ],
  );
}

3. 检查网络权限（基础排查）

确保App已获取网络权限：

• Android：在android/app/src/main/AndroidManifest.xml中添加：

<uses-permission android:name="android.permission.INTERNET"/>

• iOS：若访问非HTTPS资源需配置NSAppTransportSecurity，但本次使用HTTPS，一般无需额外配置。

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