Laravel Scout(Database驱动)无法识别模型关联关系问题

Scout 执行 php artisan scout:import 时，默认只会批量查询模型本身的数据，不会自动预加载关联关系。这就导致在 toSearchableArray() 方法中访问关联模型（比如 $this->courseCategory）时，由于关联未被加载，返回的是 null，进而访问 course_category_name 属性就会抛出「Attempt to read property "course_category_name" on null」错误，而你看到 relations 属性为空也正好验证了这一点——关联数据根本没被加载进模型实例。

要解决这个问题，核心是让 Scout 在导入数据时预加载需要的关联关系，具体有两种可靠的方式：

1. 重写模型的 makeAllSearchableUsing 方法（推荐） #

在 Course 模型中重写该方法，指定预加载关联，这样批量导入时会一次性把关联数据查询出来，既避免 N+1 性能问题，又能确保关联数据存在：

// Course.php
use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Course extends Model
{
    use Searchable;

    // 定义与CourseCategory的关联（假设是belongsTo关系）
    public function courseCategory()
    {
        return $this->belongsTo(CourseCategory::class);
    }

    // 重写该方法，让Scout导入时预加载关联
    public static function makeAllSearchableUsing($query)
    {
        return $query->with('courseCategory');
    }

    // 构建搜索数组
    public function toSearchableArray()
    {
        $baseArray = $this->toArray();

        // 安全获取分类名称（使用空安全操作符避免关联不存在时报错）
        $baseArray['course_category_name'] = $this->courseCategory?->course_category_name;

        return $baseArray;
    }
}

2. 在 toSearchableArray 中手动加载关联（不推荐，易引发N+1） #

如果只是临时需求，可以在 toSearchableArray 里手动加载关联，但这种方式会导致每条数据都单独查询关联，批量导入时性能很差：

public function toSearchableArray()
{
    // 手动加载关联
    $this->load('courseCategory');

    $baseArray = $this->toArray();
    $baseArray['course_category_name'] = $this->courseCategory?->course_category_name;

    return $baseArray;
}

修改完成后，需要重新执行导入命令，让Scout重新生成包含关联数据的索引：

php artisan scout:import "App\Models\Course"

另外，建议在访问关联属性时始终使用 空安全操作符 ?->，即使某些课程没有关联分类，也不会抛出错误，提升代码健壮性。

内容的提问来源于stack exchange，提问作者Sas Sam