Spatie Media Library 不是上传工具，而是媒体资源生命周期管理器；它需手动验证文件、依赖 InteractsWithMedia trait 与数据库迁移，fit 裁剪缩放，resize 拉伸变形，跨模型复用须用 copyFor 或共享 public 磁盘。
直接上手 addMedia() 会失败，不是包有问题，而是它根本不管上传合法性、不校验文件、不检查模型是否就绪——得你把基础链路补全才能跑通。
Call to undefined method addMedia() 是什么信号
这错误只说明一件事：模型没准备好，不是包没装好。常见原因有三个：
- 没在模型里
use InteractsWithMedia;，或者漏了implements HasMedia（Laravel 10+ 可省略接口，但 trait 必须） - 没执行
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="medialibrary-migrations"，导致media表不存在 - 执行了迁移但忘了
php artisan migrate，数据库里还是空的
别查日志，先确认 database/migrations/*_create_media_table.php 是否存在、media 表是否已建好、模型类里有没有那行 use InteractsWithMedia;。
addMedia() 传什么才不会静默失败
addMedia() 只认三类输入：本地路径字符串（如 /tmp/phpABC123）、UploadedFile 实例、或实现了 getPathname() 方法的对象。其他一律不处理，也不报错。
- 前端传
base64？得先解码存临时文件，再传路径 - 用
$_FILES['avatar']数组？不行，要转成UploadedFile：new UploadedFile(...)或更简单——直接用$request->file('avatar') - 想从 URL 下载再上传？得先用 Guzzle 或
file_get_contents()拉下来，保存为临时文件，再传路径
验证必须手动加：$model->addMedia($file)->validate(['max:2048', 'mimes:jpg,jpeg,png'])，否则超大文件或危险类型会直通到底层，等写入磁盘时才崩。
fit() 和 resize() 选错就毁图
这两个方法行为完全不同，选错会导致图片被拉伸变形或意外裁切：
-
fit(300, 200)：强制居中裁剪 + 缩放，输出严格 300×200，适合头像、卡片图 -
resize(300, 200)：单纯拉伸，宽高比丢失，仅用于占位图或明确接受失真的场景 - 想要“宽度 300、高度自适应”？用
width(300)->height(null)，不是resize()
所有转换默认走队列，如果 QUEUE_CONNECTION 没配或设成 sync 以外的值但队列没跑，页面就会卡住不动——开发时建议先设 QUEUE_CONNECTION=sync 确保流程走通。
跨模型复用同一张原图怎么避免文件残留
Media Library 默认按 model_type + model_id 绑定，不共享物理文件。真要复用，别硬改数据库：
- 安全做法：用
$media->copyFor($anotherModel)，生成新Media记录，指向同一文件；删模型时原文件不会被删，除非开了delete_unused_media - 更轻量做法：统一存到
public磁盘，用getUrl('thumb')直接拼 URL，跳过模型关联逻辑 - 绝对别手动插入
Media::create([...])，字段少填一个（比如uuid或disk）就可能让后续getUrl()返回空或 404
真正容易被忽略的是软删除：Media 模型依赖 deleted_at 清理关联，如果目标模型没启用 SoftDeletes，删模型后媒体文件永远留着——哪怕表里 media 记录被删了，磁盘文件还在。
