Laravel应用中如何记录S3文件保存失败的原因？

问题场景 #

当前使用Laravel的Storage门面将文件保存到S3时，put方法仅返回false，无法获取内部SDK的错误详情，难以排查失败原因：

$status = \Illuminate\Support\Facades\Storage::disk('s3')->put('test.txt',date('Y-m-d H:i:s'));

if(!$status){
  throw new \RuntimeException("Unable to save a file");
}

实现方法 #

Laravel的S3驱动基于AWS SDK for PHP，要获取详细错误，需要直接调用SDK的客户端并捕获其抛出的异常：

方法一：直接使用AWS SDK客户端 #

绕过Laravel Storage门面，直接实例化AWS S3客户端，捕获SDK抛出的具体异常：

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

$s3Client = new S3Client([
    'version' => 'latest',
    'region'  => env('AWS_DEFAULT_REGION'),
    'credentials' => [
        'key'    => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
    ],
]);

try {
    $result = $s3Client->putObject([
        'Bucket' => env('AWS_BUCKET'),
        'Key'    => 'test.txt',
        'Body'   => date('Y-m-d H:i:s'),
    ]);
} catch (AwsException $e) {
    // 记录详细错误信息
    \Log::error('S3文件保存失败: ' . $e->getMessage());
    \Log::error('AWS错误类型: ' . $e->getAwsErrorCode());
    \Log::error('请求ID: ' . $e->getAwsRequestId());
    
    throw new \RuntimeException("文件保存失败: " . $e->getMessage());
}

方法二：扩展Laravel Storage驱动（自定义异常处理） #

如果想继续使用Laravel Storage门面，可以自定义驱动类并重写put方法，在内部捕获SDK异常：

1. 创建自定义S3驱动类，继承原驱动并覆盖put方法，添加异常捕获逻辑
2. 在config/filesystems.php中配置使用自定义驱动

不过直接使用SDK客户端捕获异常是最直接高效的方案。

关键说明 #

• AWS SDK抛出的AwsException包含错误码、错误详情、请求ID等关键信息，可精准定位权限不足、存储桶不存在、网络故障等具体问题
• 将这些错误信息记录到Laravel日志系统，便于后续回溯排查

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