Spatie medialibrary 可方便管理 Laravel 模型的文件和图片，支持上传、缩略图生成、多磁盘存储等。1. 安装包并发布迁移与配置文件；2. 模型使用 InteractsWithMedia trait 并定义媒体集合；3. 控制器中通过 addMedia 上传文件或从 URL 添加；4. 模板用 getFirstMediaUrl 或 getMedia 获取图片链接；5. registerMediaConversions 定义图像变体如 thumb；6. 调用 delete 或 clearMediaCollection 删除文件；7. 配置 filesystems.php 磁盘并创建 storage:link 软链接以公开访问。
在 Laravel 中使用 Spatie 的 medialibrary 包可以非常方便地管理模型关联的文件和图片，比如用户头像、商品图片、文章附件等。它支持上传、生成缩略图、自定义路径、多磁盘存储等功能，是 Laravel 生态中最受欢迎的媒体管理工具之一。
1. 安装 Spatie medialibrary
在 Laravel 项目根目录下运行以下命令安装包：
composer require spatie/laravel-medialibrary
发布迁移文件并执行数据库更新：
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"
php artisan migrate
发布配置文件（可选）：
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="config"
配置文件位于 config/media-library.php，可根据需要修改默认磁盘、命名规则等。
2. 模型设置：添加媒体支持
假设你要为 Product 模型添加图片管理功能。
确保模型使用了 InteractsWithMedia trait，并注册媒体集合：
namespace App\Models;use Illuminate\Database\Eloquent\Model; use Spatie\MediaLibrary\HasMedia; use Spatie\MediaLibrary\InteractsWithMedia;
class Product extends Model implements HasMedia { use InteractsWithMedia;
// 可选：定义特定集合 public function registerMediaCollections(): void { $this->addMediaCollection('images') ->useDisk('public'); // 使用 public 磁盘 $this->addMediaCollection('downloads') ->useDisk('local'); }}
上面代码中：
- HasMedia 是接口
- InteractsWithMedia 提供具体方法
- registerMediaCollections() 用于定义不同用途的媒体集合
-
useDisk() 指定存储磁盘（需在
filesystems.php配置）
3. 上传文件或图片
在控制器中处理上传请求：
use Illuminate\Http\Request; use App\Models\Product;public function store(Request $request) { $product = Product::create(['name' => $request->name]);
if ($request->hasFile('photo')) { $product->addMedia($request->file('photo')) ->toMediaCollection('images'); } return redirect()->back();}
你也可以上传多个文件：
if ($request->hasFile('photos')) { foreach ($request->file('photos') as $photo) { $product->addMedia($photo)->toMediaCollection('images'); } }或者从 URL 添加图片：
$product->addMediaFromUrl('https://example.com/photo.jpg') ->toMediaCollection('images');4. 显示图片或文件链接
获取第一个图片：
@@##@@getFirstMediaUrl('images') }}" alt="Product">获取所有图片：
@foreach($product->getMedia('images') as $media) @@##@@getUrl() }}" width="200" alt=""> @endforeach获取文件下载链接：
下载文件5. 生成图片缩略图
medialibrary 支持自动生成图像变体（如缩略图）。
在模型中定义：
public function registerMediaConversions($media = null): void { $this->addMediaConversion('thumb') ->width(100) ->height(100) ->sharpen(10);$this->addMediaConversion('web') ->width(800) ->height(600) ->optimize() ->format('webp');}
模板中使用：
@@##@@getUrl('thumb') }}"> @@##@@getUrl('web') }}">注意：只有图像类型才会生成这些变体。
6. 删除和清理文件
删除某个媒体文件：
// 删除指定媒体 $media = $product->getMedia('images')->first(); $media->delete();// 或者清空整个集合 $product->clearMediaCollection('images');
// 清空并重新上传 $product->clearMediaCollection('images'); $product->addMedia($newFile)->toMediaCollection('images');
软删除模型时自动清理媒体（需配置）：
protected static function booted() { static::deleted(function ($product) { $product->media->each->delete(); }); }7. 配置文件系统（filesystems）
确保
config/filesystems.php中有合适的磁盘配置，例如：'disks' => [ 'public' => [ 'driver' => 'local', 'root' => storage_path('app/public'), 'url' => env('APP_URL').'/storage', 'visibility' => 'public', ],'local' => [ 'driver' => 'local', 'root' => storage_path('app'), ],]
运行以下命令创建软链接，使存储文件可通过 Web 访问：
php artisan storage:link基本上就这些。Spatie medialibrary 功能强大又灵活，掌握这几个核心操作就能应对大多数图片和文件管理需求。实际开发中建议结合表单验证、队列处理大文件等方式提升体验。
