必须实现HasMedia接口、配置媒体库驱动并调用toMediaCollection()完成绑定——否则文件上传成功却无关联或报错；模型需引入trait、实现接口、声明registerMediaCollections()；控制器中须用addMediaFromRequest()->toMediaCollection()一站式处理。
要在Laravel中实现用户上传的头像、文章配图或附件自动与对应Eloquent模型实例绑定并持久化存储，必须让模型具备媒体关联能力、配置好文件系统驱动、正确触发上传流程——漏掉任一环节，文件会上传成功但无法查到归属，或直接报错中断。
给模型添加媒体关联能力
打开你要绑定文件的模型文件，例如app/Models/Post.php，在类顶部引入HasMedia trait：
use Spatie\MediaLibrary\HasMedia;
在类定义内部添加HasMedia trait，并实现HasMedia接口：
class Post extends Model implements HasMedia
这一步是强制前提——【不实现HasMedia接口，后续调用addMedia()会抛出Method not found异常】。Spatie包不会自动为你补全接口契约，必须手动声明。
最后，在模型中添加一个空的registerMediaCollections()方法（即使当前不需要自定义集合，也必须存在）：
public function registerMediaCollections(): void { }
配置文件系统与媒体库驱动
运行命令发布配置文件：php artisan vendor:publish --provider="Spatie\MediaLibrary\MediaLibraryServiceProvider" --tag="config"
打开config/media-library.php，确认'disk_name' => 'public'已设置；若要用S3，需提前在config/filesystems.php中配置好s3磁盘，并将此处改为'disk_name' => 's3'。
执行迁移生成媒体表：php artisan migrate。该迁移创建media表，用于记录文件元数据及与模型的关联关系。
确保public/storage已链接到storage/app/public：运行php artisan storage:link。否则前端访问图片路径会404。
控制器中完成上传+绑定全流程
第一步：在控制器方法中接收上传的文件，例如$request->file('image')；
第二步：获取目标模型实例，例如$post = Post::findOrFail($id)；
第三步：调用addMediaFromRequest()并立即toMediaCollection()：
$post->addMediaFromRequest('image')->toMediaCollection();
这行代码会自动完成：校验文件类型、生成唯一文件名、保存到磁盘、写入media表、建立post_id外键关联。不要拆成多步手动处理——【跳过toMediaCollection()会导致文件存了但没关联，查询时media()返回空集合】。
如果需要指定媒体集合名（如区分“封面图”和“配图”），可传参：toMediaCollection('cover')，并在模型的registerMediaCollections()中提前声明该集合。
前端表单与验证要点
表单必须设置enctype="multipart/form-data"，否则$request->file()始终为null。
验证规则建议写为：'image' => 'required|image|mimes:jpeg,png,jpg,gif|max:2048'。注意image规则仅对上传字段生效，且会自动拒绝非图像类型文件。
提交后，可在数据库media表中看到新记录，其中model_type为App\Models\Post，model_id对应Post主键，collection_name默认为default。
