本教程旨在解决使用 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() 将远程流的数据复制到本地流。
- 关闭所有流： 确保所有打开的资源都被正确释放。
示例代码：
解决方案二：更简洁高效的 ssh2_scp_recv 方法
如果您的服务器同时支持 SCP（Secure Copy Protocol），那么 ssh2 扩展提供了一个更为简洁高效的函数 ssh2_scp_recv()。SCP 通常与 SFTP 同时存在，并且在某些场景下，它的实现可能更直接。ssh2_scp_recv() 函数能够一步完成从远程服务器复制文件到本地的操作，极大地简化了代码。
ssh2_scp_recv() 函数签名：
bool ssh2_scp_recv ( resource $connection , string $remote_file , string $local_file )
参数说明：
- $connection：已建立的 SSH 连接资源。
- $remote_file：远程服务器上文件的完整路径。
- $local_file：本地保存文件的完整路径或文件名。
示例代码：
注意事项
在实现 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，通常需要提供完整的绝对路径。
- 安全性：
-
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 文件传输功能。选择哪种方法取决于您的具体需求和服务器支持情况，但两种方法都能确保文件内容完整无缺地传输到本地。
