ThinkPHP 8.1 本身不提供内置 Elasticsearch 支持，也不自动处理分布式检索；实际方案是用 TP8.1 作业务入口，由独立部署的多节点 ES 集群承担分布式检索，需确保 ES 多节点正常加入同一集群、合理配置分片与副本、客户端连接全部协调节点，并集成 elasticsearch-php v8.x 客户端，手动创建启用 IK 分词的索引，且通过模型事件或脚本主动同步数据。
ThinkPHP 8.1 本身不提供内置的 Elasticsearch 支持，更不自动处理分布式检索逻辑。所谓“在 TP8.1 分布式中使用 ES”，实际是指：用 ThinkPHP 8.1 作为业务入口和调度层，将全文检索任务交由独立部署、多节点组成的 Elasticsearch 集群完成——TP 自身不分布式，ES 才是真正承担分布式检索的角色。
确认 ES 集群已真正分布式运行
这是前提，不是 TP 配置能解决的。必须确保：
- Elasticsearch 已部署多个节点（至少 2 个 data 节点），且通过 同一 cluster.name 加入同一个集群，能在
_cat/nodes?v中看到多个 active 状态节点 - 主分片（number_of_shards）设为 ≥2（如 3 或 5），副本分片（number_of_replicas）设为 1，确保数据自动分片+冗余
- 客户端连接时，setHosts() 传入全部协调节点地址（例如
['http://es-node1:9200', 'http://es-node2:9200']），而非只写一个；ClientBuilder 会自动负载均衡请求
TP8.1 中集成 elasticsearch-php 客户端
使用官方兼容 PHP 8.1+ 的客户端（v8.x 对应 ES 8.x）：
PHP 8.5.12
下载
修复 Core bailout 状态损坏安全问题，以及 BZ2、DOM、PDO、Opcache/JIT 内存与执行错误，改进 Unicode 字素处理、URL 解析、TLS 流状态、信号分发及会话错误处理。
- 执行
composer require elasticsearch/elasticsearch:^8.12（与你 ES 服务端版本严格一致，如 ES 是 8.12.2，就装 8.12.x） - 确保 ext-curl 已启用，PHP 版本 ≥8.1，且 Composer 自动加载正常（报
Class 'ClientBuilder'找不到？先跑composer dump-autoload -o） - 在 TP8.1 的 service 或 helper 中封装客户端，避免每次 new ——推荐用容器绑定单例：
public function getClient(): Client
{
return ClientBuilder::create()
->setHosts(config('elasticsearch.hosts'))
->setRetryAttempts(2)
->build();
}
索引需显式创建并启用中文分词
TP8.1 不会帮你建索引，也不会自动识别中文。必须手动初始化：
立即学习“PHP免费学习笔记（深入）”；
- 确认 Elasticsearch 服务端已安装对应版本的 IK 分词器（如 ES 8.12.2 → 必须装
elasticsearch-analysis-ik-8.12.2.zip），重启 ES 后用GET /_analyze?analyzer=ik_smart&text=笔记本验证分词效果 - 调用
$client->indices()->create()显式创建索引，禁用动态映射（"dynamic": "strict"），并在mappings中为 text 字段指定"analyzer": "ik_smart"或"ik_max_word" - 字段设计示例：
"title": {"type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart"}（建索引用细粒度，搜索用粗粒度，兼顾召回与准确）
数据同步要主动触发，不能依赖自动
TP8.1 没有内置的 ES 同步机制。必须在模型事件或业务逻辑中显式调用：
- 在模型的
afterWrite钩子中，构造文档并调用$client->index()写入单条，或攒够一批后走bulk() - 删除时调用
$client->delete()或bulk()发送 delete 操作 - 更新建议用
update()或直接重写 index（ES 文档不可变，本质是删旧写新） - 首次全量导入可用命令行脚本 +
chunk(500)分批读 MySQL + bulk 提交，避免内存溢出
