ThinkPHP6集成Elasticsearch的核心障碍是SDK断层与三关未过：think-elastic因依赖v5.x客户端（Elasticsearch\Client）而报Class not found，必须改用elasticsearch/elasticsearch:^8.0自建驱动；中文搜不到主因是未配ik分词器mapping；模型变更后ES不更新因缺乏主动同步逻辑，需在afterWrite钩子中调用bulk写入并补全afterDelete删除。
ThinkPHP 集成 Elasticsearch 不是“装个包就能搜”，核心障碍在于：TP6 的搜索契约与 ES 8.x 官方客户端存在 SDK 断层，且中文分词、mapping 控制、数据同步这三关不手动过，搜出来全是空或错乱结果。
为什么 think-elastic 在 TP6 上直接报 Class 'Elasticsearch\Client' not found
这不是配置漏了，是命名空间和类结构彻底变了：think-elastic 依赖的是已废弃的 elasticsearch/client v5.x（类名 Elasticsearch\Client），而 TP6 要求 PHP 7.4+ + elasticsearch/elasticsearch v8.x（主类是 \Elasticsearch\ClientBuilder）。混用会触发：
Class 'Elasticsearch\Client' not found-
ArgumentCountError（比如search()方法参数签名从 array 变成必须带index键） -
406 Not Acceptable（Content-Type 不匹配，v8 默认发application/json，v5 习惯发application/x-ndjson）
解决方案只有一条：删掉 think-elastic，用官方 elasticsearch/elasticsearch:^8.0 自建驱动。
TP6 自定义搜索驱动必须重写的三个方法
think\contract\SearchInterface 只定义了三个契约方法，但每个都得按 v8.x 客户端重写，不能照搬 TP5 示例：
立即学习“PHP免费学习笔记（深入）”；
-
search(string $index, array $params): array：v8 返回结构是['hits' => ['total' => ['value' => 123], 'hits' => [...]]]，不是旧版的['hits' => ['total' => 123, 'hits' => [...]]]；必须提取$result['hits']['total']['value'] -
index(string $index, array $data, string $id = null): bool：v8 的index()不再接受裸数组，必须包装成['index' => $index, 'id' => $id, 'body' => $data]，否则报Missing parameter: index -
delete(string $index, string $id): bool：v8 已移除单文档 delete 接口，必须用deleteById()或走 bulk；若坚持用 delete，得自己封装$this->client->delete(['index' => $index, 'id' => $id])
别省事——漏改任意一个，上线后搜索/写入/删除就随机失败。
中文搜不到？90% 是 mapping 没配 ik 分词器
ES 默认对中文用 standard 分词器，把“无线耳机”切成了 ["无线耳机"] 整体，没法匹配“蓝牙耳机”。不显式设 analyzer，match 查询基本失效。
- 先确认插件已装：
bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.12.2/elasticsearch-analysis-ik-8.12.2.zip（版本必须与 ES 服务端一致） - 建索引时必须传
mappings，不能靠自动创建：$params['body']['mappings']['properties']['title'] = ['type' => 'text', 'analyzer' => 'ik_smart', 'search_analyzer' => 'ik_smart'] -
keyword类型字段不能match，但可用于term过滤；想兼顾搜索和聚合，用fields多字段：'title' => ['type' => 'text', 'analyzer' => 'ik_smart', 'fields' => ['keyword' => ['type' => 'keyword']]]
mapping 创建后无法修改类型，字段写错只能删索引重建——上线前务必用测试数据跑一遍完整流程。
模型数据变更后 ES 不更新？因为没人调它
ES 不监听 MySQL 或 TP 模型，所谓“同步”全靠你代码里主动触发。常见错误：
- 只在
afterSave写入，但 TP6 推荐用afterWrite（覆盖新增/更新） - 批量导入用循环
index()，100 条商品耗时 3 秒以上；必须改用bulk()，每批 ≤ 1000 文档 - MySQL 删了记录，ES 忘删，导致搜出 404 页面；
afterDelete钩子里必须补$client->delete(...)或 bulk 删除指令 - 没加异常捕获，ES 临时不可用导致整个 TP 请求崩掉；所有 ES 调用外层套
try/catch (\Exception $e)，失败至少记日志，别静默吞掉
最易被忽略的一点：ES 索引名默认小写，但 TP 模型名可能含大写字母（如 UserOrder），同步逻辑里必须统一转成 user_order 这类下划线格式，否则索引错位。
