Laravel模型关联最常见错误是belongsTo和hasOne方向写反：外键在当前表用belongsTo，外键在关联表用hasOne；预加载需显式声明嵌套关系，多对多中间表字段须用withPivot()暴露。
belongsTo 和 hasOne 写反了，查不到数据
关系定义错方向是 Laravel 模型关联最常踩的坑。比如 User 表有 profile_id，但你在 User 模型里写了 hasOne(Profile::class) —— 这就错了。hasOne 要求外键在「被关联模型」上（即 Profile 表该有 user_id），而这里外键在 User 表，应该用 belongsTo(Profile::class)。
判断口诀：看外键在哪张表。外键在当前模型对应表 → 用 belongsTo；外键在对方表 → 用 hasOne、hasMany 等。
- 外键字段名不叫
xxx_id？必须显式传第二个参数：belongsTo(Profile::class, 'profile_id') - 关联模型命名不是单数或默认规则？补第三个参数：
belongsTo(Profile::class, 'profile_id', 'id') - Eager loading 时写错方法名（比如把
->with('profile')写成->with('profiles')），会静默失败，查不到关联数据也不报错
with() 预加载后 still triggers N+1
写了 ->with('posts') 却发现还是每条用户查一次 posts？大概率是后续代码又调用了未预加载的关联属性，比如循环中写了 $user->posts->count() —— 这没问题；但如果写了 $user->posts->first()->author，而 author 没预加载，就会触发新查询。
预加载只解决「第一层」关联。嵌套关联必须显式声明：
- 单层：
Post::with('user')->get() - 两层：
Post::with('user.profile')->get()（profile是User的关联） - 带条件的嵌套：
Post::with(['user' => function ($q) { $q->select('id', 'name'); }])->get() - 别用
load()替代with()在集合上反复调用，它不会合并查询，只是延迟加载
多对多中间表字段取不到
用 belongsToMany 建立多对多关系，默认只能拿到关联模型的数据，中间表（pivot）里的额外字段（比如 role、created_at）不会自动暴露。
必须在定义关系时加 withPivot()，否则访问 $user->roles->first()->pivot->role 会报错或返回 null：
return $this->belongsToMany(Role::class)->withPivot('role', 'expires_at');- 如果中间表主键不是
id，或想自定义 pivot 类名，得加->using(UserRole::class) - 注意：pivot 属性默认不可写，要更新中间表字段得用
$user->roles()->updateExistingPivot($roleId, [...]) - 别在 pivot 上直接调用模型方法（比如
$pivot->user），它只是个数据容器，不是模型实例
whereHas() 查不出数据，但数据明明存在
whereHas('posts', fn ($q) => $q->where('status', 'published')) 返回空？常见原因是关联关系本身没定义好，或者子查询条件和关联字段类型不匹配。
排查顺序很关键：
- 先确认
posts()关系方法能正常返回数据：$user->posts是否有结果 - 检查数据库字段类型：比如
status是 enum 或 tinyint，但 PHP 里写了'published'字符串，MySQL 可能静默转成 0 导致不匹配 -
whereHas默认是INNER JOIN语义，如果关联表有软删除（deleted_at不为空），得手动加->withTrashed()或在闭包里过滤 - 别在
whereHas闭包里用select()，它可能干扰 join 条件，尤其涉及聚合或 distinct 时
关系不是配置完就自动生效的魔法，每个箭头方向、每个外键名、每个 pivot 字段，都得和数据库结构严丝合缝。少一个 withPivot，少一个 foreignKey 参数，查出来就是空——这种问题不会报错，只会让你对着日志发呆半小时。
