修复 Android 上的 Flutter SSL 握手失败

当 Dart 运行时在安全 HTTPS 连接期间无法验证服务器的 SSL 证书时,就会发生 Android 上的 Flutter SSL 握手失败。Android 将受信任的根证书存储在 /system/etc/security/cacerts,而 Flutter 通过 BoringSSL 库从该路径读取。面向 Android 13 及以下版本的 Flutter 开发者,必须解决证书信任、TLS 版本支持和证书链完整性问题,才能修复此错误。

是什么导致了 Android 上的 Flutter SSL 握手失败?

Android 上的 Flutter SSL 握手失败有四个截然不同的根本原因。Flutter 的 Dart 运行时通过 BoringSSL 库,从 Android 上的 /system/etc/security/cacerts 加载受信任的根证书——而不是原生应用使用的系统 Conscrypt 层。这意味着被 Chrome 或原生 Android 应用信任的证书,不会自动被 Flutter 信任。此错误的四个根本原因是:

- 未知或不受信任的证书颁发机构(CA):服务器的证书由一个在操作系统出厂时未纳入 Android 系统根存储的 CA 签发。
- 缺少中间证书:服务器只发送其叶子证书,导致证书链中出现 Android 无法自动弥合的缺口。
- 不支持的 TLS 版本:运行 API 级别 20(Android 4.4)及以下的 Android 设备默认未启用 TLS 1.2,导致针对要求 TLS 1.2 或更高版本服务器的握手失败。
- 自签名证书:该证书并非由公共 CA 签发,因此除非应用显式信任该证书,否则 Android 会拒绝它。

如何诊断确切的 Flutter SSL 错误

诊断确切原因需要读取 Flutter 日志中的完整错误消息。三条不同的消息对应三个不同的问题:

以调试模式运行 Flutter 应用,并在终端中查看完整的堆栈跟踪。OS Error 后面括号中的 BoringSSL 错误消息,标识了确切的失败类型。务必让你的修复方法与具体错误相对应——采用错误的修复方法会浪费时间,并可能引入安全漏洞。

修复一:使用 Android 网络安全配置

网络安全配置(Network Security Config)是在 Flutter 应用中信任自定义或自签名证书的正确 Android 方法。此方法适用于 Android 7.0(API 24)及以上版本,无需任何 Dart 端改动。

按照以下四个步骤操作:

- 在 Android 项目中创建文件 res/xml/network_security_config.xml,其中包含一个指向你存储在 res/raw/ 中证书的 <trust-anchors> 条目
- 将证书文件(PEM 或 DER 格式)添加到 android/app/src/main/res/raw/my_cert.pem
- 在 xml 中通过 <application> 标签上的 android:networkSecurityConfig 属性引用该配置文件
- 用 flutter clean 后接 flutter run 重新构建应用

一个面向自定义 CA 的基础 network_security_config.xml 如下所示:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
  <domain-config>
    <domain includeSubdomains="true">api.example.com</domain>
    <trust-anchors>
      <certificates src="@raw/my_cert" />
    </trust-anchors>
  </domain-config>
</network-security-config>

根据 Android 网络安全配置文档(Android Developers,2025 年 3 月),面向 Android 6.0(API 23)及以下的应用默认信任用户添加的 CA,而面向 API 24 及以上的应用则不然——这使得该配置对于任何支持多个 Android 版本的应用都至关重要。

修复二:为较旧的 Android 设备启用 TLS 1.2

在较旧的 Android 上支持 TLS 1.2,需要在 Flutter 应用的 MainActivity.kt 文件中进行原生端修复。运行 API 级别 20 及以下的 Android 设备默认未启用 TLS 1.2,导致在现代服务器上出现 SSL 握手中止错误。

更新你的 MainActivity.kt,使其在启动时显式启用 TLS 1.2:

class MainActivity: FlutterActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.LOLLIPOP) {
      enableTLS12()
    }
  }
  private fun enableTLS12() {
    val sc = SSLContext.getInstance("TLSv1.2")
    sc.init(null, null, SecureRandom())
    HttpsURLConnection.setDefaultSSLSocketFactory(sc.socketFactory)
  }
}

此修复仅针对 API 21 以下的设备。运行 Android 5.1(Lollipop)及以上的设备会自动启用 TLS 1.2,因此此代码块不会影响它们。

修复三:在 Dart 代码中嵌入并信任证书(Dio)

对于使用自签名证书或较旧 Android 根存储中尚无的 CA 的生产应用,在 Dart 代码中嵌入证书是最可靠的修复方法。此方法将 Dio HTTP 客户端配置为信任从应用资源加载的特定证书。

按照以下三个步骤操作:

- 将服务器的 fullchain.pem 放入 assets/certificates/,并在 pubspec.yaml 的 flutter: assets: 部分声明该路径
- 在你的 Dio 客户端设置中,加载证书并将其应用到自定义 SecurityContext,以便只接受你受信任的证书
- 通过 onHttpClientCreate 回调,将自定义 HttpClient 传递给 Dio 的 IOHttpClientAdapter

