HanLP词典加载失败主因是classpath路径错误，需确保词典置于src/main/resources/hanlp/下；自定义词典需显式启用且仅StandardTokenizer支持；多模块需显式依赖或资源拷贝；所有词典必须UTF-8无BOM编码。
HanLP 词典加载失败：classpath 路径不对是最常见原因
Java 项目里 HanLP 找不到词典，十有八九是资源路径没对上。它默认从 classpath:/hanlp/ 下加载 CoreDictionary.txt 等文件，但很多人把词典直接扔进 src/main/resources 根目录，或用错相对路径。
- 确保词典文件放在
src/main/resources/hanlp/目录下（不是resources/平级） - 如果用 Maven 构建，检查
target/classes/hanlp/是否真有这些文件（IDE 编译后可能没自动复制） - 启动时加 JVM 参数
-Dhanlp.root=your/path可覆盖默认路径，但要配全子目录，比如your/path/hanlp/ - 用
System.out.println(HanLP.Config.RootDictionaryPath)打印实际加载路径，比猜快得多
自定义词典不生效：不是加了就立刻被用上
CustomDictionary 加载后默认不参与分词流程，得显式调用或配置开关。而且它只影响 StandardTokenizer 和 IndexTokenizer，NLPTokenizer 或 SpeedTokenizer 默认绕过它。
- 手动加载：调用
CustomDictionary.add("新词", 100)或CustomDictionary.load("custom.dic") - 启用自动加载：在
hanlp.properties中设CustomDictionaryPath=data/dictionary/custom/CustomDictionary.txt（注意路径是相对于RootDictionaryPath的） - 确认分词器类型：用
StandardTokenizer.segment("文本")，别用SpeedTokenizer—— 后者压根不查自定义词典 - 热更新支持弱：
CustomDictionary.reload()仅对内存加载有效，文件变动不会自动触发
多模块项目中词典路径断裂：Maven 子模块资源隔离是隐形坑
父模块配好了 hanlp 目录，子模块调用却报 FileNotFoundException: CoreDictionary.txt —— 这是因为子模块的 classpath 不包含父模块的 resources，除非显式依赖或配置资源拷贝。
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
- 子模块
pom.xml中添加<dependency>指向含词典的模块（且该模块打包类型为jar） - 或在子模块的
maven-resources-plugin里配置<resources>，把父模块词典目录copy进来 - 更稳的做法：统一用
ClassLoader.getSystemResourceAsStream("hanlp/CoreDictionary.txt")测试能否读取，别依赖this.getClass().getClassLoader().getResource()（可能拿到 null） - Spring Boot 项目注意：
application.properties里的hanlp.root配置，得用@Value("${hanlp.root}")注入后传给Config，否则初始化早于配置加载
词典编码错误导致乱码分词：UTF-8 是唯一安全选择
CoreDictionary.txt 如果用 GBK 或 ANSI 保存，HanLP 会按 UTF-8 解码，结果每行首字变 ，整个词典失效。现象是分词结果漏词、切错位置，但无异常抛出。
立即学习“Java免费学习笔记（深入）”；
- 所有词典文件（包括
CustomDictionary.txt、ChineseDictionary.txt）必须存为 UTF-8 无 BOM 格式 - 用 VS Code、Notepad++ 等编辑器打开后看右下角编码标识，不是 “UTF-8” 就另存为；别信 Windows 记事本的“UTF-8”标签（它默认带 BOM）
- Linux/macOS 下可用
file -i your.dic查编码，或iconv -f gbk -t utf-8 input.dic > output.dic转换 - 如果词典里混用了全角空格、不可见 Unicode 字符，
HanLP会静默跳过整行——用hexdump -C或在线十六进制查看器排查
词典加载看着只是配个路径，但 classpath 分层、模块边界、编码隐式转换、分词器类型绑定，四层嵌套下来，任何一个松动都会让分词结果飘忽不定。最省事的验证方式：写一行测试代码，用 DoubleArrayTrieSegment 直接加载词典并 match 一个已知词，绕过所有封装，问题立马浮出水面。
