Yii框架集成Elasticsearch关键在于连接通、索引对、映射准、查询稳：需按ES版本选兼容扩展（如ES 7.x用~2.1.0），显式配置dslVersion与nodes，模型中index()、attributes()、mapping()须严格匹配ES规范，复杂查询须用rawQuery而非QueryBuilder。
Yii 框架集成 Elasticsearch 不是“装个扩展就能搜”，关键在于连接通、索引对、映射准、查询稳——三处出错，搜索就返回空或报 Cluster autodetection did not find any active node 这类错误。
composer 安装 yii2-elasticsearch 扩展时版本怎么选
别直接 composer require yiisoft/yii2-elasticsearch。这个包的主干分支已停止维护，必须显式指定兼容版本：
- ES 7.x → 用
yiisoft/yii2-elasticsearch:~2.1.0（推荐） - ES 6.x → 可用
~2.0.0，但注意type()在 ES 7+ 已废弃，该版本仍保留 type 支持 - ES 8.x → 官方扩展未适配，需降级到 ES 7.17 或改用原生
Elastica客户端
安装命令示例：composer require --prefer-dist yiisoft/yii2-elasticsearch:"~2.1.0"。装完后检查 vendor/yiisoft/yii2-elasticsearch/CHANGELOG.md，确认最后更新时间在 2024 年后。
elasticsearch 组件配置里 nodes 和 dslVersion 必须配对
nodes 数组里的地址必须能被 PHP curl 直接访问，且响应格式要匹配 dslVersion 声明的语法。常见错误：
- ES 启动后没开 HTTP 端口：检查
curl -v http://127.0.0.1:9200是否返回 JSON，含"version": {"number": "7.17.21"} -
dslVersion漏配或错配：ES 7 默认不带 type，但扩展默认dslVersion => 5，会导致createIndex()生成带_type的请求而被拒；务必显式设为7 - 集群节点写成
http_address => 'localhost:9200'：PHP curl 可能解析失败，统一用127.0.0.1
正确配置片段：
'elasticsearch' => [
'class' => 'yii\elasticsearch\Connection',
'dslVersion' => 7,
'nodes' => [
['http_address' => '127.0.0.1:9200'],
],
// 'auth' => ['username' => 'elastic', 'password' => 'changeme'], // 有认证才开
],
ActiveRecord 模型里 index() / attributes() / mapping() 怎么写才不出错
模型不是 ORM 表映射，而是 ES 索引结构的声明式描述。最容易踩的坑是字段类型和 mapping 不一致：
-
index()返回字符串，不能含大写或特殊符号，如'my_index_v1'合法，'MyIndex'会触发 ES 400 错误 -
attributes()列出的字段名，必须和你后续写入文档的 key 完全一致（大小写敏感），且不能包含 ES 保留字段如_id、_score -
mapping()中每个字段的"type"要和实际数据匹配：比如存时间戳用"long"，存中文文本用"text"并配"analyzer": "ik"（需提前装 ik 插件） - 首次建索引必须调用
updateMapping()，否则字段默认是dynamic: true，后期加字段可能类型推断错误（例如第一次写"price": "99"推成text，再写99.5就失败）
示例 mapping 片段（ES 7）：
public static function mapping()
{
return [
'properties' => [
'title' => ['type' => 'text', 'analyzer' => 'ik_smart'],
'price' => ['type' => 'float'],
'created_at' => ['type' => 'long'],
]
];
}
搜索时 queryBuilder 和 rawQuery 的边界在哪
扩展封装了 QueryBuilder，适合简单 match、term、range 查询；但复杂聚合、高亮、suggest 或跨索引操作，必须用 rawQuery：
- 用
search()+where()写['match' => ['title' => 'yii']]是安全的；但想加"highlight"，QueryBuilder不支持，得切到createCommand()->search($index, $rawQuery) -
rawQuery必须是完整 DSL JSON 结构，不是只填query部分；漏掉query外层会直接 400 - 分页参数用
limit()/offset()即可，不用手动塞from/size到 rawQuery 里
rawQuery 示例（带高亮）：
$rawQuery = [
'query' => ['match' => ['title' => 'yii']],
'highlight' => [
'fields' => ['title' => new \stdClass()]
]
];
$result = Yii::$app->elasticsearch->createCommand()->search('my_index', $rawQuery);
ES 字段 mapping 一旦写入就不能改类型，删 index 重建是唯一办法；所以开发期务必先写好 mapping() 再调 updateMapping()，而不是边试边改。
