PHP 8 连接 Elasticsearch 报错本质是客户端版本错配、SSL 配置失效、数组结构失真或 mapping 缺失所致；需严格对齐 ES 与客户端大版本、启用 curl 扩展、正确嵌套布尔查询数组、手动创建带 IK 分词器的索引。
PHP 8 连接 Elasticsearch 时出现 cURL error 77、Class 'Elasticsearch\ClientBuilder' not found、中文搜不到、查询返回全部文档等报错，本质是客户端版本错配、SSL 配置失效、数组结构失真或 mapping 缺失所致，不是代码逻辑错误。
解决 Class 'Elasticsearch\ClientBuilder' not found
这一步操作起来很简单，直接在项目根目录执行 Composer 命令即可。
运行 composer require elasticsearch/elasticsearch:^8.0 ——必须与 Elasticsearch 服务端大版本严格对齐，ES 8.x 就不能用 v7 客户端，否则后续会触发 406 Not Acceptable 错误。
确认 ext-curl 已启用：执行 php -m | grep curl，若无输出，需编辑 php.ini 取消 extension=curl 前的分号，并重启 Web 服务或 PHP-FPM。
立即学习“PHP免费学习笔记（深入）”；
【手动生成 vendor/autoload.php 不生效】 切勿将 elasticsearch 包手动解压到 vendor/ 目录下，Composer 才负责注册 autoloader，手放等于白装。
仍报错？执行 composer dump-autoload -o 强制刷新自动加载映射。
修复 cURL error 77（SSL 证书验证失败）
该错误几乎只出现在 HTTPS 连接场景，根本原因是 CA 证书路径错误、格式不匹配或信任链不完整。
方法一：验证证书文件有效性
使用命令 openssl pkcs12 -in /xx/http.p12 -info 检查 .p12 文件是否可读、未损坏；若报错“MAC verify failure”，说明密码错误或文件已损。
方法二：转换为 PEM 格式（更兼容）
执行 openssl pkcs12 -in /xx/http.p12 -clcerts -nokeys -out ca.pem 提取公钥证书，再用 openssl pkcs12 -in /xx/http.p12 -nodes -nocerts -out key.pem 提取私钥（如需），然后在代码中改用 setCaBundle('ca.pem')。
方法三：临时禁用 SSL 验证（仅限调试）
在 ClientBuilder 链式调用末尾添加 ->setVerify(false)。注意：【生产环境绝对禁止此操作】，它会暴露凭据与数据于中间人攻击风险之下。
修正布尔查询返回全部文档的问题
这是最隐蔽的坑：Kibana 里能跑通的 DSL，在 PHP 里却返回所有文档，原因全在 must 子句的 PHP 数组嵌套方式不对。
第一步：确保 must 是数组而非关联数组
错误写法：'must' => ['match' => ['title' => $q]] → JSON 输出为 "must": {"match": {...}}（对象），ES 忽略该条件。
正确写法：'must' => [['match' => ['title' => $q]]] → JSON 输出为 "must": [{"match": {...}}]（数组），ES 正常识别。
第二步：检查 _source 字段位置与拼写_source 必须作为顶层参数传入，不能塞进 query 或 body 内部；拼错成 source 或 index 会导致字段过滤失效。
第三步：所有布尔子句必须严格嵌套在 bool 下filter、should、must_not 若与 must 平级写在 bool 外，会被 ES 当作无效键丢弃。
让中文搜索生效的关键操作
ES 默认用 standard 分词器切中文，结果是单字切分，“笔记本”变成“本”“笔”“记”“本”，搜“笔记本”必然无结果。
必须提前创建索引并显式配置 IK 分词器 mapping，不能依赖 index() 自动建索引——ES 8.x 生产环境默认关闭 action.auto_create_index。
准备 mapping 数组，例如：['title' => ['type' => 'text', 'analyzer' => 'ik_smart']]，其中 ik_smart 适合搜索，ik_max_word 适合高亮。
调用 $client->indices()->create(['index' => 'article', 'body' => ['mappings' => ['properties' => $mapping]]) 手动建索引。
【ES 服务器必须已安装 analysis-ik 插件】 且插件版本与 ES 版本严格对应，否则创建索引时会报 illegal_argument_exception。
