把「三體」「未來科技」這類專名寫進自定義詞典，重啟容器後
_analyze切出來的結果和之前一模一樣——詞典沒生效。IK 官方 README 的 FAQ 第一條就點破最常見原因：自定義詞典文件必須 UTF-8 編碼；除此之外還有三個高發點——IKAnalyzer.cfg.xml裡ext_dict寫的文件名和磁盤上文件名對不上、掛載路徑沒落進插件config目錄、以及已有索引不會自動重新分詞（自定義詞只對新索引生效，老數據要重建索引才用得上）。逐個核對，把詞典先驗證成加載成功，再去想分詞結果。
Issue & Env（案發現場與環境）
- 觸發場景：參照教程給 IK 加自定義詞典，目標是把詞典裡沒有的複合專名鎖成整詞。照著步驟建了
mydict.dic、開了IKAnalyzer.cfg.xml的ext_dict、用-v掛載進容器並重啟，結果_analyze返回的還是「未來」「科技」兩個詞，不是「未來科技」。 - 環境：OpenSearch
2.19.0+ analysis-ik2.19.0，Docker 單節點；詞典文件直接掛載進/usr/share/opensearch/plugins/analysis-ik/config/。 - 前置聲明：適用物件是「改詞典文件後分詞結果不變」的讀者；如果你在集群（多個數據節點）上，還要確認每個節點都掛了同一份詞典，節點間設定不一致也會表現成「時靈時不靈」。
- 關鍵區分：這個報錯沒有例外堆疊，服務正常跑、
_analyze正常返回，只是 token 跟你期望的不一樣。「不報錯 ≠ 生效」是排這個坑要時刻記住的。
StackTrace（堆疊日誌）
沒有 4xx、沒有例外日誌。唯一的「證據」是 _analyze 的輸出不符合預期。改詞典前：
{
"tokens" : [
{ "token" : "未来" },
{ "token" : "科技" }
]
}改了詞典、重啟之後，返回還是這倆，一個不少：
{
"tokens" : [
{ "token" : "未来" },
{ "token" : "科技" }
]
}如果節點啟動時加載詞典報錯，docker logs 可能出現 Dictionary 加載相關的棧（比如 Dictionary.loadMySQLExtDict 一層），多數時候是文件路徑或編碼問題觸發：
[ERROR] ... Dictionary.java:dictionary load ...Reproduce（復現程式碼）
常見錯法之一——文件沒存成 UTF-8，或用編輯器保存成了 ANSI / UTF-8 with BOM：
mkdir -p ik-config
# Windows 记事本默认可能存成 ANSI，这不是 UTF-8
printf '未来科技\r\n平凡的世界\r\n' > ik-config/mydict.dic
cat > ik-config/IKAnalyzer.cfg.xml <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="ext_dict">mydict.dic</entry>
</properties>
EOF
docker run -d -p 9200:9200 -p 9600:9600 \
-e "discovery.type=single-node" \
-e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=Devfix@2026" \
--name opensearch-ik \
-v "$(pwd)/ik-config/IKAnalyzer.cfg.xml:/usr/share/opensearch/plugins/analysis-ik/config/IKAnalyzer.cfg.xml:ro" \
-v "$(pwd)/ik-config/mydict.dic:/usr/share/opensearch/plugins/analysis-ik/config/mydict.dic:ro" \
opensearch-with-ik:2.19.0
curl -sk -u admin:Devfix@2026 -X POST "https://localhost:9200/_analyze?pretty" \
-H "Content-Type: application/json" \
-d '{ "analyzer": "ik_max_word", "text": "未来科技" }'
# 期望返回整词：{"token":"未来科技"}，实际无变化则说明没生效Root Cause（根因分析）
詞典加載鏈路：cfg 引用 → 文件編碼 → 文件路徑
IK 在進程啟動時讀取 IKAnalyzer.cfg.xml，根據 ext_dict 指向的文件名去 config 目錄下找文件並解析。鏈條上任何一環斷了，詞典就加載不到，但進程不崩潰——預設詞典還能用，所以表現成「分詞結果不變、也不報錯」。這跟前面兩篇「直接拋例外」的坑形成對照。
四個高發根因
- 文件不是 UTF-8：官方 README 的 FAQ 原文明確寫了——「Please ensure that the text format of your custom dictionary is UTF8 encoded」。Windows 上隨手用記事本存的
.dic，很可能是 ANSI/GBK 編碼，IK 按 UTF-8 解析會讀出亂碼或解析失敗，詞就進不去。 - 文件名對不上：
ext_dict裡寫的mydict.dic，和磁盤上真實文件名必須完全一致，大小寫敏感。寫錯了就靜默找不到文件。 - 掛載路徑不對：容器內的詞典必須落在插件自己的
config目錄（/usr/share/opensearch/plugins/analysis-ik/config/），IKAnalyzer.cfg.xml才能引到；掛到別處（比如只掛在容器根目錄）插件讀不到。 - 老索引不會重新分詞：這是最容易被忽略的一條。IK 分析器在文檔索引時定 token；索引早建好了，詞典後來才加，已入庫文檔的 token 還是舊詞典切出來的，不會自動更新。所以「改詞典後，對存量數據搜不到預期結果」是正常的，得重建索引（reindex / 刪了重建）。
多節點集群的額外因素
多數據節點集群裡，詞典要同步到每個節點並各自重啟。節點間設定文件不一致，就會表現為「有時生效有時不生效」，看起來像玄學。
The Fix（解決方案）
第一步：確認文件是 UTF-8（不帶 BOM）
file ik-config/mydict.dic
# 期望输出含 UTF-8 Unicode text；若出现 ISO-8859 / ASCII（非 UTF-8）要先转码
# 或在此判断有无 CR/BOM
xxd ik-config/mydict.dic | head轉成 UTF-8（去掉 BOM、統一換行）：
iconv -f GBK -t UTF-8 ik-config/mydict.dic > ik-config/mydict.dic.utf8
mv ik-config/mydict.dic.utf8 ik-config/mydict.dic第二步：核對 cfg 文件名和掛載路徑
# cfg 里写的文件名
cat ik-config/IKAnalyzer.cfg.xml
# <entry key="ext_dict">mydict.dic</entry>
# 磁盘文件名必须一字不差、大小写一致
ls -la ik-config/mydict.dic
# 挂载目标是插件 config 目录，别挂到不知名的路径
docker inspect opensearch-ik --format '{{json .Mounts}}'第三步：用貓命令先驗證文件被帶進容器
docker exec opensearch-ik cat /usr/share/opensearch/plugins/analysis-ik/config/mydict.dic
# 应原样打出：未来科技 / 平凡的世界 / 冰激凌第四步：重啟並確認詞典加載
docker restart opensearch-ik
sleep 30
# 位移词典后，_analyze 应命中整词
curl -sk -u admin:Devfix@2026 -X POST "https://localhost:9200/_analyze?pretty" \
-H "Content-Type: application/json" \
-d '{ "analyzer": "ik_max_word", "text": "未来科技" }'
# 期望：{"tokens":[{"token":"未来科技"}]}第五步：存量數據要重建索引
自定義詞只對新索引的文檔生效。要讓新詞典對已有數據生效，刪掉重建或 reindex：
# 彻底重建：删掉旧索引
curl -sk -u admin:Devfix@2026 -X DELETE "https://localhost:9200/books_zh?pretty"
# 重走建索引 + bulk 导入，让文档用新词典重新切词注意事項
- 改完詞典必須重啟生效（除非用 HTTP 熱加載詞典，那要另配
remote_ext_dict）。 - 同一份詞典、多節點集群要同步到所有節點。
- 完整搭建流程，見從零跑通 OpenSearch 中文搜索。