PHP 缺 Elasticsearch 扩展或未启用 cURL 导致 Class 'Elasticsearch\ClientBuilder' not found；需用 Composer 安装对应版本客户端、显式创建索引并定义 mapping、在模型钩子中主动同步、检查网络与安全组配置。
PHP 扩展没装好，elasticsearch 客户端直接报错 Class 'Elasticsearch\ClientBuilder' not found
不是框架问题，是 PHP 环境缺扩展或自动加载没触发。ThinkPHP 本身不自带 ES 客户端，得手动装 elasticsearch/elasticsearch 包。
- 用 Composer 装：运行
composer require elasticsearch/elasticsearch:^8.0（注意版本对齐 ES 服务端大版本，ES 8.x 就别用 7.x 的客户端） - 确认
ext-curl已启用——ES 客户端底层靠 cURL 发请求，php -m | grep curl看不到就去 php.ini 开extension=curl - 别把包放进
vendor里手动拷，Composer 自动注册 autoloader，手放进去不会被识别
索引同步时数据漏掉或字段类型错乱，mapping 没预设就直接写入
ES 不是数据库，它会根据第一条文档的字段值自动推断 mapping 类型。比如第一次写 "price": 99，它定成 long；后面来个 "price": "99.5" 就直接写不进去，报 illegal_argument_exception。
- 上线前必须先用
PUT /your_index_name显式创建索引并定义mappings，尤其是text/keyword分开、日期字段用date、数值字段明确long或double - ThinkPHP 中建议把 mapping 定义抽成 JSON 文件（如
app/config/es_mapping_user.json），同步逻辑里读取后调用$client->indices()->create() - 别依赖
index()接口自动建索引——开发环境可能开了，生产通常关了：action.auto_create_index: false
ThinkPHP 模型变更后，ES 索引没跟着更新，搜索结果还是旧字段
ES 不监听 MySQL 表结构或 TP 模型变化，所谓“同步”全靠你主动触发。没人调 saveToEs()，它就永远停在上次写入的状态。
- 在模型的
afterSave钩子里调 ES 写入逻辑最稳妥，但注意：TP6 的afterWrite更准，因为包含新增和更新 - 批量导入场景别循环调
index()，改用bulk()，100 条一批，否则网络开销炸掉 - 删除操作容易漏——MySQL 删了记录，ES 忘删，搜出来 404。务必在模型
afterDelete里补上$client->delete()或bulk删除指令
本地能连 ES，线上 500 报 cURL error 7: Failed to connect
不是代码问题，是服务器网络策略卡住。ES 默认只监听 localhost，Docker 容器没暴露端口，或者云服务器安全组没放开 9200。
- 检查 ES 配置文件
elasticsearch.yml：必须有network.host: 0.0.0.0和http.port: 9200（别只改 port 忘了 host） - 云服务器（阿里云/腾讯云）进控制台，查安全组是否放行
9200端口——只加了80/443不管用 - Docker 启动 ES 时记得加
-p 9200:9200，且docker run命令里要带--network=host或自定义 bridge 网络，否则 TP 容器根本 ping 不通 ES 容器
ES 索引同步真正的复杂点不在代码怎么写，而在「什么时候写」和「写之前有没有人动过 mapping」。这两处一错，查半天日志都看不出毛病。
php免费学习视频：立即使用
踏上前端学习之旅，开启通往精通之路！从前端基础到项目实战，循序渐进，一步一个脚印，迈向巅峰！
