Laravel 8 空多对多关联使用withPivot抛出QueryException如何解决

• Organisation模型的users多对多关联定义错误：belongsToMany第一个参数应为目标关联模型User::class，当前错误填写为Organisation::class，导致关联映射逻辑异常
• 自定义中间表模型OrganisationMember未继承Laravel提供的Pivot基类，而是继承了默认的Model基类，在使用withPivot/using参数时会出现字段解析异常
• 多对多关联未显式声明外键，存在默认命名匹配失败的隐性风险

1. 修复中间表模型继承关系 #

自定义中间表用于多对多using场景时，必须继承Illuminate\Database\Eloquent\Relations\Pivot类：

use Illuminate\Database\Eloquent\Relations\Pivot;
use Illuminate\Database\Eloquent\Relations\BelongsTo;

class OrganisationMember extends Pivot
{
    public function organisation(): BelongsTo
    {
        return $this->belongsTo(Organisation::class)->withTrashed();
    }

    public function user(): BelongsTo
    {
        return $this->belongsTo(User::class);
    }
}

2. 修复Organisation模型的users关联 #

修正关联目标模型，同时统一补充withPivot声明保证双向关联都能拿到role字段：

use Illuminate\Database\Eloquent\Relations\BelongsToMany;

class Organisation
{
    public function organisationMembers(): \Illuminate\Database\Eloquent\Relations\HasMany
    {
        return $this->hasMany(OrganisationMember::class);
    }

    public function users(): BelongsToMany
    {
        return $this->belongsToMany(User::class, 'organisation_members')
            ->using(OrganisationMember::class)
            ->withPivot('role');
    }
}

3. 优化User模型的organisations关联（可选） #

显式声明关联外键，避免默认规则不匹配导致的隐性问题：

use Illuminate\Database\Eloquent\Relations\BelongsToMany;

Class User
{
   public function organisationMembers(): \Illuminate\Database\Eloquent\Relations\HasMany
   {
        return $this->hasMany(OrganisationMember::class);
   }

   public function organisations(): BelongsToMany
   {
        return $this->belongsToMany(Organisation::class, 'organisation_members', 'user_id', 'organisation_id')
            ->withPivot('role');
   }
}

当存在关联数据时，Laravel会直接执行关联查询返回结果，不会触发异常逻辑路径；当无关联数据时，Laravel会尝试解析中间表模型结构生成空集合的默认属性，由于中间表继承错误、反向关联定义错误，就会抛出字段不存在的异常。

内容的提问来源于stack exchange，提问作者Yahya Uddin