Laravel对接Elasticsearch教程

本文全面解析了在 Laravel 项目中对接 Elasticsearch 实现高性能全文检索的四种主流方案：从直连官方 8.x 兼容客户端以获得最大控制力，到通过 Scout + matchish 驱动实现模型数据自动同步，再到基于服务提供者封装为容器单例以支撑中大型项目的可维护性与扩展性，最后提供 Guzzle 手动 HTTP 调试方式精准定位连接、认证、映射等常见故障；无论你是追求灵活性、开发效率还是问题排查深度，都能找到适配当前项目阶段与技术约束的落地路径。

如果您在 Laravel 项目中需要实现高性能全文检索，但 Elasticsearch 无法被正确调用或搜索结果不匹配，则可能是由于客户端版本不兼容、连接配置缺失认证、索引字段映射错误或未启用 HTTPS 验证绕过（开发环境）。以下是接入 Elasticsearch 并支持全文检索查询的多种可行方法：

一、使用官方 elasticsearch/elasticsearch 客户端直连

该方式绕过 Scout 抽象层，直接调用 ES REST API，对 ES 8.x 兼容性最佳，可精确控制请求头、SSL 行为与响应解析。适用于需深度定制查询 DSL 或处理复杂聚合场景。

1、执行命令安装客户端：composer require elasticsearch/elasticsearch:^8.0

2、在 config/services.php 中添加配置块，必须包含协议前缀且禁用证书验证（仅限开发）：

3、创建服务类 App\Services\ElasticsearchService，使用 ClientBuilder::create()->setHosts()->setSSLVerification(false)->setBasicAuthentication() 构建实例

4、在控制器中调用 $es->search(['index' => 'posts', 'body' => ['query' => ['match_phrase' => ['title' => 'Laravel教程']]]]) 执行全文检索

二、通过 Laravel Scout + matchish/laravel-scout-elasticsearch 驱动

此方案复用 Scout 的模型同步机制，自动监听 Eloquent 事件并推送数据至 ES，适合已有 Scout 使用经验且需保持统一搜索接口的项目。注意该驱动已适配 ES 8.x 的无 type 设计与 API Key 认证结构。

1、执行命令安装驱动：composer require matchish/laravel-scout-elasticsearch:^4.0

2、运行命令发布 Scout 配置：php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

3、在 .env 文件中设置：SCOUT_DRIVER=Matchish\ScoutElasticSearch\Engines\ElasticSearchEngine 与 ELASTICSEARCH_HOST=https://localhost:9200

4、在模型中启用搜索：class Post extends Model implements Searchable { use Searchable; public function toSearchableArray() { return ['title' => $this->title, 'content' => $this->content]; } }

三、基于服务提供者封装 Elasticsearch 客户端

该方式将客户端注册为 Laravel 容器单例，便于在任意位置通过 app('es') 获取实例，同时支持多集群、前缀隔离与动态凭据注入，适合中大型项目统一管理 ES 资源。

1、新建配置文件 config/es.php，定义 hosts、username、password、prefix 字段，并从 .env 加载

2、创建服务提供者 App\Providers\ElasticsearchServiceProvider，在 register() 方法中构建 ClientBuilder 实例并调用 setBasicAuthentication() 和 build()

3、在 config/app.php 的 providers 数组中追加 App\Providers\ElasticsearchServiceProvider::class

4、在模型或服务中使用 app('es')->search() 查询，或调用 indices()->create() 创建带 mapping 的索引，其中 text 类型字段需显式声明以支持全文分析

四、手动构建 HTTP 请求对接 Elasticsearch

当项目受限于极简依赖或需调试底层通信时，可跳过 SDK 直接使用 Guzzle 发起请求。该方式完全暴露原始请求/响应，便于定位 verify_certs、header 缺失、body 格式错误等底层问题。

1、执行命令安装 Guzzle：composer require guzzlehttp/guzzle

2、构造请求 URL，例如 https://elastic:password@localhost:9200/posts/_search

3、设置请求头：Content-Type: application/json 与 Accept: application/json

4、发送 POST 请求，body 内容为 JSON 格式 DSL，如 {"query":{"multi_match":{"query":"全文检索","fields":["title^3","content"]}}}

文中关于Laravel的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Laravel对接Elasticsearch教程》文章吧，也可关注golang学习网公众号了解相关技术文章。