ThinkPHP连接Elasticsearch应直接使用官方elasticsearch/elasticsearch客户端（v8.x），禁用DB类封装；需显式配置timeout与connect_timeout、抽离为单例服务类、严格校验DSL结构与分词器映射，避免自动mapping导致中文分词失效或字段类型错误。
ThinkPHP里怎么连Elasticsearch不卡住
直接用 curl 或原生 elasticsearch-php 客户端连 ES，比走 ThinkPHP 自带的 DB 类快得多——DB 类会把全文检索当普通 SQL 处理，字段映射、结果集封装全跑一遍，纯属浪费 CPU。ES 查询返回的是 JSON，直接解码用就行，别套模型。
- 推荐用官方维护的
elasticsearch/elasticsearch包（v8.x），不是第三方封装库，兼容性好、错误提示准 - 连接必须设超时：
timeout和connect_timeout都得显式配，ES 响应慢时 PHP 不会等死，避免 FPM 进程卡住 - 别在控制器里 new Client，抽成服务类 + 单例，否则每次请求都重建连接池，TCP 握手开销明显
搜索 DSL 写不对，查不到数据但没报错
ThinkPHP 里拼数组容易漏掉层级，比如把 match 写成顶层键，实际要包在 query 下；或者字段名写成数据库列名（title），而 ES mapping 里可能是 title.keyword 或 title.text。这种错 ES 默认返回空结果，HTTP 状态码还是 200，看着像“没数据”，其实是 DSL 语法合法但逻辑不匹配。
- 调试时先用
curl直连 ES，把 DSL 贴进去验证，确认能返回预期结果再搬进代码 - 多字段模糊搜用
multi_match，别一个个写match；精确匹配优先用term（注意大小写和分词器），别滥用match - 分页别只传
from/size，深度分页（比如from=10000）ES 会拒绝，改用search_after或scroll
中文分词失效，搜“手机”返回“手机壳”却漏了“智能手机”
ES 默认标准分词器对中文是单字切分，智能 → 智 + 能，导致召回率低。必须换中文分词插件，且 mapping 创建时就指定，后续不能改——很多人建完索引才想起来装 IK，结果重导数据都得重新来。
- ES 7.10+ 推荐用
ik_max_word（最大粒度）或ik_smart（最少粒度），mapping 中字段 type 设为text，analyzer指向对应分词器 - ThinkPHP 里建索引的代码要检查：是否用了
PUT /index_name显式定义 mapping？还是靠 ES 自动 mapping？后者大概率分词器没生效 - 更新分词器后，旧文档不会自动重分词，必须用
_update_by_query重建索引，否则新老数据行为不一致
高并发下 ES 返回 429 或超时，TP 日志里只看到“cURL error 28”
cURL error 28 是超时，但根源常是 ES 集群负载高被限流（429 Too Many Requests），而 ThinkPHP 默认没处理这类 HTTP 状态码，直接抛异常中断流程。更麻烦的是，如果多个接口共用一个 ES 客户端实例，某个慢查询会拖垮所有请求。
立即学习“PHP免费学习笔记（深入）”；
- 客户端配置加
retry_on_conflict和max_retries，对 429 主动退避重试，别让前端直接看到错误 - 读写分离：搜索走独立 ES 集群节点（
search角色），写入走另一组（ingest+data），避免 bulk 导入影响查询响应 - TP 的中间件里做简单熔断：连续 3 次 429 就临时降级为 MySQL LIKE 查询（仅限兜底，非长期方案）
ES 的 mapping 结构、分词器选择、客户端连接复用这三块，改错一个，后面调半天都未必见效。尤其 mapping 一旦建好就不能改字段类型，宁可删索引重来，也别硬扛着修。
