Flutter使用FTPConnect库建立FTPS连接时出现HandshakeException错误

问题重现 #

使用Flutter的FTPConnect库建立FTPS连接时触发握手错误，错误信息为HandshakeException: Handshake error in client (OS Error: WRONG_VERSION_NUMBER(tls_record.cc:231))。

相关代码：

FTPConnect ftpConnect = FTPConnect('devftp.made.net', user: 'user', pass: 'pass', showLog: kDebugMode, securityType: SecurityType.FTPS); 
await ftpConnect.connect();

日志显示已成功建立初始连接并收到服务器欢迎信息，但TLS握手阶段失败。

解决方案 #

1. 匹配服务器支持的TLS版本 #

错误提示WRONG_VERSION_NUMBER说明客户端使用的TLS版本与服务器支持的版本不兼容。可以通过指定允许的TLS协议版本解决：

import 'dart:io';

// 创建自定义SecurityContext，指定兼容的TLS版本
SecurityContext securityContext = SecurityContext.defaultContext;
// 根据服务器支持情况调整，常见为TLS 1.2或1.3
securityContext.allowedProtocols = [TlsProtocol.tls12, TlsProtocol.tls13];

FTPConnect ftpConnect = FTPConnect(
  'devftp.made.net',
  user: 'user',
  pass: 'pass',
  showLog: kDebugMode,
  securityType: SecurityType.FTPS,
  context: securityContext,
);
await ftpConnect.connect();

2. 确认FTPS连接模式 #

FTPS分为显式（Explicit）和隐式（Implicit）两种模式：

• 显式模式：默认使用21端口，先建立明文连接再升级为TLS（对应SecurityType.FTPS）
• 隐式模式：直接使用990端口建立加密连接

如果服务器采用隐式FTPS，需修改端口并确认连接模式：

FTPConnect ftpConnect = FTPConnect(
  'devftp.made.net',
  user: 'user',
  pass: 'pass',
  showLog: kDebugMode,
  securityType: SecurityType.FTPS,
  port: 990, // 隐式FTPS默认端口
);
await ftpConnect.connect();

3. 验证服务器证书（可选） #

若上述方法无效，可能存在服务器证书不被客户端信任的情况，可以临时禁用证书验证进行测试（仅用于调试，生产环境不建议）：

SecurityContext securityContext = SecurityContext.defaultContext;
securityContext.setTrustedCertificatesBytes([]); // 跳过证书验证
securityContext.allowedProtocols = [TlsProtocol.tls12, TlsProtocol.tls13];

FTPConnect ftpConnect = FTPConnect(
  'devftp.made.net',
  user: 'user',
  pass: 'pass',
  showLog: kDebugMode,
  securityType: SecurityType.FTPS,
  context: securityContext,
);
await ftpConnect.connect();

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