Spatie/laravel-medialibrary 支持自定义磁盘路径、响应式图像、WebP格式、媒体集合分类、自定义属性存储及签名URL安全访问，并可通过队列异步处理文件转换，提升性能与安全性。
在 Laravel 应用中，Spatie/laravel-medialibrary 是处理文件上传和媒体管理的首选包之一。除了基础的上传、删除功能外，它还支持许多高级特性，如自定义目录结构、响应式图像、文件转换、URL 签名、集合（collections）与自定义属性等。下面详细介绍这些高级用法，帮助你更高效地管理媒体资源。
1. 自定义存储路径与磁盘配置
默认情况下，media library 会将文件存储在 storage/app/media 目录下，但你可以灵活指定磁盘和路径。
在模型中通过 registerMediaConversions 和 registerMediaCollections 方法可以控制存储位置：
- 在 config/filesystems.php 中添加自定义磁盘，例如：
'media' => [ 'driver' => 'local', 'root' => storage_path('app/media') ] - 在模型中指定磁盘：
public function registerMediaConversions(Media $media = null): void
{
$this->addMediaConversion('thumb')
->width(100)
->height(100)
->nonQueued();
// 指定该转换存储在特定磁盘
$this->addMediaConversion('webp')
->format('webp')
->withResponsiveImages()
->onDisk('public');
}
使用 onDisk('disk-name') 可将特定转换或原始文件保存到不同磁盘（如 public、s3）。
2. 响应式图片与 WebP 格式支持
为提升网页性能，可生成响应式图像或自动输出 WebP 格式。
- 启用响应式图像：
$this->addMediaConversion('responsive')
->withResponsiveImages();
这样会生成多个尺寸的缩略图，并在前端使用 <img srcset="..."> 实现自适应显示。
- 生成 WebP 版本用于现代浏览器：
$this->addMediaConversion('webp-thumb')
->width(200)
->height(200)
->format('webp');
结合 CDN 或 Nginx 判断浏览器支持情况，优先返回 WebP 资源，节省带宽。
3. 使用集合（Collections）分类媒体文件
一个模型可能有多种类型的媒体（如头像、相册、附件），可通过集合进行逻辑分组。
- 添加到指定集合：
$model->addMedia($path)->toMediaCollection('avatars');
$model->addMedia($path)->toMediaCollection('gallery');
- 获取特定集合的文件：
$avatars = $model->getMedia('avatars');
$gallery = $model->getMedia('gallery');
还可以对不同集合设置不同的转换规则：
public function registerMediaCollections(): void
{
$this->addMediaCollection('avatars')
->singleFile() // 每个模型只保留一个头像
->useDisk('public');
$this->addMediaCollection('gallery');
}
4. 添加自定义属性与元数据
除了文件本身，还可附加额外信息，如上传者、版权说明、排序权重等。
- 添加自定义属性：
$media = $model->addMedia($path)->usingName('风景照')->withCustomProperties([
'author' => '张三',
'location' => '杭州西湖',
'order' => 10
])->toMediaCollection('gallery');
- 读取或更新属性：
echo $media->getCustomProperty('author'); // 张三
$media->setCustomProperty('order', 5)->save();
这些属性存储在数据库的 custom_properties 字段中（JSON 格式），可用于过滤或排序。
5. 安全访问：签名 URL 与私有磁盘
若需限制文件访问权限，可使用签名 URL 结合私有磁盘实现临时授权访问。
- 将媒体保存在非公开磁盘（如 s3-private）：
$this->addMediaCollection('documents')->useDisk('s3-private');
- 生成带过期时间的签名 URL：
$url = $media->getTemporaryUrl(now()->addMinutes(30), 'thumb');
用户只能在 30 分钟内访问该链接，适合文档下载、会员内容等场景。
6. 文件预处理与队列优化
当处理大量图片或视频时，建议将转换任务放入队列，避免阻塞请求。
- 确保模型启用了队列转换：
$this->addMediaConversion('preview')
->width(800)
->height(600)
->queued();
- 配置 config/medialibrary.php 中的
queue_conversions_by_default为 true。 - 运行队列监听器：
php artisan queue:work
这样所有图像缩放、裁剪、格式转换都会异步执行，提高系统响应速度。
基本上就这些。Spatie Media Library 的强大之处在于它的扩展性和灵活性，合理使用上述功能可以让文件管理更加安全、高效且易于维护。不复杂但容易忽略。
