常见失败原因是PHP或Laravel版本不匹配，需按兼容表选对应medialibrary版本；必须执行vendor:publish发布配置和迁移；addMedia()仅接受文件路径、UploadedFile实例或getPathname()对象；查集合需显式传参如getMedia('cover')。
composer require spatie/medialibrary 失败怎么办
常见失败原因是 PHP 版本或 Laravel 版本不匹配，spatie/medialibrary 对版本要求严格。v10（当前主流）要求 PHP ≥ 8.0、Laravel ≥ 10.x；若你用 Laravel 9，得装 v9：composer require spatie/laravel-medialibrary:^9.0。
实操建议：
- 先运行
php -v和php artisan --version确认环境 - 查清你要装的版本对应关系——直接看 GitHub 仓库的
README.md顶部“Compatibility”表格，别信第三方教程写的“最新版通用” - 如果提示
Root composer.json requires spatie/medialibrary ^10, found spatie/medialibrary[dev-main, 10.x-dev] but these were not loaded，大概率是minimum-stability设得太松，删掉"minimum-stability": "dev"或加--with-all-dependencies
发布配置和迁移文件前漏了 vendor:publish
vendor:publish 不只是复制配置，它还决定模型是否自动继承 HasMedia、能否调用 addMedia() ——没执行就写上传逻辑，会报 Call to undefined method addMedia()。
实操建议：
- 装完包立刻跑：
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" - 别只发配置，顺手把迁移也发了：
php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="migrations"，否则media表不存在，上传直接抛SQLSTATE[42S02]: Base table or view not found - 发完记得
php artisan migrate，别卡在“以为发了就完事”这步
addMedia() 传路径还是文件对象？
新手常把 $_FILES 数组或前端传来的 base64 字符串直接塞给 addMedia()，结果报 File not found at path 或静默失败。这个方法只接受三种东西：本地文件路径（/tmp/phpabc123）、UploadedFile 实例、或实现了 getPathname() 的对象。
实操建议：
- 表单用
，后端直接取$request->file('avatar')，它已经是UploadedFile，可直传：$model->addMedia($request->file('avatar'))->toMediaCollection('avatars') - 不要自己拼
$_FILES['avatar']['tmp_name']，Laravel 的UploadedFile已帮你处理好临时文件生命周期 - 如果必须处理 base64，先解码存临时文件：
$path = storage_path('app/temp/'.Str::uuid().'.png'); file_put_contents($path, base64_decode($data)); $model->addMedia($path)->toMediaCollection(); unlink($path);
toMediaCollection() 指定名称后查不到文件
很多人设了 toMediaCollection('cover')，但后面用 $model->getMedia() 却拿不到——因为默认查的是 default 集合。集合名不是标签，是查询时的硬性过滤条件。
实操建议：
- 查指定集合必须显式传参：
$model->getMedia('cover')，而不是$model->getMedia() - 想让某个集合成为“默认”，在模型里加属性：
protected $defaultCollection = 'cover';，这样getMedia()才会查它 - 集合名区分大小写，且不能含空格或特殊字符；用
cover_images比Cover Images安全得多
事情说清了就结束。最常卡住的其实是版本对不上 + vendor:publish 漏步骤 + 集合名查错这三处，其他问题基本是这三者的组合变形。
