访问中间表字段必须用withPivot()，否则自定义字段如role、expires_at将丢失；sync()是全量覆盖而非更新；需自定义Pivot模型才能使用访问器、事件等高级功能。
访问中间表字段必须用 withPivot()
不加这句，Laravel 会把中间表当成纯关联跳板，$model->pivot 只有 id、created_at 这些默认字段，你加的 role、expires_at 全部丢失。
常见错误是只在模型里定义了多对多关系，但忘了在 belongsToMany() 链式调用里显式声明要拉哪些额外字段：
-
withPivot('role', 'priority')—— 字段名必须和数据库列名完全一致（区分大小写） - 如果中间表有
deleted_at，也得写进去，否则软删除状态不可见 - 不能只写
withPivot('*')，Laravel 不支持通配符
$user->roles()->sync() 会清空再写入，不保留原有 pivot 数据
这是最常踩的坑：你以为 sync() 是“更新”，其实它是“全量覆盖”。哪怕只改一个用户的 role 字段，用 sync() 就会把其他没列出来的关联全删掉。
正确做法取决于场景：
- 只想更新某条 pivot 记录？直接操作 pivot 对象：
$user->roles()->where('role_id', 5)->update(['role' => 'admin']) - 想批量更新多条？用
upsert()（Laravel 9.2+）或原生DB::table()->upsert() - 需要原子性增删改？别用 Eloquent，走
DB::transaction()+ 原生 SQL 更稳
自定义 pivot 模型才能用访问器、作用域和事件
如果你需要给中间表字段加逻辑（比如把 status 映射成中文、校验 starts_at < ends_at），光靠 withPivot() 不够——它只提供原始值。
必须定义一个继承 Pivot 的类，并在关系方法里用 using() 绑定：
class RoleUser extends Pivot
{
protected $casts = ['expires_at' => 'datetime'];
public function getRoleLabelAttribute()
{
return match($this->role) {
'admin' => '管理员',
'editor' => '编辑',
default => '成员'
};
}
}
然后在 User 模型里：return $this->belongsToMany(Role::class)->using(RoleUser::class);
- 自定义 pivot 模型后，
$user->roles返回的每个关联对象，其$role->pivot就是RoleUser实例，能用访问器、属性、事件 - 注意：
using()必须配合withPivot()使用，否则字段还是拿不到 - 迁移里中间表主键别设
id，Laravel 自定义 pivot 要求复合主键（user_id+role_id）
使用 attach() 或 syncWithoutDetaching() 时，额外字段必须传数组
很多人以为 attach(1) 就行，结果 pivot 字段全为 null。Eloquent 要求带字段时必须传二维数组：
$user->roles()->attach([1 => ['role' => 'editor', 'priority' => 3]])$user->roles()->sync([1 => ['role' => 'admin'], 2 => ['role' => 'viewer']])- 键是外键 ID，值是字段数组；漏掉某个 ID 就等于从中间表删掉那条记录
- 如果字段含时间戳，别传字符串，用
now()或Carbon::parse()实例
复杂点在于：这些字段不是模型属性，不会触发模型的 casts 或 set* mutator，全靠你在 attach 前手动处理好类型。
