Laravel Scout自定义Elasticsearch引擎search()返回null问题

核心问题拆解 #

你的代码存在两个关键问题，直接导致了返回null和map方法异常调用的现象：

1. 自定义引擎的search()方法违背了Laravel Scout的工作流程，提前转换模型导致Builder处理失败
2. map()方法的分支逻辑不完整，存在隐式返回null的情况

问题1：search方法返回值不符合Scout预期 #

Laravel Scout的自定义引擎工作流程是：

• 调用Model::search($query)生成Builder实例
• 调用get()时，Builder先调用引擎的search()获取原始搜索结果（比如Elasticsearch的hits数组）
• 再自动调用引擎的map()方法，将原始结果转换为Eloquent模型

你当前的代码在search()里直接把hits转成模型数组返回，Builder拿到后会继续调用map()方法，但此时传入的$results是已经转换好的模型实例，而非Elasticsearch的hit对象，导致map()里找不到_source字段，最终返回null。

问题2：map方法存在无返回值分支 #

当map()进入else分支时，仅打印日志但没有明确返回值，PHP会默认返回null，这也是结果集中出现null的原因之一。

修复步骤 #

1. 修改search方法，返回原始搜索结果 #

移除search()中转换模型的逻辑，直接返回Elasticsearch的原始hits数组：

public function search(Builder $builder)
{
    $query = $builder->query;
    $params = [
        'index' => 'products_index',
        'body' => [
            'query' => [
                'match' => [
                    'title' => $query
                ],
            ],
        ],
    ];

    $response = $this->elasticsearch->search($params);
    $hits = $response['hits']['hits'];

    if (empty($hits)) {
        Log::warning('No hits found in the search response');
    }

    // 返回原始hits，交给Builder后续调用map方法处理
    return $hits;
}

2. 完善map方法的分支返回逻辑 #

确保map()所有分支都有明确返回值：

public function map(Builder $builder, $results, $model)
{
    if ($results && isset($results['_source'])) {
        Log::warning('every thing seem fine');
        $keyName = $model->getKeyName();
        $modelInstance = $model->newInstance();
        $modelInstance->setRawAttributes($results['_source']);
        $modelInstance->setAttribute($keyName, $results['_id']);
        return $modelInstance;
    }

    Log::error('Missing _source field in search results', ['results' => $results]);
    // 明确返回null，或根据业务需求抛出异常
    return null;
}

额外验证点 #

• 确认自定义引擎类正确实现了Laravel\Scout\Engines\Engine接口，所有必填方法都已实现
• 检查config/scout.php，确保默认引擎配置为你的自定义引擎
• 验证Elasticsearch返回的hits中确实包含_source和_id字段，避免map方法频繁进入错误分支

内容的提问来源于stack exchange，提问作者Ali Arefzadeh