medialibrary-development

用途

本技能用于在 Laravel 项目中使用 spatie/laravel-medialibrary 包，将文件关联到 Eloquent 模型，并围绕上传、转换与检索媒体开展开发工作。

主要能力

将文件关联到 Eloquent 模型。
支持图像与视频转换。
支持响应式图片。
支持多个媒体集合。
支持多种存储磁盘。
涵盖媒体上传、集合、转换、响应式图片、自定义属性、文件获取、路径与 URL 生成。

不涵盖：无 Eloquent 关联的通用文件存储、非 Laravel 框架。

使用方式

工作流程

识别任务类型（模型设置、添加媒体、定义转换、获取文件等）。
阅读 references/medialibrary-guide.md，聚焦相关章节。
应用参考中的模式，保持代码精简且符合 Laravel 原生风格。

模型设置

每个需要媒体的模型都必须实现 HasMedia 接口并使用 InteractsWithMedia trait：

use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;

class BlogPost extends Model implements HasMedia
{
    use InteractsWithMedia;
}

添加媒体

$blogPost->addMedia($file)->toMediaCollection('images');
$blogPost->addMediaFromUrl($url)->toMediaCollection('images');
$blogPost->addMediaFromRequest('file')->toMediaCollection('images');

定义集合

public function registerMediaCollections(): void
{
    $this->addMediaCollection('avatar')->singleFile();
    $this->addMediaCollection('downloads')->useDisk('s3');
}

定义转换

use Spatie\MediaLibrary\MediaCollections\Models\Media;
use Spatie\Image\Enums\Fit;

public function registerMediaConversions(?Media $media = null): void
{
    $this->addMediaConversion('thumb')
        ->fit(Fit::Contain, 300, 300)
        ->nonQueued();
}

获取媒体

$url = $model->getFirstMediaUrl('images');
$thumbUrl = $model->getFirstMediaUrl('images', 'thumb');
$allMedia = $model->getMedia('images');

建议做法

始终同时实现 HasMedia 接口并使用 InteractsWithMedia trait。
registerMediaConversions() 的参数使用 ?Media $media = null。
调用 ->toMediaCollection() 完成媒体添加。
对需要同步运行的转换使用 ->nonQueued()。
对只应保存一个文件的集合使用 ->singleFile()。
fit 方法使用 Spatie\Image\Enums\Fit 枚举值。

避免做法

迁移前不要忘记运行：php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"
不要用 env() 配置磁盘，应使用 config() 或在 config/media-library.php 中设置。
不要只调用 addMedia() 而不调用 toMediaCollection()，否则媒体不会被保存。
不要引用未在 registerMediaConversions() 中注册的转换名称。

适用场景

当在 Laravel 中处理文件上传、媒体附件或图片处理时；当代码引用 HasMedia、InteractsWithMedia、Media 模型或媒体集合/转换时；当用户希望添加、获取、转换或管理附加到 Eloquent 模型的文件时。

限制

不适用于无 Eloquent 关联的通用文件存储，也不适用于非 Laravel 框架。