Spatie Media Library不是即装即用工具，而是依赖模型trait、数据库迁移和文件系统精准对齐的媒体生命周期管理器；需确保模型use InteractsWithMedia、media表已迁移、addMedia()仅接受UploadedFile实例/本地绝对路径/实现getPathname()的对象。
不是“装完就能用”，而是“配错一步就卡死”——Spatie Media Library 的核心能力（多磁盘、转换、集合）全依赖模型层和文件系统上下文的精准对齐。
Call to undefined method addMedia() 怎么快速定位
这错误只说明模型没接通底层，跟包是否装好无关。先查三件事：
- 模型里有没有
use InteractsWithMedia;（HasMedia接口在 Laravel 10+ 可省略，但 trait 必须） - 数据库里有没有
media表：运行php artisan migrate前，确认database/migrations/*_create_media_table.php已存在且未被删改 - 如果用了自定义迁移路径或分组，检查是否漏加
--tag="medialibrary-migrations"参数
别急着看日志，90% 是这三处之一漏了。验证方式：临时在模型里加个 dd(method_exists($this, 'addMedia'));，返回 false 就是 trait 没生效。
addMedia() 传什么才不静默失败
addMedia() 只认三类输入，其他一律跳过、不报错、不写日志：
- 本地绝对路径字符串（如
/tmp/phpXYZ789） -
UploadedFile实例（$request->file('avatar')返回的就是这个） - 实现了
getPathname()方法的对象（比如用Storage::putFile()后返回的TemporaryUploadedFile）
常见踩坑点：
- 传
$_FILES['avatar']数组 → 不行，必须转成UploadedFile - 传 base64 字符串 → 先解码存为临时文件，再传路径
- 传 URL 字符串 →
addMediaFromUrl()才支持，addMedia()不认 - 没手动验证 → 超大文件或危险类型会直通到底层，等缩略图生成时才崩（常报
Class 'Intervention\Image\ImageManager' not found，其实是 GD 扩展缺失）
fit() 和 resize() 为什么图片变形了
这两个方法行为完全不同，选错就毁图：
-
fit(300, 200)：强制居中裁剪 + 缩放，输出严格 300×200，保持比例，适合头像、卡片图 -
resize(300, 200)：单纯拉伸，宽高比丢失，仅用于占位图或明确接受失真的场景 - 想要“宽度 300、高度自适应” → 用
width(300)->height(null)，不是resize()
所有转换默认走队列，如果 QUEUE_CONNECTION 设为 redis 或 database 但队列没跑，页面就会卡住不动。开发阶段建议先设 QUEUE_CONNECTION=sync 确保流程走通。
文件属主不一致导致 GUI 删除失败
Web 请求由 www-data 处理，生成的文件属主就是 www-data；但 cron 用 root 执行 php artisan schedule:run，所有 media 及 conversions 文件就变成 root 属主 —— 导致 Web 进程无权删除。
解决方案不在 config/media-library.php，而在统一执行用户：
- 把 crontab 条目从
root改为www-data：sudo -u www-data php /var/www/artisan schedule:run - 队列 worker 也必须用同一用户启动：
sudo -u www-data php artisan queue:work - 不要用
chown -R www-data:www-data storage/app临时修复，它治标不治本，下次 cron 写入又变root
真正麻烦的是跨模型复用场景：一张原图被多个模型引用，删掉其中一个模型的关联记录，物理文件不会自动清理 —— delete_unused_media 配置项默认是 false，得手动打开，否则残留文件越积越多。
