本文旨在解决php通过`ssh2.sftp://`协议从sftp服务器下载文件时，本地文件内容为空的问题。文章深入分析了问题根源，并提供了两种有效的解决方案：一是使用`stream_copy_to_stream`函数在文件流之间复制数据，确保内容完整传输；二是推荐使用更简洁高效的`ssh2_scp_recv`函数，尤其在服务器支持scp协议时，可大幅简化代码。同时，文章也强调了错误处理、资源管理和安全性的重要性。
在PHP开发中，通过SSH2扩展连接SFTP服务器并下载文件是一个常见的操作。然而，开发者有时会遇到一个困扰：尽管代码执行没有报错，但下载到本地的文件却是空的。这通常不是因为连接或认证失败，而是文件内容传输环节存在疏漏。
理解问题根源
当使用ssh2_sftp()获取SFTP子系统句柄，并结合ssh2.sftp:// URI方案通过fopen()打开远程文件时，我们实际上是创建了一个指向远程文件内容的流（stream）。接着，如果仅仅是再次使用fopen()以写入模式打开一个本地文件，却没有将远程流中的数据复制到本地文件流中，那么本地文件自然会保持为空。原始代码片段中，虽然成功打开了远程文件流（$stream = fopen($target_path, 'r');）和本地文件流（fopen($file, "w");），但缺少了关键的数据传输步骤，导致本地文件为空。
解决方案一：使用 stream_copy_to_stream 进行流数据传输
要解决上述问题，最直接的方法是在打开远程和本地文件流之后，使用stream_copy_to_stream()函数将数据从远程流复制到本地流。
以下是修正后的代码示例：
立即学习“PHP免费学习笔记（深入）”；
<?php
// 假设这些变量已正确定义
$server_ip = '{your_server_ip}';
$user = '{your_username}';
$password = '{your_password}';
$remote_file_path = '/public_html/test.txt'; // 远程文件在SFTP服务器上的完整路径
$local_file_name = 'test.txt'; // 下载到本地的文件名
// 1. 建立SSH连接
$connection = ssh2_connect($server_ip, 22);
if (!$connection) {
die('无法连接到SSH服务器');
}
// 2. SSH认证
if (!ssh2_auth_password($connection, $user, $password)) {
die('SSH认证失败');
}
// 3. 获取SFTP子系统句柄
$sftp = ssh2_sftp($connection);
if (!$sftp) {
die('无法获取SFTP子系统句柄');
}
// 4. 构建远程文件URI
$target_path = "ssh2.sftp://$sftp" . $remote_file_path;
// 5. 打开远程文件流（读取模式）
$remote_stream = fopen($target_path, 'r');
if (!$remote_stream) {
die('无法打开远程文件: ' . $remote_file_path);
}
// 6. 打开本地文件流（写入模式）
$local_stream = fopen($local_file_name, 'w');
if (!$local_stream) {
fclose($remote_stream); // 确保关闭已打开的远程流
die('无法创建本地文件: ' . $local_file_name);
}
// 7. 将数据从远程流复制到本地流
// stream_copy_to_stream(源流, 目标流)
$bytes_copied = stream_copy_to_stream($remote_stream, $local_stream);
if ($bytes_copied === false) {
echo '文件复制失败！';
} else {
echo "文件 '$local_file_name' 下载成功，复制了 $bytes_copied 字节。\n";
}
// 8. 关闭所有文件流以释放资源
fclose($local_stream);
fclose($remote_stream);
// SSH连接在脚本结束时通常会自动关闭，但也可以显式管理
// ssh2_disconnect($connection); // PHP的ssh2扩展没有ssh2_disconnect函数，连接会在脚本结束时自动关闭。
?>关键点：
- fopen($target_path, 'r') 返回一个可读的远程文件流。
- fopen($local_file_name, 'w') 返回一个可写的本地文件流。
- stream_copy_to_stream($remote_stream, $local_stream) 是执行数据传输的核心。
- 务必在操作完成后关闭所有打开的文件流，以释放系统资源。
解决方案二：利用 ssh2_scp_recv 简化文件下载
如果你的服务器同时支持SCP（Secure Copy Protocol），那么PHP的SSH2扩展提供了一个更为简洁高效的函数ssh2_scp_recv()，它可以将远程文件直接复制到本地，无需手动处理文件流。SCP通常与SFTP共存，大多数支持SFTP的服务器也支持SCP。
使用ssh2_scp_recv()可以大大简化代码：
<?php
// 假设这些变量已正确定义
$server_ip = '{your_server_ip}';
$user = '{your_username}';
$password = '{your_password}';
$remote_file_path = '/public_html/test.txt'; // 远程文件在SFTP服务器上的完整路径
$local_file_name = 'test.txt'; // 下载到本地的文件名
// 1. 建立SSH连接
$connection = ssh2_connect($server_ip, 22);
if (!$connection) {
die('无法连接到SSH服务器');
}
// 2. SSH认证
if (!ssh2_auth_password($connection, $user, $password)) {
die('SSH认证失败');
}
// 3. 使用 ssh2_scp_recv 下载文件
// ssh2_scp_recv(连接句柄, 远程文件路径, 本地文件路径)
if (ssh2_scp_recv($connection, $remote_file_path, $local_file_name)) {
echo "文件 '$local_file_name' 下载成功。\n";
} else {
echo "文件 '$local_file_name' 下载失败。\n";
}
// SSH连接在脚本结束时通常会自动关闭。
?>优势：
- 代码量显著减少，可读性更高。
- 内部处理了文件流的打开、复制和关闭，开发者无需关心这些细节。
- 通常在性能上与手动流操作相当，甚至更优。
注意事项：
- ssh2_scp_recv 依赖于服务器支持SCP协议。如果服务器只支持SFTP而不支持SCP，则此方法不可用。
- 远程文件路径必须是相对于SFTP根目录的完整路径。
注意事项与最佳实践
- 错误处理： 务必对ssh2_connect()、ssh2_auth_password()、ssh2_sftp()、fopen()以及stream_copy_to_stream()或ssh2_scp_recv()的返回值进行检查。任何一步的失败都应导致适当的错误处理或程序终止，以防止不可预期的行为。
- 资源管理： 使用fopen()打开的文件流，无论操作成功与否，都应通过fclose()显式关闭，以释放系统资源，避免资源泄露。对于ssh2_connect()建立的连接，虽然PHP脚本结束时会自动关闭，但在长时间运行的脚本或循环中，合理管理连接生命周期也很重要。
- 路径安全性： 如果远程文件路径或本地保存路径是用户输入或动态生成的，请务必进行严格的输入验证和清理，以防止路径遍历攻击或其他安全漏洞。
- 本地文件权限： 确保PHP运行的用户对目标本地目录具有写入权限，否则fopen()创建本地文件时可能会失败。
- 文件大小限制： 对于非常大的文件，stream_copy_to_stream通常能更好地处理，因为它以流的方式处理数据，不会一次性将整个文件加载到内存。ssh2_scp_recv在处理大文件时也表现良好，但其内部实现可能会有不同。
总结
当使用PHP通过SFTP下载文件时遇到内容为空的问题，核心原因在于缺少将远程数据流传输到本地文件流的步骤。解决此问题有两种主要方法：
- 使用 stream_copy_to_stream： 这是通用且灵活的方法，适用于所有支持流操作的场景。它要求开发者手动管理远程和本地文件流的打开与关闭。
- 使用 ssh2_scp_recv： 如果SFTP服务器同时支持SCP协议，这是更推荐的方法，因为它极其简洁高效，将复杂的流操作封装在一个函数调用中。
在实际开发中，建议优先考虑使用ssh2_scp_recv以简化代码。如果SCP不可用或有特定需求，则采用stream_copy_to_stream。无论选择哪种方法，都应结合严谨的错误处理和资源管理，以确保代码的健壮性和安全性。
