本教程旨在解决使用 php `ssh2` 扩展通过 sftp 下载文件时，本地文件为空的问题。文章将详细阐述数据流传输的正确方法，包括使用 `stream_copy_to_stream` 进行数据复制，并介绍更简洁高效的 `ssh2_scp_recv` 替代方案，帮助开发者实现可靠的文件下载功能。
在开发需要与远程服务器进行文件交互的应用程序时，安全地传输文件是一项常见需求。PHP 的 ssh2 扩展为 SSH 和 SFTP 操作提供了强大的功能。然而，在使用 SFTP 下载文件时，一个常见的陷阱是最终得到的本地文件内容为空。本教程将深入探讨导致此问题的根本原因，并提供两种有效的解决方案，以确保文件传输的成功与高效。
问题根源：为何本地文件为空
问题的核心在于文件处理流程的不完整。当开发者使用 fopen 结合 ssh2.sftp:// URI 打开远程文件以供读取，并随后再次使用 fopen 创建一个本地文件以供写入时，往往会忽略一个关键步骤：在两个已打开的流之间进行数据传输。仅仅打开一个远程流和一个本地流，然后关闭远程流，并不会自动复制文件内容。数据必须明确地从源流中读取，并写入到目标流中。
解决方案一：使用 stream_copy_to_stream 进行流数据传输
为了正确地将远程文件内容复制到本地文件，我们需要利用 PHP 的流处理功能。stream_copy_to_stream() 函数专门用于在两个已打开的流之间复制所有剩余的数据，是解决此问题的直接且可靠的方法。
实现步骤：
立即学习“PHP免费学习笔记（深入）”；
建立 SSH 连接并初始化 SFTP 子系统： 这是所有 SFTP 操作的基础。打开远程 SFTP 文件流： 使用 fopen 结合 ssh2.sftp:// URI 以只读模式打开远程文件。打开本地文件流： 使用 fopen 以写入模式打开或创建本地文件。复制数据： 使用 stream_copy_to_stream() 将远程流的数据复制到本地流。关闭所有流： 确保所有打开的资源都被正确释放。示例代码：
<?php$server_ip = '{你的服务器IP}';$username = '{你的用户名}';$password = '{你的密码}';$remote_file_path = '/public_html/test.txt'; // 远程文件在SFTP服务器上的路径$local_file_name = 'downloaded_test.txt'; // 本地保存的文件名// 1. 建立 SSH 连接$connection = ssh2_connect($server_ip, 22);if (!$connection) { die('错误：无法建立 SSH 连接。');}// 2. 身份验证if (!ssh2_auth_password($connection, $username, $password)) { die('错误：SSH 身份验证失败。');}// 3. 初始化 SFTP 子系统$sftp = ssh2_sftp($connection);if (!$sftp) { die('错误：无法初始化 SFTP 子系统。');}// 4. 构建远程文件 URI$target_path = "ssh2.sftp://$sftp" . $remote_file_path;// 5. 打开远程 SFTP 文件流$remote_stream = fopen($target_path, 'r');if (!$remote_stream) { die("错误：无法打开远程 SFTP 文件流：'$target_path'。");}// 6. 打开本地文件流$local_stream = fopen($local_file_name, 'w');if (!$local_stream) { fclose($remote_stream); // 确保在出错时关闭已打开的远程流 die("错误：无法打开本地文件流：'$local_file_name'。请检查目录权限。");}// 7. 复制数据if (stream_copy_to_stream($remote_stream, $local_stream)) { echo "成功：文件 '$remote_file_path' 已下载并保存为 '$local_file_name'。\n";} else { echo "错误：文件复制失败。\n";}// 8. 关闭所有流fclose($local_stream);fclose($remote_stream);// SSH 连接在脚本结束时通常会自动关闭。// 对于 ssh2 扩展，通常不需要显式调用 ssh2_disconnect，除非需要立即释放资源。?>登录后复制解决方案二：更简洁高效的 ssh2_scp_recv 方法
如果您的服务器同时支持 SCP（Secure Copy Protocol），那么 ssh2 扩展提供了一个更为简洁高效的函数 ssh2_scp_recv()。SCP 通常与 SFTP 同时存在，并且在某些场景下，它的实现可能更直接。ssh2_scp_recv() 函数能够一步完成从远程服务器复制文件到本地的操作，极大地简化了代码。
醒文 文字排版美化生图工具
22 查看详情 
ssh2_scp_recv() 函数签名：
bool ssh2_scp_recv ( resource $connection , string $remote_file , string $local_file )登录后复制
参数说明：
$connection：已建立的 SSH 连接资源。$remote_file：远程服务器上文件的完整路径。$local_file：本地保存文件的完整路径或文件名。示例代码：
<?php$server_ip = '{你的服务器IP}';$username = '{你的用户名}';$password = '{你的密码}';$remote_file_path = '/public_html/test.txt'; // 远程文件在SFTP服务器上的路径$local_file_name = 'downloaded_test_scp.txt'; // 本地保存的文件名// 1. 建立 SSH 连接$connection = ssh2_connect($server_ip, 22);if (!$connection) { die('错误：无法建立 SSH 连接。');}// 2. 身份验证if (!ssh2_auth_password($connection, $username, $password)) { die('错误：SSH 身份验证失败。');}// 3. 使用 ssh2_scp_recv 直接下载文件if (ssh2_scp_recv($connection, $remote_file_path, $local_file_name)) { echo "成功：文件 '$remote_file_path' 已通过 SCP 下载并保存为 '$local_file_name'。\n";} else { echo "错误：通过 SCP 下载文件失败。\n";}// SSH 连接在脚本结束时通常会自动关闭。?>登录后复制注意事项
在实现 SFTP 文件下载功能时，除了核心逻辑，还需要考虑以下几点以确保系统的健壮性和安全性：
错误处理： 在每一步操作（如 ssh2_connect、ssh2_auth_password、fopen、stream_copy_to_stream 或 ssh2_scp_recv）之后都应进行严格的错误检查。例如，检查函数返回值是否为 false 或 null，并根据需要抛出异常或记录错误日志，以便及时发现和解决问题。资源管理： 始终确保在文件操作完成后关闭所有打开的文件流 (fclose())，即使在发生错误时也应如此。这有助于避免资源泄露和潜在的系统性能问题。本地文件权限： 确保 PHP 运行的用户对目标本地目录有写入权限，否则 fopen($local_file_name, 'w') 将会失败。远程文件路径： 远程文件的路径必须准确无误。对于 SFTP URI，ssh2.sftp://$sftp/path/to/file 格式中，path/to/file 通常是相对于 SFTP 根目录的绝对路径，或者相对于用户主目录的路径（具体取决于服务器配置）。对于 ssh2_scp_recv，通常需要提供完整的绝对路径。安全性：凭据管理： 避免在代码中硬编码敏感的服务器 IP、用户名和密码。应通过环境变量、配置文件或密钥管理系统来安全地存储和检索这些凭据。输入验证： 如果文件名或路径来自用户输入，务必进行严格的验证和清理，以防止路径遍历攻击或其他潜在的安全漏洞。SCP 与 SFTP 的选择：SFTP (SSH File Transfer Protocol)：是 SSH 协议的一部分，提供更丰富的文件操作功能（如目录列表、文件属性修改等），通常通过 ssh2.sftp:// URI 结合 fopen 进行流式操作。SCP (Secure Copy Protocol)：是一种更简单的协议，主要用于文件复制。如果只需要简单的文件上传或下载，且服务器支持 SCP，ssh2_scp_recv 或 ssh2_scp_send 会是更简洁高效的选择。在大多数支持 SFTP 的服务器上，SCP 也通常可用。总结
通过本教程，我们深入探讨了 PHP 中使用 ssh2 扩展从 SFTP 服务器下载文件时遇到的“空文件”问题，并提供了两种有效的解决方案。无论是通过 stream_copy_to_stream 进行精细的流数据传输，还是利用 ssh2_scp_recv 实现一步到位的简洁下载，关键在于理解数据传输的必要性。遵循最佳实践，包括严谨的错误处理、资源管理和安全措施，将帮助您构建稳定、可靠的 PHP SFTP 文件传输功能。选择哪种方法取决于您的具体需求和服务器支持情况，但两种方法都能确保文件内容完整无缺地传输到本地。
以上就是PHP SFTP 文件下载教程：避免空文件并优化传输的详细内容，更多请关注php中文网其它相关文章！
