Laravel 7使用文件系统调用时如何查看调试或错误信息？

Laravel 底层文件系统基于 Flysystem 适配器实现，默认配置下，Storage::put/write 这类磁盘操作遇到失败时，不会主动抛出业务异常，仅返回布尔型的失败状态。如果你的代码没有主动校验返回值，整个操作会静默失败——既不会走到 Laravel 的异常渲染流程，也不会触发默认日志记录，自然既看不到调试页面，也找不到laravel.log里的相关记录。

• 主动校验磁盘操作的返回值
  不要默认文件写入一定成功，每次调用后主动判断执行结果，最小成本捕获异常状态：

  $isSuccess = Storage::disk('sftp')->put('test.txt', '测试内容');
  if (! $isSuccess) {
      logger()->error('SFTP文件写入失败', [
          'target_path' => 'test.txt',
          'disk_name' => 'sftp'
      ]);
  }
  

• 开启Flysystem的操作异常抛出
  Laravel 9.x 及以上版本支持为指定磁盘配置throw_on_failures参数，只需要在config/filesystems.php对应sftp磁盘的配置块中增加：

  'sftp' => [
      // 原有连接、权限等配置项
      'throw_on_failures' => true,
  ],
  

  开启后，所有磁盘操作的失败都会直接抛出League\Flysystem\FilesystemException类型的异常，会被 Laravel 内置的异常处理器自动捕捉——开发环境会直接展示带完整堆栈的调试页面，生产环境也会自动把具体失败原因（比如SFTP密码错误、目录无写入权限、连接超时、路径不存在等）写入laravel.log。
• 打开SFTP协议层的调试日志
  如果使用的是低版本Laravel，不支持throw_on_failures配置，可以在sftp磁盘配置中直接开启连接调试参数，获取SFTP交互的全量日志：

  'sftp' => [
      // 原有配置项
      'debug' => true,
  ],
  

  开启后会在运行时输出SFTP协议握手、路径校验、权限校验的全流程交互信息，能直接定位网络层、协议层的具体故障点。
• 单独编写连接测试逻辑
  可以临时写一个简单的测试路由，跳过业务逻辑直接验证磁盘连通性：

  Route::get('/test-sftp-connect', function() {
      try {
          $disk = Storage::disk('sftp');
          // 执行最简单的目录列举操作验证连接
          $rootFiles = $disk->files('/');
          dd('连接正常，根目录文件：', $rootFiles);
      } catch (\Exception $e) {
          logger()->error('SFTP连通性测试异常', [
              'error_msg' => $e->getMessage(),
              'trace' => $e->getTraceAsString()
          ]);
          dd('测试失败：' . $e->getMessage());
      }
  });
  

• 写入的目标目录不存在，且SFTP账号没有自动创建目录的权限，操作直接被拒绝
• SFTP配置的根目录路径错误，文件实际写入了非预期的物理路径，代码判定写入成功但找不到目标文件
• 网络波动导致SFTP连接中途断开，但低层连接没有触发错误回调，上层代码感知不到失败

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