根据 Flutter Dart 关于 SecurityContext 的文档,Flutter 在 Android 上从 /system/etc/security/cacerts 读取其根 CA 存储。由于该存储是只读系统分区的一部分,它只会随完整的操作系统更新而改变。面向那些在新根 CA 添加之前就已出厂的设备的应用,必须嵌入证书或使用网络安全配置来弥合这一缺口。

Flutter 的 BoringSSL 证书验证完全在 BoringSSL 原生库内进行,独立于 Android 的 Conscrypt 层。这就是为什么原生 Android 应用和 Chrome 可能信任一张 Flutter 拒绝的证书——它们使用不同的验证栈。

修复四:验证并修复服务器证书链

Flutter HTTPS 连接 Android 的修复并不总是客户端问题。如果服务器不发送完整的证书链(包括所有中间证书),Android 会以"Trust anchor for certification path not found"错误终止握手。

用以下命令检查服务器的证书链:

openssl s_client -connect api.example.com:443 -showcerts

正确的证书链会在"Certificate chain"部分下显示三到四张证书。损坏的证书链只显示一张。对于 Nginx 服务器,请确保你的 SSL 证书文件同时包含叶子证书和按顺序拼接的所有中间证书。

服务器的 ssl_protocols 指令必须包含 TLS 1.2 和 TLS 1.3,以支持应用所面向的所有 Android 版本。用以下命令验证:

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers on;

需要避免的常见错误

有三个错误导致的 Flutter SSL 失败持续存在,比任何根本原因都多:

- 使用 badCertificateCallback => true——这会在生产环境中禁用所有 SSL 验证,使用户暴露于中间人攻击之下。绝不要在开发环境之外使用它。
- 应用了网络安全配置却没有重新构建——该配置在安装时被读取。在任何 AndroidManifest.xml 或 network_security_config.xml 更改后,务必运行 flutter clean 并重新构建。
- 只锁定单张证书而不设备份——针对单张叶子证书的证书锁定,会在服务器轮换证书的那一刻让所有用户的应用失效。应改为锁定中间 CA 或根 CA 的摘要。

关于 Flutter SSL 握手失败的常见问题

Flutter 在 Android 上 SSL 握手失败的原因是什么?

Android 上的 Flutter SSL 握手失败,由四个问题之一引起:证书颁发机构不受信任、服务器证书链中缺少中间证书、Android API 20 及以下未启用 TLS 1.2,或应用未显式信任自签名证书。Flutter 使用 BoringSSL 库,从 Android 系统根存储 /system/etc/security/cacerts 验证证书,这与 Chrome 和原生 Android 应用使用的验证栈是分开的。

如何修复 Flutter Android 中的 HandshakeException?

要修复 Flutter 中的 HandshakeException certificate verify failed,先在调试日志中确定确切的错误消息。使用 Android 网络安全配置信任自定义或自签名 CA,在 MainActivity.kt 中为 API 20 及以下的设备启用 TLS 1.2,或使用 SecurityContext 和 Dio 的 IOHttpClientAdapter 将服务器证书直接嵌入 Dart 代码。

为什么我的 Flutter 应用在较旧的 Android 设备上 SSL 失败,而在新设备上不会?

较旧的 Android 设备出厂时其根证书存储不包含操作系统构建后新增的根 CA。较旧设备上的 TLS 1.2 Android Flutter 也是一个因素——Android API 20 及以下的设备默认不启用 TLS 1.2。由于系统根存储位于只读的 /system 分区,它只随完整的操作系统更新而改变,而许多较旧设备从未获得这种更新。

如何修复 Flutter 中的 CERTIFICATE_VERIFY_FAILED?

要修复 Flutter 中的 trust anchor certification path not found,请按顺序检查三件事:用 openssl s_client 验证服务器发送完整证书链,将签发 CA 添加到应用的网络安全配置中,如果该 CA 是较旧设备上不存在的新根,则将完整证书链嵌入 Flutter 资源并配置自定义 SecurityContext。

Flutter 在 Android 上的 SSL 信任存储是什么?

Flutter 的 Android 根证书存储,是位于设备上 /system/etc/security/cacerts 的系统 CA 存储。Flutter 的 Dart 运行时通过 BoringSSL 直接从该路径加载证书,绕过了 Android 的 Conscrypt 层。这意味着 Flutter 只信任设备出厂时内置到 Android 操作系统中的 CA,除非你通过网络网络安全配置或自定义 SecurityContext 显式添加更多受信任的 CA。

如何在 Flutter 中为较旧的 Android 启用 TLS 1.2?

要为较旧设备启用 Flutter Dio SSL 证书错误防护,可在 MainActivity.kt 中添加 TLS 1.2 强制代码块。用 Build.VERSION.SDK_INT < Build.VERSION_CODES.LOLLIPOP 检查 API 级别,并在 try-catch 块中调用 SSLContext.getInstance("TLSv1.2").init(null, null, SecureRandom())。这会针对 Android 4.4 及以下设备,强制通过 HttpsURLConnection 建立的所有 HTTPS 连接使用 TLS 1.2。