medialibrary-development

媒体库开发

概述

使用 spatie/laravel-medialibrary 将文件关联到 Eloquent 模型。支持图像/视频转换、响应式图像、多个集合和各种存储磁盘。

何时激活

• 在 Laravel 中处理文件上传、媒体附件或图像处理时激活。
• 代码引用 HasMedia、InteractsWithMedia、Media 模型或媒体集合/转换时激活。
• 用户希望添加、检索、转换或管理附加到 Eloquent 模型的文件时激活。

范围

• 范围内：媒体上传、集合、转换、响应式图像、自定义属性、文件检索、路径/URL 生成。
• 范围外：未关联 Eloquent 的常规文件存储、非 Laravel 框架。

工作流

1. 确定任务（模型设置、添加媒体、定义转换、检索文件等）。
2. 阅读 references/medialibrary-guide.md，重点关注相关章节。
3. 应用参考中的模式，保持代码简洁并遵循 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。
• 使用 ?Media $media = null 作为 registerMediaConversions() 的参数。
• 调用 ->toMediaCollection() 完成媒体添加。
• 对需要同步运行的转换使用 ->nonQueued()。
• 对只应包含一个文件的集合使用 ->singleFile()。
• 在适配方法中使用 Spatie\Image\Enums\Fit 枚举值。

不应做：

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

参考资料

• references/medialibrary-guide.md