ThinkPHP6.x集成Elasticsearch需五步：一、安装elasticsearch/elasticsearch:^8.0客户端并启用cURL；二、配置hosts及认证，用info()验证连接；三、安装IK插件并创建带ik_smart分词的索引；四、自建SearchInterface驱动适配v8返回结构；五、通过模型afterWrite/afterDelete钩子同步数据。
如果您在ThinkPHP6.x项目中尝试启用Elasticsearch实现站内全文检索功能，但搜索无结果、索引写入失败或客户端报错，则可能是由于客户端版本不匹配、连接未验证、中文分词未配置、索引未预建或数据不同步所致。以下是解决此问题的步骤：
一、安装并启用兼容的Elasticsearch PHP客户端
ThinkPHP6.x运行于PHP 7.4+环境，必须使用elasticsearch/elasticsearch v8.x客户端；v5/v7客户端因类名、方法签名及返回结构变更，会导致Class 'Elasticsearch\ClientBuilder' not found或406 Not Acceptable错误。
1、在项目根目录执行Composer命令安装指定大版本客户端：composer require elasticsearch/elasticsearch:^8.0
2、确认ext-curl已启用：运行php -m | grep curl应有输出；若无，需在php.ini中取消注释extension=curl并重启Web服务。
立即学习“PHP免费学习笔记（深入）”；
3、执行composer dump-autoload -o强制刷新自动加载器，确保ClientBuilder类可被正确解析。
二、配置ES连接参数并验证网络连通性
客户端必须显式声明hosts、认证方式与SSL策略；默认配置易因network.host绑定localhost或云服务器安全组未放行9200端口而失败。
1、在config/elasticsearch.php中定义连接配置：return ['hosts' => ['http://127.0.0.1:9200'], 'user' => '', 'pass' => '']
2、使用ClientBuilder构建实例并调用info()接口测试：$client = ClientBuilder::create()->setHosts(config('elasticsearch.hosts'))->build(); $client->info();
3、捕获异常并排查：若出现cURL error 7，需检查Elasticsearch配置文件中是否设置network.host: 0.0.0.0，并确认云服务器安全组已开放9200端口。
三、手动创建索引并配置IK中文分词mapping
Elasticsearch默认对text字段使用standard分词器，无法切分中文词汇，导致“笔记本”等关键词无法命中；必须提前创建索引并为title、content等字段指定ik_smart或ik_max_word分词器。
1、确认Elasticsearch已安装对应版本的analysis-ik插件：bin/elasticsearch-plugin install https://github.com/medcl/elasticsearch-analysis-ik/releases/download/v8.12.2/elasticsearch-analysis-ik-8.12.2.zip
2、准备mapping配置数组，明确字段类型与analyzer：'title' => ['type' => 'text', 'analyzer' => 'ik_smart']
3、调用indices()->create()显式创建索引：$client->indices()->create(['index' => 'article', 'body' => ['mappings' => ['properties' => $mapping]]]);
四、实现并注册自定义SearchInterface驱动
ThinkPHP6通过think\contract\SearchInterface解耦搜索能力，不能直接使用think-elastic（其依赖已废弃的v5.x Client类），必须自建驱动并重写search、index、delete三个契约方法。
1、创建app/search/ElasticsearchDriver.php，实现SearchInterface接口，并在构造函数中初始化ClientBuilder实例。
2、重写search()方法：v8返回结构为['hits' => ['total' => ['value' => 123], 'hits' => []]]，需提取$result['hits']['total']['value']
3、在app/provider.php中注册该驱动：App::bind('think\contract\SearchInterface', 'app\search\ElasticsearchDriver');
五、通过模型钩子同步增删改操作至Elasticsearch
Elasticsearch不监听数据库变更，所有同步动作必须主动触发；遗漏afterDelete将导致MySQL已删记录仍可被搜出，点击后返回404。
1、在模型类中定义afterWrite钩子，调用bulk接口批量写入：100条/批，避免连接数耗尽
2、在afterDelete钩子中执行删除逻辑：$this->client->deleteById(['index' => 'article', 'id' => $this->id]);
3、字段类型变更后必须重建索引：先调用$client->indices()->delete(['index' => 'article'])，再用新mapping重新create并全量bulk导入。
