使用PHPSeclib时文件确认存在但无法正常下载的问题排查

核心故障点按出现概率排序 #

• 本地目录不存在/无写入权限
  你代码中指定的本地存储路径为temp/file.txt，phpseclib的SFTP客户端不会自动递归创建不存在的本地目录，也不会提前校验目录权限。如果运行PHP的进程（web-fpm/CLI用户）对项目根目录没有写入权限，或者temp目录未提前创建，get()方法会直接返回false，不会生成任何本地文件。
  修复代码：在下载逻辑前增加本地目录校验与创建逻辑

  public function downloadFile($p_strTargetFile, $p_strSourceFile)
  {
      $this->openConnection();
      // 校验并创建本地目标目录
      $localDir = dirname($p_strTargetFile);
      if (!is_dir($localDir)) {
          mkdir($localDir, 0755, true);
      }
      // 后续下载逻辑
      if (!$this->objConn->get($p_strTargetFile, $p_strSourceFile)) {
          throw new \Exception('Unable to download file.');
      }
  }
  

• 远程路径未做标准化处理
  你的isFileExist()方法中对传入的远程路径调用了standardizePath()做格式修正（统一斜杠方向、去除多余斜杠、解析相对路径片段），但downloadFile()方法中直接使用了原始传入的路径参数，没有做相同的标准化处理。nlist()方法对非标准路径的容错性更高，会让你误判文件存在，但SFTP的文件获取接口对路径格式要求严格，非标准路径会直接触发文件找不到错误。
  修复代码：在下载方法中增加路径标准化逻辑，和文件存在校验保持一致

  public function downloadFile($p_strTargetFile, $p_strSourceFile)
  {
      $this->openConnection();
      // 标准化远程路径
      $p_strSourceFile = $this->standardizePath($p_strSourceFile);
      // 本地目录校验逻辑略
      if (!$this->objConn->get($p_strTargetFile, $p_strSourceFile)) {
          throw new \Exception('Unable to download file.');
      }
  }
  

• 传输模式常量误用
  你当前代码中给get()传入的第三个参数是FTP_BINARY，这是PHP原生FTP扩展的预定义常量，和phpseclib的SFTP类要求的常量不兼容：
  • phpseclib 1.x/2.x 版本二进制传输常量为NET_SFTP_LOCAL_BINARY
  • phpseclib 3.x 版本二进制传输常量为SFTP::MODE_BINARY
    传入不匹配的常量值会导致传输模式参数非法，触发下载失败。排查阶段可以先不传第三个参数，使用类默认的二进制传输模式测试。
• 文件存在校验逻辑假阳性
  你当前实现的isFileExist()逻辑存在误判可能：不同SFTP服务端nlist()返回的文件列表格式不统一，部分服务端会返回带完整父路径的文件名（例如path/to/file.txt），部分会返回相对文件名，你直接拿拆分后的纯文件名做in_array匹配，可能把同名目录、其他路径下的同名文件误判为目标文件存在。
  修复方式：替换为phpseclib自带的文件类型判断方法，避免遍历匹配误差

  public function isFileExist($p_strFile) 
  {
      $this->openConnection();
      $strStandardizedPath = $this->standardizePath($p_strFile);
      return $this->objConn->file_exists($strStandardizedPath) 
          && $this->objConn->is_file($strStandardizedPath);
  }
  

• 登录凭证属性不匹配
  你在实例化FTPConnection时传入的第三个参数是FTP_PASS（密码），但openConnection()的登录逻辑中使用的是$this->rsa属性作为认证凭证。如果类构造函数没有把传入的密码正确赋值给$this->rsa属性，会导致登录时实际使用空凭证：部分SFTP服务端允许未授权用户列目录，但下载文件时会做权限校验，直接拒绝请求。

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