Spatie Media Library 是媒体资源生命周期管理器，非上传工具；addMedia() 需手动验证、依赖 trait 与迁移；大文件失败常因扩展缺失而非超时；fit 裁剪缩放，resize 拉伸变形；跨模型复用需 copyFor 或手动创建，清理须防文件残留。
直接回答：Spatie Media Library 不是“上传工具”，而是围绕 Media 模型构建的媒体资源生命周期管理器；它本身不处理 HTTP 上传，但能优雅承接 request()->file() 或第三方存储（如 S3）的原始文件，并自动关联、转换、清理。
为什么不能直接 $model->addMedia($request->file('avatar')) 就完事？
可以，但容易踩坑：
-
addMedia()默认只做基础注册，不验证文件类型/大小——得手动加->validate()` 或用 Laravel 的validated()预过滤 - 若模型未启用
InteractsWithMediatrait 或未运行迁移，会抛出Call to undefined method addMedia() - 上传大文件时，PHP 超时或内存溢出，
addMedia()会失败但不提示具体原因，日志里只有Class 'Intervention\Image\ImageManager' not found这类误导信息（其实是 GD 扩展缺失导致缩略图生成失败）
registerMediaConversions() 中的 fit() 和 resize() 到底怎么选？
二者行为差异直接影响输出质量与性能：
-
fit(300, 200)：强制裁剪+缩放至精确尺寸，保持宽高比前提下居中裁切多余部分；适合头像、卡片图等需严格尺寸的场景 -
resize(300, 200)：单纯拉伸变形，不裁剪也不保比例；仅用于占位图或明确接受失真的场合 - 若想“缩放到宽度 300，高度自适应并保持比例”，该用
width(300)->height(null)，而非resize() - 所有转换默认异步执行（需队列），若没配好
QUEUE_CONNECTION，页面会卡住；本地开发可临时设为sync测试
如何让同一张图在不同模型上复用（比如用户头像和文章封面共用一张原图）？
Media Library 默认按模型+ID 绑定，不支持跨模型复用。但可通过以下方式绕过限制：
- 不调用
addMedia()，改用Media::create(['model_type' => 'App\Models\User', 'model_id' => 1, ...])手动插入记录（需确保uuid、disk、filename等字段准确） - 更安全的做法：用
Media::find($id)->copyFor($anotherModel)复制一条新记录，指向同一物理文件（注意：删除任一模型关联时，原文件不会被删，除非启用delete_unused_media配置） - 若真要共享存储路径，建议统一存到公共 disk（如
public），再用getUrl('thumb')直接拼 URL，跳过模型绑定逻辑
use Spatie\MediaLibrary\MediaCollections\Models\Media;
// 手动复制 media 到另一个模型（推荐用于少量复用）
$originalMedia = Media::find(123);
$newMedia = $originalMedia->copyFor($post); // $post 是 App\Models\Post 实例
$newMedia->setCustomProperty('source', 'shared_from_user_456')->save();
真正麻烦的不是写法，而是清理逻辑——当一个 Media 被多个模型引用时，delete() 只删关联记录，不删文件；你得自己查 media 表里 count(*) where uuid = ? 是否为 0，再决定是否 Storage::delete()。这点文档几乎不提，但线上磁盘爆满往往就从这里开始。
