应改用社区维护分支 theflyingzamboni/yii2-elasticsearch，兼容 yii 2.0.42+ 和 es 7.x/8.x；注意 http/https 配置、basic auth、ssl 验证、mapping 字段类型匹配及聚合查询 dsl 写法。
composer require 装不上 yiisoft/yii2-elasticsearch 怎么办
常见错误现象是执行 composer require yiisoft/yii2-elasticsearch 报版本冲突，尤其在 Yii 2.0.40+ 或 PHP 8.0+ 环境下。这个扩展已停止维护，官方仓库标记为 abandoned，Packagist 上最新稳定版只支持到 Yii 2.0.38 和 Elasticsearch 6.x。
- 确认你用的 Yii 版本：
php yii version，若 ≥2.0.40，别硬装原版扩展 - 改用社区维护分支：
composer require --prefer-dist theflyingzamboni/yii2-elasticsearch（兼容 Yii 2.0.42+、ES 7.x/8.x） - 安装后清空应用 runtime 缓存：
rm -rf runtime/cache/*，否则可能报Class 'yii\elasticsearch\Connection' not found
配置 elasticsearch 组件时连不上 ES 7.x/8.x
默认配置走 HTTP + 基础认证，但 ES 7.10+ 默认禁用 http.enabled: true，8.x 更彻底移除了 Transport 协议。连不上多数是因为协议或认证没对上。
- 检查 ES 是否启用了 HTTP：确认
elasticsearch.yml含http.port: 9200和http.host: 0.0.0.0（开发环境） - 若开了 Basic Auth（如 Elastic Cloud 或自建启用 security），必须配
auth参数："auth" => ["elastic", "your_password"]
- ES 8.x 默认强制 HTTPS，本地开发可临时关掉安全模块（
xpack.security.enabled: false），否则得配sslPeerVerification: false并用https://地址
ActiveRecord::find()->query() 返回空，但 curl 能查到数据
这是最常踩的坑：Yii2 的 yii\elasticsearch\ActiveRecord 默认只查 _source 字段，且要求 mapping 中字段类型与 PHP 类型严格匹配；ES 返回的文档若含 _id、_score 等元字段，或字段类型是 keyword 但模型声明为 string，就会静默过滤整条记录。
- 先用
curl -XGET '@#@#@#@#@#@#@#@#@#@0'看原始响应，确认_source内容结构 - 在 ActiveRecord 类里显式定义
attributes()，把 ES mapping 里的字段名一一列出来，别依赖自动推断 - 查询时加
->asArray()调试：Article::find()->where(['status' => 'published'])->asArray()->all()
，避免 ORM 层悄悄丢数据
聚合查询（Aggregation）写法和原生 DSL 差太多
扩展封装的 Aggregation 类不支持嵌套聚合或脚本字段，且方法名跟 ES 官方术语不一致（比如 addTerms() 对应 terms aggregation），容易写错结构。
- 直接用原生 DSL 更稳：
$query = ['aggs' => ['by_status' => ['terms' => ['field' => 'status.keyword']]]];<br>Article::find()->addParams(['body' => $query])->all();
- 注意字段后缀：
text类型要查.keyword子字段才能聚合，否则返回空桶 - 聚合结果不在
ActiveRecord实例里，得从ActiveDataProvider的models外单独取：$dataProvider->getRawData()['aggregations']
Elasticsearch 和 Yii2 的胶水层薄，很多问题出在“以为 ORM 会帮你兜底”，其实它只负责发请求和映射 _source。mapping 定义、DSL 结构、HTTP 层配置，三者漏一个就查不到东西。
