PHP 8.2 不内置 Elasticsearch，需协同部署 PHP 环境、ES 服务及官方客户端库；关键在版本匹配（PHP ≥ 8.0）、启用 ext-curl/ext-json、用 composer require elasticsearch/elasticsearch:^8.18 安装，连接时必须显式配置 HTTPS、Basic Auth 与 SSL 验证，并注意 refresh、mapping 和分词器设置。
PHP 8.2 本身不包含 Elasticsearch，也不提供内置客户端；你实际要部署的是「PHP 环境 + Elasticsearch 服务 + PHP 客户端库」三者协同运行的完整链路。其中最容易卡住的不是代码，而是版本错配、扩展缺失或认证配置漏项。
确认 PHP 8.2 环境已就绪且含必要扩展
elasticsearch/elasticsearch v8.x 要求 PHP ≥ 8.0，但仅装对版本远远不够：
-
ext-curl和ext-json必须启用——缺一不可，否则composer require elasticsearch/elasticsearch会直接报错ext-curl missing或json extension not loaded - 若用
phpenv管理 PHP 版本，执行phpenv local 8.2.12后，必须验证php -m | grep -E 'curl|json'确实输出两行 - 若
php -v显示版本正确但composer报扩展缺失，说明composer没走当前 phpenv 的 PHP：运行phpenv which composer查路径，再检查该composer是否绑定到同一 PHP 实例 - 重装 PHP 时务必加
--with-curl和--enable-json（如用 phpenv：phpenv install --reinstall --configure-options="--with-curl --enable-json" 8.2.12）
安装 elasticsearch/elasticsearch 客户端（非 C 扩展）
官方推荐且最稳妥的是 Composer 包 elasticsearch/elasticsearch，不是 php-elasticsearch（C 扩展）或 Elastica（第三方封装）。它适配 ES 8.x，默认基于 Guzzle，自动处理重试、429/503、Basic Auth 等细节：
- 执行
composer require elasticsearch/elasticsearch:^8.18（对应 ES 8.18，兼容 PHP 8.2） - 不要写成
~8.2.3或^8.0——前者可能拉低版本导致不支持 TLS 1.3，后者在 PHP 8.2 下可能触发弃用警告 - 若项目已有旧版依赖冲突，先运行
composer why-not elasticsearch/elasticsearch:^8.18定位阻塞包 - 安装后无需额外
extension=配置，纯 PHP 实现，require 'vendor/autoload.php'即可使用
连接 ES 8.x 时必须显式处理认证与 TLS
ES 8.x 默认启用安全特性（Basic Auth + HTTPS），跳过会导致 401 Unauthorized 或 cURL error 60: SSL certificate problem：
立即学习“PHP免费学习笔记（深入）”；
- 若用
setBasicAuthentication('elastic', 'your_password')，host 必须是https://开头，且setSSLVerification(false)仅限开发环境——生产必须配好 CA 证书并设为true - 不建议把凭证硬编码进 host 字符串（如
'https://elastic:pass@127.0.0.1:9200'），因为setBasicAuthentication()会自动注入Authorization头，更清晰可控 - 集群多节点时，
setHosts(['https://node1:9200', 'https://node2:9200'])中每个地址都需是 HTTPS，且证书需被 PHP 的 OpenSSL 信任（常见坑：自签名证书未导入系统 CA store） - 超时和重试必须显式设置：
->setRetries(3)->setConnectionTimeout(3)->setRequestTimeout(10)，否则默认值在高延迟网络下极易失败
写入数据后搜不到？重点检查 refresh 和 mapping
PHP 调用 $client->index() 成功 ≠ 数据立刻可搜，这是最常被忽略的底层机制问题：
- ES 默认
refresh_interval是1s，所以index()后立即search()可能返回空——加'refresh' => 'true'参数强制刷新（仅测试用，生产禁用） - 中文字段搜不出，大概率是没配中文分词器（如
ik或hanlp），而默认standard分词器把整句当一个 token 切分；建索引时 mapping 必须显式指定：'analyzer' => 'ik_max_word' - 字段类型一旦写入就会固化，后续插入同名字段但类型不同（如 string vs integer）会直接报
mapper_parsing_exception；建索引时务必定义完整mappings，别依赖 dynamic mapping - 批量写入用
bulk()，但注意 body 格式：每条操作指令（index、update）和对应文档必须严格交替，且_id必须在指令行里，不能混在文档体中
真正麻烦的从来不是“怎么连上”，而是“为什么连上了却查不到”“为什么写进去却报错类型冲突”“为什么换台机器就 cert verify failed”。这些点没有魔法开关，只能逐层验证：PHP 扩展 → Composer 依赖版本 → ES 认证开关 → 索引 mapping 定义 → refresh 行为。漏掉任意一环，都会让调试时间翻倍。
