Spatie Media Library文件未复制到Laravel Storage问题排查

环境：Laravel 10 + Laravel Sail，安装Spatie Media Library ^11.0.0
TestModel已实现HasMedia接口并引入InteractsWithMedia Trait。

Blade表单代码

<form method="POST" action="{{ route('test.upload', $test->id) }}" enctype="multipart/form-data">
  <input type="file" id="image" name="image" class="">
</form>

控制器代码

public function upload(Request $request, Test $test)
{        
    if($request->has('image')) {            
        $test->addMedia(($request->image))->toMediaCollection('images');
    }
    return redirect()->back();
}

问题现象：

• 上传后无报错、正常重定向，日志无错误记录
• 文件未出现在storage/app/public目录
• 跳过表单直接复制测试图片到storage目录无效
• Laravel Storage写入文件权限正常（执行\Illuminate\Support\Facades\Storage::disk('local')->put('example.txt', 'Contents')可成功生成文件）
• 执行dd( $test->addMediaFromRequest('image')->toMediaCollection() )返回的Media模型中exists字段为false

1. 检查Media Library迁移与配置

   • 确认已执行Media Library的迁移命令：

     sail artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"
     sail artisan migrate
     

     未执行迁移会导致Media模型无法写入数据库，进而无法生成文件。
   • 检查config/media-library.php，确认disk配置项为public（默认值），若指定其他磁盘，文件会存入对应目录。

2. 修正控制器文件处理逻辑

   • 用hasFile替代has判断上传文件有效性，同时使用addMediaFromRequest方法处理上传文件：

     public function upload(Request $request, Test $test)
     {        
         if($request->hasFile('image')) {            
             $test->addMediaFromRequest('image')->toMediaCollection('images');
         }
         return redirect()->back();
     }
     

     has('image')仅检查字段存在性，hasFile('image')会验证是否为有效上传文件；addMediaFromRequest能正确处理上传文件的临时路径，避免直接传入$request->image可能导致的路径异常。

3. 修复Sail环境文件权限

   • 执行命令确保storage目录权限与软链接正常：

     sail artisan storage:link
     sail chmod -R 775 storage bootstrap/cache
     sail chown -R sail:sail storage bootstrap/cache
     

4. 验证TestModel的Media集合配置

   • 在TestModel中显式声明媒体集合，确保磁盘配置正确：

     use Spatie\MediaLibrary\HasMedia;
     use Spatie\MediaLibrary\InteractsWithMedia;
     
     class TestModel extends Model implements HasMedia
     {
         use InteractsWithMedia;
     
         public function registerMediaCollections(): void
         {
             $this->addMediaCollection('images')
                  ->useDisk('public');
         }
     }
     

5. 调试捕获隐藏异常

   • 在控制器中添加异常捕获，查看具体错误信息：

     public function upload(Request $request, Test $test)
     {        
         try {
             if($request->hasFile('image')) {            
                 $media = $test->addMediaFromRequest('image')->toMediaCollection('images');
                 dd($media);
             }
         } catch (\Exception $e) {
             dd($e->getMessage());
         }
         return redirect()->back();
     }
     

     Media模型exists为false通常意味着模型未写入数据库，可通过此方式排查验证失败或数据库写入异常问题。

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