ThinkPHP本身不带Elasticsearch支持，必须手动集成elasticsearch/elasticsearch客户端并自定义SearchInterface实现类；Class 'Elasticsearch\ClientBuilder' not found需通过composer require elasticsearch/elasticsearch:^8.0安装、启用ext-curl、执行dump-autoload解决；中文搜索失败主因是未显式创建索引及配置ik_smart分词器；数据同步须在afterWrite/afterDelete钩子中主动调用index/bulk/delete；线上连接失败多因ES未监听0.0.0.0或云服务器安全组未放行9200端口。
直接说结论：ThinkPHP 本身不带 Elasticsearch 支持，必须手动集成官方 elasticsearch/elasticsearch 客户端，并自定义搜索驱动；跳过这步直接写 Search::search() 肯定报错。
Class 'Elasticsearch\ClientBuilder' not found 怎么解决
这不是 ThinkPHP 的问题，是 PHP 环境缺失依赖或加载失败。
- 运行
composer require elasticsearch/elasticsearch:^8.0（ES 8.x 服务端必须配 8.x 客户端，混用会出406 Not Acceptable） - 确认
ext-curl已启用：php -m | grep curl，没输出就去php.ini解开extension=curl - 别手动把包丢进
vendor目录——Composer 才管 autoloader 注册，手放进去等于白装 - 报错仍存在？执行
composer dump-autoload -o强制刷新自动加载
为什么 index() 写不进数据，或搜不到中文
根本原因：没显式建索引 + 没配中文分词器，ES 自动 mapping 把中文当乱码处理。
- ES 8.x 默认禁用自动建索引：
action.auto_create_index: false，调index()不会帮你建 mapping - text 字段不指定
analyzer，默认用standard分词器——对中文完全无效，搜“笔记本”肯定返回空 - 必须提前用
$client->indices()->create()创建索引，并在mappings里声明：'title' => ['type' => 'text', 'analyzer' => 'ik_smart'] - 确保 Elasticsearch 已安装对应版本的 IK 插件，例如 ES 8.12.2 就装
elasticsearch-analysis-ik-8.12.2.zip
ThinkPHP 模型数据怎么同步到 ES
ES 不监听数据库变更，所有同步动作都得你主动触发，靠钩子最稳。
立即学习“PHP免费学习笔记（深入）”；
- 在模型的
afterWrite（TP6）或afterSave（TP5）里调用写入逻辑，覆盖新增和更新 - 单条写用
$client->index()，批量导入务必改用$client->bulk()，100 条/批，否则连接数炸掉 - 删除操作极易遗漏：MySQL 删了记录，ES 还留着，搜索出来点开会 404。必须在
afterDelete里补$client->delete()或bulk删除指令 - 别信“自动同步”——上线前检查一遍 mapping 字段类型是否和模型字段一致，比如 PHP 传
float，mapping 却是long，写入直接被拒
本地能连，线上 500 报 cURL error 7 怎么查
99% 是网络层卡住，不是代码问题。
- 检查 ES 配置文件
elasticsearch.yml：必须同时设network.host: 0.0.0.0和http.port: 9200，只改 port 不改 host 无效 - Docker 部署要加
-p 9200:9200并确认容器内网互通 - 云服务器（如腾讯云、阿里云）必须放开安全组中 9200 端口，且协议选 TCP
- 生产环境若启用了 HTTPS + Basic Auth，
ClientBuilder必须加setSSLVerification(false)（仅开发）或传入 PEM 路径，再用setBasicAuthentication()
最容易被忽略的一点：mapping 一旦创建，字段类型无法修改。字段类型错了、分词器漏了、日期格式写成 string 而非 date——删索引重建是唯一解法，别试图 patch。
