ik_smart和ik_max_word必须在索引mapping中显式指定analyzer与search_analyzer，否则PHP客户端查询将回退至standard分词器导致中文搜索失效；安装IK插件需停ES、清旧目录、匹配版本、赋权并验证；远程词典需配置JVM网络权限。
ik_smart 和 ik_max_word 必须在索引 mapping 中显式指定，否则 PHP 客户端发过去的查询会 fallback 到 standard 分词器，中文搜索直接失效。
elasticsearch-plugin install 失败的常见原因
- 插件目录下已存在
ik文件夹，elasticsearch-plugin会拒绝覆盖，直接报java.lang.IllegalStateException - ES 进程仍在运行，插件安装要求 ES 完全停止（无守护进程残留）
- 下载的 ZIP 包 URL 版本号与当前 ES 不匹配，例如用
v7.17.2的包装在7.16.3上，会静默失败或启动报PluginException - Linux 环境下未给
plugins/ik目录赋予 elasticsearch 用户读执行权限（尤其非 root 启动时）
建议操作顺序：
停 ES → 删除 plugins/ik（如有）→ 用完整 URL 下载对应版本 ZIP → 执行 ./bin/elasticsearch-plugin install [url] → 启动 ES → 调用 GET /_cat/plugins?v 确认列表含 analysis-ik
PHP 客户端创建索引时必须声明 analyzer 和 search_analyzer
不手动定义 mapping，ES 默认用 standard，对中文就是单字切分。PHP 中用 Elasticsearch\ClientBuilder 创建 client 后，建索引必须传入完整 settings + mappings：
立即学习“PHP免费学习笔记（深入）”；
$indexParams = [
'index' => 'article',
'body' => [
'settings' => [
'analysis' => [
'analyzer' => [
'ik_analyzer' => [
'type' => 'custom',
'tokenizer' => 'ik_max_word'
],
'ik_search' => [
'type' => 'custom',
'tokenizer' => 'ik_smart'
]
]
]
],
'mappings' => [
'properties' => [
'title' => [
'type' => 'text',
'analyzer' => 'ik_analyzer',
'search_analyzer' => 'ik_search'
],
'content' => [
'type' => 'text',
'analyzer' => 'ik_analyzer',
'search_analyzer' => 'ik_search'
]
]
]
]
];
$client->indices()->create($indexParams);
漏掉 search_analyzer，match 查询仍会按 ik_max_word 切分 query string，导致“华为手机”搜不出“华为”和“手机”分别出现的文档。
ik_max_word vs ik_smart 在 PHP 查询中的实际影响
-
ik_max_word用于索引阶段：把“人工智能”拆成["人工智能", "人工", "智能"]，提升召回率，但增加倒排索引体积 -
ik_smart用于搜索阶段：把用户输入“人工智能应用”只拆成["人工智能", "应用"]，避免误匹配“人工”+“能应用”这类噪声组合
PHP 构造查询时，不用手动调用分词 API，只要 mapping 正确，match 或 multi_match 就自动走对应 analyzer：
$searchParams = [
'index' => 'article',
'body' => [
'query' => [
'match' => [
'title' => '智慧园区建设'
]
]
]
];
如果发现结果中“智慧”“园区”“建设”各自独立命中但没组合命中，大概率是 search_analyzer 没生效，或字段类型写成了 keyword。
真正容易被忽略的是：IK 的远程扩展词典（如 <a href="https://www.php.cn/link/1fdfb6f89419a6d2e520339bfea2d0bb">https://www.php.cn/link/1fdfb6f89419a6d2e520339bfea2d0bb</a>）依赖 JVM 的网络权限。即使配置了 IKAnalyzer.cfg.xml，ES 启动时若报 java.security.AccessControlException: access denied (java.net.SocketPermission ...)，就必须修改 $JAVA_HOME/jre/lib/security/java.policy，追加对应域名和端口的 SocketPermission——这个策略文件在容器化部署或 OpenJDK 17+ 中位置可能不同，且改完必须彻底重启 ES 进程，热加载不生效。
