如何让PHP函数ssh2_sftp()触发错误或超时而非挂起？

我用以下PHP代码尝试连接SFTP：

$connection = ssh2_connect($host, $port);
ssh2_auth_password($connection, $user, $password);
$sftp = ssh2_sftp($connection);

但脚本没有触发任何错误，直接挂起。而通过Linux命令行连接时，得到如下错误：

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: from
Could not chdir to home directory /xxx/xxx/./xxx/xxxx/xxx: No such file or directory
Connection to closed.

如何让脚本触发错误（最好显示具体问题）而非挂起？

问题根源是SSH服务器在验证身份后，尝试切换到指定的家目录失败，直接断开了连接，但PHP的ssh2扩展没有及时检测到连接断开，导致脚本挂起。可以通过以下几种方式解决：

1. 设置连接超时 #

在ssh2_connect中添加超时参数，避免脚本无限挂起，超时后会抛出明确的错误：

<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);

$connection = ssh2_connect($host, $port, ['timeout' => 10]); // 设置10秒超时
if (!$connection) {
    die("无法连接到SFTP服务器");
}

if (!ssh2_auth_password($connection, $user, $password)) {
    die("身份验证失败");
}

// 尝试初始化SFTP，超时会触发错误
$sftp = ssh2_sftp($connection);
if (!$sftp) {
    die("无法初始化SFTP会话");
}
?>

2. 主动触发连接检测 #

初始化SFTP后，执行一个简单的SFTP操作（比如列出当前目录），强制检测连接状态，触发潜在的错误：

<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);

$connection = ssh2_connect($host, $port);
if (!$connection) {
    die("无法连接到SFTP服务器");
}

if (!ssh2_auth_password($connection, $user, $password)) {
    die("身份验证失败");
}

$sftp = ssh2_sftp($connection);
if (!$sftp) {
    die("无法初始化SFTP会话");
}

// 尝试列出目录，触发连接错误
$dir = "ssh2.sftp://$sftp/";
$files = scandir($dir);
if ($files === false) {
    die("SFTP操作失败：无法访问目录，可能是服务器家目录不存在导致连接断开");
}
?>

3. 使用更可靠的SFTP库替代ssh2扩展 #

PHP的ssh2扩展错误处理不够完善，推荐使用phpseclib（纯PHP实现的SSH/SFTP库），它能更精准地捕获这类登录后的异常：

<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);

require_once 'vendor/autoload.php'; // 若用Composer安装
// 或手动引入文件：require 'Net/SFTP.php';

use phpseclib3\Net\SFTP;

$sftp = new SFTP($host, $port);
if (!$sftp->login($user, $password)) {
    die("登录失败：" . $sftp->getLastError());
}

// 尝试执行操作，捕获家目录不存在的错误
try {
    $sftp->nlist('.');
} catch (Exception $e) {
    die("SFTP会话失败：" . $e->getMessage());
}
?>

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