正确写法是belongsToMany（无下划线），必须显式配置中间表字段，否则关联查询为空或报Undefined index: pivot错误；参数共6个，前两个必填，后四个在非标准命名时必须补全；中间表含业务字段须建Pivot模型并用through指定；with仅预加载，whereHas才可筛选主表。
ThinkPHP 6.x 中没有 _belongsToMany 这个方法名，这是常见拼写错误——正确写法是 belongsToMany（无下划线），且必须显式配置中间表字段，否则关联查询为空或报 Undefined index: pivot 错误。
belongsToMany 参数顺序和必填项
参数共 6 个，前两个是必须的，后四个在非标准命名时必须补全：
-
belongsToMany('Role')：第一个参数是关联模型类名（字符串或类引用），注意不是表名 -
'sys_user_role'：第二个参数是中间表名，不能省略；若用默认约定名role_user，才可不传 -
['user_id', 'role_id']：第三个参数是「当前模型在中间表的外键」和「关联模型在中间表的外键」，顺序不能反 -
'id'：第四个参数是当前模型（如User）自身的主键名，默认为id，但若你用的是user_id就得显式传 -
'id'：第五个参数是关联模型（如Role）自身的主键名，同理
完整写法示例：$this->belongsToMany('Role', 'sys_user_role', ['uid', 'rid'], 'user_id', 'role_id')。漏掉任意一个，查出来就是空集合或报错。
中间表要不要建 Pivot 模型？
只读角色列表、批量绑定/解绑 ID，不用建 Pivot 模型；一旦中间表含业务字段（如 status、created_at、sort），就必须建，并用 through 显式指定：
立即学习“PHP免费学习笔记（深入）”；
- 新建
app\model\UserRole.php，继承think\Pivot - 在
User模型中改写关联：return $this->belongsToMany('Role')->through('UserRole'); - 此时
$user->roles返回的每个Role实例会带->pivot属性，里面是UserRole表的字段值
不建 Pivot 却访问 $role->pivot->status，会直接报错或返回 null。
with 预加载和 whereHas 的区别
想查「有某角色的用户」，不能用 with('roles')->where('roles.name', 'admin')——with 的闭包只作用于 Role 模型自身查询，不影响主表筛选。
- 要用
whereHas('roles', function ($q) { $q->where('name', 'admin'); })，这是 SQL 的EXISTS子查询 - 若还要查出该角色的额外字段（比如中间表的
is_primary），得配合hasWhere或手写join -
with('roles')必须放在select()或find()之前，否则无效
常见错误：把 with 放在 where 后面，结果预加载根本没触发。
attach/detach 和 save 的行为差异
这三个方法都操作中间表，但语义和副作用不同：
-
$user->roles()->attach(1)：仅插入中间表记录，不操作Role表；支持传数组、传模型实例、传带字段的二维数组（如[1, ['is_default' => 1]]） -
$user->roles()->detach(2)：仅删除中间表记录，不删Role数据；可传 ID、模型、ID 数组 -
$user->roles()->save(['name' => 'new role'])：先插入Role表新记录，再写入中间表——这通常不是你想要的，除非真要动态建角色
多数场景下，角色是预置好的，只该用 attach/detach；误用 save 可能导致脏数据。
最易被忽略的一点：中间表字段名和模型主键名哪怕只差一个下划线（比如 user_id vs uid），belongsToMany 就会静默失败——它不会报错，只是返回空集合。调试时务必 dump 出生成的 SQL，看 JOIN 条件是否真的对得上。
