PHPSeclib SFTP 文件下载失败的参数顺序问题详解-php教程-PHP中文网

PHPSeclib SFTP 文件下载失败的参数顺序问题详解

PHPSeclib 的 SFTP::get() 方法参数顺序为「远程路径在前、本地路径在后」，若误用 FTP 扩展风格（本地在前、远程在后）会导致静默失败，即使文件存在也无法下载。

phpseclib 的 `sftp::get()` 方法参数顺序为「远程路径在前、本地路径在后」，若误用 ftp 扩展风格（本地在前、远程在后）会导致静默失败，即使文件存在也无法下载。

在使用 phpseclib 进行 SFTP 文件下载时，一个常见却极易被忽视的错误是混淆 SFTP::get() 方法的参数顺序。与 PHP 原生 ftp_get() 函数（ftp_get($ftp_stream, $local_file, $remote_file, $mode)）不同，phpseclib 的 SFTP::get($remote_file, $local_file, $mode = null) 要求第一个参数是远程服务器上的文件路径，第二个参数才是本地保存路径。

在您提供的代码中：

// ❌ 错误写法（模仿 ftp_get，参数顺序颠倒）
$this->objConn->get($p_strTargetFile, $p_strSourceFile, FTP_BINARY);

这实际等价于尝试从本地文件 $p_strTargetFile（如 'temp/file.txt'）读取内容并写入远程路径 $p_strSourceFile（如 'path/to/file.txt'），不仅逻辑相反，且因 FTP_BINARY 不被 phpseclib 的 get() 方法识别（该方法第三个参数应为可选的 SFTP::SOURCE_LOCAL 或 SFTP::SOURCE_REMOTE，但通常无需显式传入），可能导致调用失败或返回 false —— 而 get() 在失败时不会抛出异常，仅返回 false，因此需主动检查返回值。

✅ 正确写法如下：

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

// ✅ 正确：远程路径在前，本地路径在后
if (!$this->objConn->get($p_strSourceFile, $p_strTargetFile)) {
    throw new \Exception("Failed to download remote file: {$p_strSourceFile}");
}

? 提示：phpseclib 的 get() 方法默认以二进制模式传输，无需指定 FTP_BINARY；若需指定传输模式（如文本模式自动换行转换），应使用 SFTP::SOURCE_REMOTE（默认）或 SFTP::SOURCE_LOCAL，但绝大多数场景下直接传两个路径参数即可。

此外，建议增强健壮性，在下载前补充路径合法性校验与目录创建逻辑：

public function downloadFile($p_strTargetFile, $p_strSourceFile)
{
    $this->openConnection();

    // 确保本地目标目录存在
    $targetDir = dirname($p_strTargetFile);
    if (!is_dir($targetDir) && !mkdir($targetDir, 0755, true)) {
        throw new \Exception("Cannot create local directory: {$targetDir}");
    }

    // 执行下载（参数顺序已修正）
    if (!$this->objConn->get($p_strSourceFile, $p_strTargetFile)) {
        throw new \Exception("SFTP download failed for remote file: {$p_strSourceFile}");
    }

    // 可选：验证文件完整性（如比对 size）
    $remoteSize = $this->objConn->size($p_strSourceFile);
    $localSize  = filesize($p_strTargetFile);
    if ($remoteSize !== $localSize) {
        throw new \Exception("Downloaded file size mismatch: expected {$remoteSize}, got {$localSize}");
    }
}

? 总结：

✅ 记住口诀：“Get from Remote → to Local”，即 get($remote, $local)；
❌ 切勿套用 ftp_get() 的参数习惯；
⚠️ 始终检查 get() 返回值，避免静默失败；
? 使用 var_dump($this->objConn->pwd(), $this->objConn->nlist('.')) 可辅助调试当前远程工作目录及文件列表，确认路径有效性。

遵循以上规范，即可稳定、可靠地通过 phpseclib 完成 SFTP 文件下载任务。