PHP通过SFTP向IPv6主机传输文件时ssh2_connect连接失败如何解决？

核心问题是旧版本libssh2库底层调用仅支持IPv4的gethostbyname做地址解析，导致原生ssh2_connect无法适配IPv6地址，以下是两种可落地的解决方案：

方案1：使用纯PHP实现的phpseclib SFTP库（推荐） #

phpseclib是纯PHP编写的SSH/SFTP实现，不依赖系统libssh2扩展，原生支持IPv6地址解析，兼容性更强。

1. 安装方式：通过Composer安装即可

composer require phpseclib/phpseclib:~3.0

2. 连接代码示例：

use phpseclib3\Net\SFTP;

// 注意：IPv6地址不需要额外包裹方括号
$host = 'XXXX:XXXX:XX:...';
$port = 22;
$user = 'XXX';
$pass = 'XXXXXXX';

$sftp = new SFTP($host, $port);
if ($sftp->login($user, $pass)) {
    error_log('valid connection');
    // 上传文件示例：$sftp->put('远程存储路径', '本地文件路径', SFTP::SOURCE_LOCAL_FILE);
} else {
    error_log('failed connection');
}

方案2：原生ssh2扩展+手动创建IPv6套接字 #

如果必须使用原生ssh2扩展，可以先通过支持IPv6的stream_socket_client预创建连接套接字，绕过ssh2底层的地址解析逻辑：

$host = 'XXXX:XXXX:XX:...';
$port = 22;
$user = 'XXX';
$pass = 'XXXXXXX';

// 套接字地址格式必须为 tcp://[IPv6地址]:端口，方括号不可省略
$socket = stream_socket_client("tcp://[$host]:$port", $errno, $errstr, 10);
if (!$socket) {
    error_log("套接字创建失败：$errstr ($errno)");
    exit;
}

// 将已创建的套接字传入ssh2_connect
$connection = ssh2_connect($host, $port, [], [], $socket);
if ($connection && ssh2_auth_password($connection, $user, $pass)) {
    error_log("valid connection");
    // 后续可通过ssh2_sftp初始化SFTP会话执行文件操作
} else {
    error_log("failed connection");
}

• 先在服务器命令行执行ping6 [IPv6地址]和telnet [IPv6地址] 22，确认IPv6网络连通性正常、22端口未被防火墙拦截
• 如果使用域名关联IPv6地址，需确认服务器DNS支持AAAA记录查询，可通过nslookup -query=AAAA 你的域名验证

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