如何排查Laravel中Storage::put方法返回false的具体错误原因？

Laravel 文件系统默认采用静默失败策略，put 方法返回布尔值不会主动抛出错误，可通过以下方式定位具体原因：

首先开启磁盘异常抛出配置，修改 config/filesystems.php 中你的自定义磁盘配置：

'disks' => [
    // 其他原有磁盘配置
    'mycloud' => [
        'driver' => 'xxx', // 对应你实际使用的驱动，比如s3/oss/cos等
        // 保持原有密钥、桶名、地域等配置不变
        'throw' => true, // 新增该行，关闭静默失败，出错直接抛出异常
    ],
]

配置生效后通过 try-catch 捕获具体错误信息：

$ImgSource = (string) Image::make($this->photo)->encode('jpg', 75);

$local = Storage::put("temp/file.jpg", $ImgSource);
try {
    $update = Storage::disk('mycloud')->put($path, $ImgSource);
} catch (\League\Flysystem\FilesystemException $e) {
    // 此处可直接打印/记录具体错误原因，比如权限不足、文件大小超限、路径非法等
    var_dump($e->getMessage());
    exit;
}

如果不想修改全局配置，也可以临时调用适配器获取最近错误：

$update = Storage::disk('mycloud')->put($path, $ImgSource);
if (!$update) {
    var_dump(Storage::disk('mycloud')->getAdapter()->getLastError());
    exit;
}

常见部分文件写入失败原因 #

• 检查失败文件的编码后大小，是否超出自定义磁盘/对应云存储服务的单文件上传上限
• 检查 $path 变量是否存在特殊字符、长度超出云存储路径限制、或者和已有文件重名触发覆盖权限限制
• 检查自定义磁盘绑定的账号权限，是否对写入的路径拥有写入权限，部分云存储会做路径级别的权限隔离
• 检查失败请求的网络状态，是否存在大文件上传时网络超时的情况

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