Flutter加载TMDB网络图片出现HandshakeException握手终止异常怎么解决

该Connection terminated during handshake握手异常是Flutter默认网络请求组件与目标站点SSL验证、TLS版本兼容或请求头规则不匹配导致的，Postman能正常请求是因为它的网络栈默认携带了更完整的请求配置、对SSL证书的兼容策略更宽松。

方案1：调试阶段临时关闭SSL校验 #

该方案仅适用于本地调试，禁止在生产环境使用，存在安全风险。
在main.dart中runApp执行前添加自定义HttpOverrides配置：

import 'dart:io';
import 'package:flutter/material.dart';

class MyHttpOverrides extends HttpOverrides {
  @override
  HttpClient createHttpClient(SecurityContext? context) {
    return super.createHttpClient(context)
      ..badCertificateCallback = (X509Certificate cert, String host, int port) => true;
  }
}

void main() {
  HttpOverrides.global = MyHttpOverrides();
  runApp(const MyApp());
}

配置后重新运行项目即可正常加载图片。

方案2：自定义请求加载图片（生产可用） #

不使用默认的Image.network，自行通过http库发起请求，可自定义请求头、SSL配置，完全匹配站点要求：

1. 先添加http依赖到pubspec.yaml
2. 封装图片加载逻辑：

import 'package:http/http.dart' as http;

// 组件内使用
Future<Image> loadTmdbImage(String url) async {
  final response = await http.get(
    Uri.parse(url),
    // 可按需添加请求头，比如User-Agent、Referer等匹配站点校验规则
    headers: {
      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Safari/537.36"
    }
  );
  return Image.memory(response.bodyBytes, height: 200, width: 160, fit: BoxFit.cover);
}

// 界面中用FutureBuilder包裹
SizedBox(
  height: 200,
  width: 160,
  child: ClipRRect(
    child: FutureBuilder<Image>(
      future: loadTmdbImage('https://image.tmdb.org/t/p/w200/xmbU4JTUm8rsdtn7Y3Fcm30GpeT.jpg'),
      builder: (context, snapshot) {
        if (snapshot.hasData) {
          return snapshot.data!;
        } else if (snapshot.hasError) {
          return const Icon(Icons.error);
        }
        return const CircularProgressIndicator();
      },
    ),
  ),
)

方案3：安卓端网络配置适配 #

如果仅安卓端出现该问题，可添加网络安全配置兼容低版本系统：

1. 在res/xml目录下新建network_security_config.xml：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">tmdb.org</domain>
    </domain-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
        </trust-anchors>
    </base-config>
</network-security-config>

2. 在AndroidManifest.xml的application标签中添加配置：

android:networkSecurityConfig="@xml/network_security_config"
android:usesCleartextTraffic="true"

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