BelongsToMany 关系必须显式指定中间表名和外键，否则 sync() 等操作可能失败；需用 withPivot() 加载额外字段；sync() 是全量覆盖而非增量同步；中间表须有联合主键，否则 detach() 可能失效。
BelongsToMany 关系定义时必须显式指定中间表名和外键
laravel 不会自动推断多对多关系的中间表结构，哪怕命名符合 user_role 这类“字母序拼接”规则。如果不显式声明，sync()、attach() 等操作可能写入错误字段，或查询返回空结果。
正确写法需明确中间表名、当前模型外键、关联模型外键：
public function roles() { return $this->belongsToMany(Role::class, 'user_role', 'user_id', 'role_id'); }-
Role::class：关联模型类 -
'user_role'：中间表名（不能省略，即使叫role_user也得写） -
'user_id'：当前模型（User）在中间表中的外键 -
'role_id'：关联模型（Role）在中间表中的外键
漏掉任意一个参数，Laravel 就按默认规则猜——而默认只认 role_user 表 + role_id/user_id 字段，且顺序固定（关联模型名在前）。一旦表名或字段不匹配，就静默失败。
中间表额外字段要用 withPivot() 才能读取
如果中间表除了两个外键还有 created_at、is_primary 等字段，默认查出来的集合里 $user->roles 是拿不到这些值的。不加声明，Eloquent 直接忽略它们。
必须在关系定义中调用 withPivot() 显式列出要加载的字段：
public function roles() { return $this->belongsToMany(Role::class, 'user_role', 'user_id', 'role_id') ->withPivot('is_primary', 'assigned_at'); }之后就能访问：
foreach ($user->roles as $role) { echo $role->pivot->is_primary; // ✅ echo $role->pivot->assigned_at; // ✅ }注意：pivot 对象不是模型实例，不能调用 save() 或触发事件；修改它需要走 sync() 或 updateExistingPivot()。
sync() 会清空再写入，别在没确认时乱用
sync() 的行为是「全量覆盖」：传入 [1,3,5]，它会删掉所有旧记录，再插入这三条。很多人误以为它是「增量同步」，结果线上用户权限被清空。
- 想追加用
attach([3, 5]) - 想删特定项用
detach([2]) - 想更新 pivot 字段用
updateExistingPivot(3, ['is_primary' => true])
sync() 合适的场景只有两种：管理员批量重置某用户的全部角色，或表单提交时你明确知道这是「最终完整列表」。
另外，sync() 返回的是被删除的 ID 数组（不是新增的），这点容易看反：
$removed = $user->roles()->sync([1, 4]); // 若原来有 [1,2,3]，则 $removed === [2,3]中间表没有主键时，detach() 可能失效
如果中间表用的是联合主键（PRIMARY KEY (user_id, role_id)），Laravel 默认能正常工作。但有些老项目为了兼容或误操作，把中间表设成无主键（或仅有一个自增 id），这时候 detach() 可能只删掉一条记录，甚至不生效。
根本原因是 Laravel 内部依赖主键做 WHERE 条件，无主键时生成的 sql 可能漏条件或逻辑错乱。验证方式很简单：
DB::table('user_role')->where(['user_id' => 123, 'role_id' => 456])->delete(); // 手动删，看是否成功如果这条原生语句都删不掉，说明表结构有问题。修复方案只有两个：
- 给中间表加上联合主键：
ALTER table user_role ADD PRIMARY KEY (user_id, role_id); - 或补上自增
id主键，并在关系定义中用withTimestamps()配合using()指定中间模型（较重，一般不推荐）
这个点藏得深，出问题时日志里不会报错，只会发现「明明调了 detach，数据还在」——得查数据库层面的执行效果才能定位。