Laravel 10配置SFTP存储驱动后检测文件存在失败，求排查配置

环境与已完成配置 #

• 运行环境：PHP 8.2、Laravel 10
• 已安装SFTP驱动：

composer require league/flysystem-sftp-v3 "^3.0"

• config/filesystems.php中的SFTP配置：

'sftp' => [
    'driver' => 'sftp',
    'host' => env('SFTP_HOST'),
 
    // 基础认证设置
    'username' => env('SFTP_USERNAME'),
    'password' => env('SFTP_PASSWORD'),
 
    // SSH密钥认证设置（未使用）
    'privateKey' => env('SFTP_PRIVATE_KEY'),
    'passphrase' => env('SFTP_PASSPHRASE'),
 
    // 文件/目录权限设置
    'visibility' => 'private', // `private` = 0600, `public` = 0644
    'directory_visibility' => 'private', // `private` = 0700, `public` = 0755
 
    // 可选SFTP设置
    'port' => env('SFTP_PORT', 6323),
    'root' => env('SFTP_ROOT', ''),
]

• .env文件配置：

SFTP_HOST="my.host.it"
SFTP_USERNAME="mysftpusername"
SFTP_PASSWORD="mysftppwd"
SFTP_PRIVATE_KEY=""
SFTP_PASSPHRASE=""
SFTP_ROOT="/PagoPA/0000999/RT"

• 测试路由代码：

Route::get('test-sftp', function() {
    if (Storage::disk('sftp')->exists('RT_1000888_0000900_00000000000999999_250623160941-BNLIITRR-0597.xml')) {
        return 'file found';
    } else {
        return 'file not found';
    }
});

遇到的错误 #

League\Flysystem\UnableToCheckFileExistence
Unable to check existence for: RT_1000888_0000900_00000000000999999_250623160941-BNLIITRR-0597.xml

排查步骤 #

• 验证SFTP基础连接信息
  先用第三方工具（如FileZilla）手动连接SFTP主机，确认SFTP_HOST、端口6323、用户名、密码均正确，且能正常访问/PagoPA/0000999/RT目录下的目标文件，排除地址、端口、账号密码类错误。

• 确认根目录配置的正确性
  检查SFTP_ROOT设置的/PagoPA/0000999/RT是否为SFTP主机上的绝对路径，且当前用户拥有该目录的访问权限；如果是相对路径，需调整为对应账号的相对路径格式。

• 排查权限问题
  确保SFTP用户对/PagoPA/0000999/RT目录有读取权限，同时对目标文件也有读取权限——部分SFTP服务器会限制目录或文件的访问权限，即使登录成功也无法查看特定资源。

• 清理未使用的认证配置
  由于使用密码认证而非密钥认证，建议删除privateKey和passphrase这两行配置，避免驱动混淆认证方式。

• 开启详细日志定位问题
  在config/filesystems.php的sftp配置中添加日志记录：

  'sftp' => [
      // 原有配置...
      'logger' => \Illuminate\Support\Facades\Log::getLogger(),
  ]
  

  执行测试路由后，查看storage/logs/laravel.log，日志中会包含更具体的错误信息（如连接超时、权限不足、路径不存在等），帮助精准定位问题。

• 检查文件名大小写
  若SFTP主机为Linux环境，文件名区分大小写，需确保测试代码中的文件名与主机上的文件名完全一致，包括大小写。

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