Flutter应用接入Firebase Storage出现WRONG_VERSION_NUMBER TLS握手错误如何解决

• 网络环境异常：切换WiFi后恢复的测试结论可直接指向这类问题。常见场景包括当前网络的DNS劫持、路由器/运营商的TLS代理规则异常、防火墙拦截了TLS 1.2/1.3握手请求，或是临时网络路由波动导致握手包被篡改，错误返回了不符合协议版本的响应包。
• Firebase服务端临时故障：部分区域的Firebase Storage边缘节点出现配置更新异常、证书部署错误时，会引发短时间握手失败问题，这类故障通常会在几小时内由官方自动修复，和问题自行消失的特征吻合。
• 客户端设备时间偏移：设备系统时间和标准时间偏差超过1小时时，会导致TLS证书有效期校验失败，部分底层TLS库会抛出版本不匹配错误，这类问题通常不会随网络切换恢复，同步设备时间即可解决。
• 依赖版本兼容问题：若近期更新过flutterfire相关依赖、Dart SDK版本，旧版本firebase_storage包对高版本TLS适配存在缺陷，若确认代码无变更可排除该诱因。

网络侧排查 #

• 出现问题时优先切换移动热点测试，若切换后恢复即可判定为当前WiFi网络问题，可进一步排查路由器防火墙规则、DNS配置，或联系运营商确认是否存在拦截策略
• 无法切换网络时可通过curl工具手动请求Storage资源链接，执行curl -v <Storage资源公网链接>，查看TLS握手阶段日志，确认协商的TLS版本和报错节点

客户端侧排查 #

• 校验设备系统时间是否与标准时间一致，偏差过大时先同步时间重试
• 确认firebase_storage依赖版本≥11.0.0，该版本之后官方修复了大量TLS握手兼容问题
• 可在初始化HTTP客户端时强制指定最小TLS版本为1.2，示例代码如下：

import 'dart:io';

HttpClient createHttpClient() {
  final client = HttpClient();
  // 生产环境请勿开启badCertificateCallback配置，仅调试时使用
  client.badCertificateCallback = (cert, host, port) => false;
  client.minTlsVersion = TlsVersion.tls12;
  return client;
}

服务端侧排查 #

• 登录Firebase控制台查看状态面板，确认对应区域的Storage服务是否存在历史故障记录
• 若使用自定义域名对接Storage，确认域名SSL证书是否在有效期内，DNS解析是否指向正确的服务节点

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