Composer安装Elasticsearch客户端必须严格匹配PHP版本、ES服务版本及异步需求，否则初始化失败或报400/超时；ES 8.x用v8.x客户端，7.x用v7.17，6.x仅支持v6.x；需正确配置host、认证、SSL验证并测试ping连接。
Composer 安装 Elasticsearch 客户端不是“选一个包就行”，关键看 PHP 版本、ES 服务版本、是否需要异步支持——不匹配会导致 ClientBuilder 初始化失败、search() 报 400 或连接超时。
确认 ES 服务版本再选客户端
PHP 客户端和 Elasticsearch 服务端有严格兼容要求，硬装高版本客户端连低版本 ES（比如 7.x）会触发 BadMethodCallException 或返回空响应：
- ES 8.x → 必须用
elasticsearch/elasticsearchv8.x（如^8.4），不兼容 v7 - ES 7.x → 可用 v7.17（
^7.17），v8 客户端会拒绝连接（HTTP 406） - ES 6.x → 只能用
elasticsearch/elasticsearchv6.x（^6.7），v7+ 已移除Transport类
查服务版本：curl -X GET "http://localhost:9200/" 看 version.number 字段。
用 Composer 安装对应版本客户端
别直接 composer require elasticsearch/elasticsearch（默认装最新版，大概率翻车）：
- ES 8.4：运行
composer require elasticsearch/elasticsearch:^8.4 - ES 7.17：运行
composer require elasticsearch/elasticsearch:^7.17 - 如果项目已用 Guzzle，注意 v8 客户端强制依赖
guzzlehttp/guzzle:^7.5，与旧版 Guzzle 6 冲突时需升级或加"guzzlehttp/guzzle": "^7.5"到require
安装后检查 vendor/elasticsearch/elasticsearch/src/ClientBuilder.php 是否存在——没有说明版本未正确载入。
基础连接与搜索代码不能少这三步
光装包不写对初始化逻辑，ClientBuilder::create()->build() 会静默失败或抛 ConnectionFailedException：
- 必须显式设置 host 和 port：
->setHosts(['http://localhost:9200'])（ES 8 默认启用 HTTPS，本地开发用 HTTP 要写全协议） - ES 8 需要 API key 或 basic auth：
->setBasicAuthentication('elastic', 'your_password')（单节点默认密码在elasticsearch.yml里没配就用bin/elasticsearch-setup-passwords auto生成） - 搜索前先测试连接：
$client->ping([])返回true才继续，否则查日志看是不是证书验证失败（verify=false仅限开发环境）
最小可运行搜索示例：
$client = ClientBuilder::create()
->setHosts(['http://localhost:9200'])
->setBasicAuthentication('elastic', 'changeme')
->build();
$response = $client->search([
'index' => 'products',
'body' => [
'query' => ['match' => ['title' => 'laptop']]
]
]);
常见报错和绕不过的坑
这些错误基本都卡在配置层，不是代码逻辑问题：
-
cURL error 60: SSL certificate problem：ES 8 启用 TLS 后，PHP cURL 默认校验证书。开发时加->setSSLVerification(false)；生产环境必须配好 CA 证书路径 -
InvalidArgumentException: Missing required parameter: index：调search()时没传index键，或者用了旧版写法['index' => 'xxx', 'type' => 'yyy']（ES 7+ 已废弃type） -
Client is not configured with any hosts：setHosts()漏了，或传了空数组，或 host 字符串少了http:// - ES 8 返回
406 Not Acceptable：客户端版本太低（比如用 v7 连 v8），或请求头Accept不匹配（v8 客户端自动设为application/json，v7 是application/vnd.elasticsearch+json; compatible-with=7）
ES 的 HTTP 接口细节随大版本变化剧烈，客户端版本、服务端版本、认证方式、SSL 设置四个点只要一个没对齐，就卡在连接阶段——别猜，先 curl -v 对比请求头和响应体。
