前段时间帮人折腾输入法换平台，前后经手了大概七八套词库，从桌面端换到开源框架，又从开源框架换回手机端。几乎每个人一开始都觉得这事很简单——导出、转换、导入，三步。真上手才发现，输入法词库迁移的麻烦根本不在"转换"这个动作上，而在词库这坨数据本身的构成：词条怎么存、词频怎么算、编码对不对、排序规则差多少。我见过最typical的翻车现场，是十几万词条导进去了，看着成功了，结果打一个常用词，候选里排第七，比自带的还要靠后，等于白干。
词库转换工具能解决的，就是把这个过程从"看运气"变成"可复现"。它做的事情很朴素：把源端词库解析成中间结构，归一化处理，重新算分排序，再按目标端的格式吐出来。五分钟确实够，前提是你知道每一步在干什么、哪几个参数会决定最终手感。这篇就把我这几年积累的经验摊开讲，从词库结构、工具选型、到实操命令和一堆踩过的坑，写给正在换输入法、换设备、或者想给团队统一术语库的人看，新手能照着抄，有经验的也能捞到几个细节。
1. 先搞清楚词库文件里到底装了什么
1.1 词条、词频、注音这三件套决定了迁移难度
很多人以为词库就是一份"词的清单"，一个词一行，导进去就完事。实际上主流的用户词库和细胞词库里，一条记录通常是三元组：词条本体、词频权重、可选的注音信息。这个结构看着简单，但它决定了你在转换时会遇到什么样的坑。
词条本体是最直白的部分，但它的边界比想象中模糊。有的词库允许词条里带空格（比如英文短语或者带空格的术语），有的词库会把空格当作分隔符，你把前者转成后者，整个词条会被拆成两半，导入后你会看到一堆莫名其妙的半截词。还有的词条里带标点、带数字、带符号，不同实现对这类字符的容忍度完全不同，转换器如果没做清洗，导进目标端要么被静默丢弃，要么变成排序最靠前的干扰项。
词频权重是最容易被忽略、也是最能左右成品手感的部分。它的本质是"这个词在候选里应该排多前"，但各家用的量纲完全不一样。有的词库把它归一化到 0 到 100 的区间，100 是最高优先级；有的用绝对计数，记录的是"你实际打过多少次"；还有的干脆没有这个字段，排序靠词条在文件里的物理位置或者字典序。你把这个字段原样搬到量纲不同的目标端，结果就是排序彻底乱掉——明明是你天天打的词，跑到第五六位去了。
注音信息则是分水岭。带注音的词库可以直接参与拼音匹配，不带注音的词库得靠目标端自己的词典去反查拼音。反查就会遇到多音字问题："重"到底是 chong 还是 zhong，"长"是 chang 还是 zhang，目标端的默认词典未必和你的习惯一致。这部分后续会单独讲，先记住一件事：词库迁移的质量上限，取决于你对这三件套的理解深度，而不取决于转换器有多快。
1.2 容器格式和字符编码，真正的坑藏在这一层
如果说词条结构是明面上的复杂度，那容器格式和字符编码就是暗礁。市面上流通的词库格式我粗略数过，至少有七八种大类：纯文本（一行一词，或者词与词频用制表符分隔）、带结构的标记文本、以特定扩展名封装的二进制词库、以及各大输入法自家定义的专有格式。开源的输入法框架大多直接吃纯文本，商业输入法则偏爱二进制容器，因为体积小、加载快、还能顺便做个格式保护。
二进制容器带来的第一个麻烦是不可直接编辑。你想手动加十条术语，打不开文件，只能靠工具转出来、改完再转回去。第二个麻烦是版本漂移，同一个扩展名，不同版本的工具导出的内部结构可能略有差异，老版本转换器解析新版本文件时不一定报错，而是安静地丢掉一部分数据。我遇到过最难受的一次，是转出来的词条数比源端统计少了六千多条，没有任何报错，全靠事后比对数量才发现。
字符编码的问题更阴险，因为它的表现形式往往是"部分乱码"而不是"全错"。纯文本词库常见的编码有 UTF-8、带 BOM 的 UTF-8、以及部分老工具仍在用的双字节编码。BOM 这个东西尤其坑：它在文件开头塞了三个不可见字节，多数现代工具会正确跳过，但有些解析器不会，于是你的第一个词条就变成了一串鬼画符，而后面所有词条都正常——这种"只有第一条错"的现象特别容易让人误判成工具 bug。
双字节编码的问题在于字符覆盖范围。生僻字、异体字、部分少数民族文字和符号，在双字节编码里根本没有对应码位，转换时会被替换成一个问号或者一个替代字符。这个过程是不可逆的，你不知道原来那个位置是什么字。所以我的习惯是：只要涉及生僻字或者跨平台迁移，一律先统一转成 UTF-8 无 BOM，再往下走。多花十秒，省掉后面两小时的排查。
转换前先看一眼文件头，用十六进制工具或者命令行的文件类型检测，确认编码和有无 BOM。这一步比任何参数调优都值钱。
2. 三条迁移路线，为什么我最后选了离线转换
2.1 云端同步、手动导出、离线转换的取舍对比
换输入法的时候，摆在面前的路其实有三条，很多人下意识选第一条，然后被坑得最惨。
第一条是云端同步。桌面端登录账号，词库自动上传，手机端登录同一账号，自动下发。这条路最省事，但限制非常硬：它只在同一家的产品体系内生效，跨品牌、跨平台、跨开源框架一律无效；而且它同步的通常只是"用户自学习词库"，也就是你实际打过的词，那些你手动导入的细胞词库、专业术语库、自定义短语，往往不在同步范围内。更麻烦的是它不可控——你没法在同步前做清洗、去重、词频调整，只能接受它给什么就是什么。
第二条是手动导出再手动导入。多数桌面输入法都提供"导出用户词库"的功能，导出一个文本文件，格式各家不同但基本可读。这条路的问题在于"格式转换"这一环仍然要人肉做。如果源端和目标端恰好都吃纯文本，且词条格式一致，那确实能直接导入；一旦涉及二进制格式或者字段顺序不同，就得靠脚本或者工具处理。我早期手写过一段脚本做这事，处理几百条还行，上了十万条就各种边界情况爆炸——特殊字符、空行、重复词条、超长词条，每一条都能让你多调试半小时。
第三条是离线转换工具。它的定位很清晰：吃进去任意一种源格式，吐出来任意一种目标格式，中间所有的清洗、映射、排序都由它负责。这条路多花了几分钟的准备时间，但换来的是可复现和可回滚——同一份源词库，同样的参数，转十次结果都一样；出了问题可以把中间产物留下来逐步比对，而不是对着云端同步的黑盒干瞪眼。
我最后固定用离线转换，核心原因不是它快，而是它把不可见的中间过程变成了可见的文件。你能看到解析出来的原始词条、能看到归一化之后的词条、能看到打分之后的最终顺序，出问题的时候这些中间文件就是最好的排查依据。
2.2 选工具时我实际会看的四个点
挑词库转换工具，网上一堆推荐贴会跟你讲速度、讲界面，但真正决定你用起来顺不顺手的，是另外四件事。
第一，支持的格式清单是不是双向的。有些工具支持把 A 格式转出来，但不支持把改好的词库转回 A 格式。这在需要"导出-编辑-回导"的场景里就是死路。我在选型时会把源端和目标端两个方向的格式都列出来对照，只要有一个方向缺失就换工具。
第二，能不能指定输出编码和换行符。这个功能听起来很基础，但不少图形化工具把它藏起来或者干脆固定死。跨平台迁移时，换行符不一致会引发非常隐蔽的故障——文件在源端看着正常，导入目标端后所有词条匹配不上，因为你肉眼看不见的字符被当成了词条的一部分。
第三，有没有"只输出纯词条"的降级选项。遇到格式不兼容或者字段映射失败时，最靠谱的保底方案是先把所有词条压成一行一词的纯文本，丢掉词频和注音，然后再用目标端自己的工具去重建。有这个选项，你就永远有一条退路。
第四，日志够不够啰嗦。我宁可要一个吵得要命的工具，也不要一个安静的工具。理想的日志应该明确告诉你：解析了多少条、丢弃了多少条（以及为什么丢）、合并了多少重复、有多少条超出长度限制被截断。没有这些数字，你根本不知道转出来的是不是完整数据。
至于界面，命令行和图形界面都行。我偏向命令行，因为可以写进脚本、可以批量处理、可以把参数记在文本里随时复用。图形化的优点是对新手友好，缺点是每次都得重新点一遍相同的选项，容易漏。
2.3 一个容易被忽略的决策：转换还是重建
这里有个很多人没想过的岔路口：你是要把旧词库"搬过去"，还是干脆在目标端"重建"一个新词库？
搬过去适合那些积累了大量专业术语、人名、行话的人，这些词是输入法自带词库里没有的，重建成本极高。重建则适合那些词库主要是日常用语的人——目标端自带的系统词库质量往往不差，你只需要把少数高频的个人用词补进去，剩下的交给系统，反而更干净。
我的判断标准很简单：如果旧词库里超过一半的词条是目标端自带词库里本来就有的常用词，那就别搬了，重建。硬搬的结果是把一堆系统词重复导入，词频叠加，导致某些常见词的候选位置异常靠前，反而把真正需要的长尾词挤得更远。这种情况我在第一次迁移时就踩过，导入后打"我们"两个字，第一候选是"我们"，第二候选居然还是"我们"的变体，看着像bug，实际是重复词条叠加的后果。
3. 转换流水线的四层结构，一层都不能省
3.1 解析层：从容器里把词捞出来，先保完整性再谈其他
解析层干的事情是把源文件读成内存里的结构化数据。听起来是个纯技术活，但这里有个原则必须坚持：先保证捞全，再谈清洗。
很多工具默认在解析阶段就顺手做过滤——丢掉长度小于二的词条、丢掉含特殊字符的词条、丢掉纯数字词条。这些过滤逻辑本身没错，但如果在解析阶段就执行，你就永远失去了"知道丢了多少"的机会。我习惯的做法是让解析层原样输出，把过滤动作全部推到归一化层，这样中间产物里能看到完整的原始数据，出了问题是数据源的锅还是过滤规则的锅，一目了然。
二进制容器在这一层最容易出问题。它的内部结构通常是分块的：文件头记录版本和总条数，然后是索引表，然后是实际数据块。解析时如果只读了数据块没读索引，条数就对不上；如果索引表里的偏移量因为版本差异算错了几字节，读出来的就是一堆乱码，而且不报错。所以我在转二进制词库时有两个固定动作：一是转换后立刻比对条数，二是随机抽十条做人工核对。这两个动作加起来不到一分钟，能拦掉绝大部分静默失败。
编码探测也在这一层。理想情况是文件自带明确的编码声明，现实情况是经常要靠猜。我的策略是优先尝试 UTF-8，失败则尝试双字节编码，两种都失败就当成"未知编码"单独标记出来，不让它污染正常数据。中间产物里我会保留原始字节的十六进制片段，方便事后确认到底哪个环节出了岔子。
3.2 归一化层：繁简、异体、全半角，以及最关键的合并去重
归一化是整个流水线里最考验经验的一层，因为它没有标准答案，全看你的目标端怎么理解"等价"。
第一件事是字符层面的统一。全角字母和半角字母要不要统一？理论上应该统一，实际上有些输入法把全角当成单独的输入模式，你把全角词条改成半角，用户在全角状态下打不出来。数字也一样，全角数字在某些场景下是有效词条。我的做法是默认不统一全半角，只在明确知道目标端不支持时才做转换，而不是无脑清洗。
第二件事是繁简和异体字。如果你的目标端是简体环境，那繁体词条转成简体是合理的；但要注意转换会把不同的繁体字合并到同一个简体字上，如果两个繁体词条转完后变成了一模一样，就产生了重复。反过来，简体转繁体的歧义更大，很多简体字对应多个繁体字，转错了就变成错词。所以我的原则是：只做单向的、语料充分的转换，反方向一律不动，宁可留着繁体词条匹配不上，也不要造出错误的词。
第三件事是去重合并，这是归一化层最核心的动作，也是最容易出错的地方。重复词条在词库里是真实存在的，来源可能有三类：源文件本身就有重复、繁简转换产生了重复、多次导入叠加产生了重复。处理策略要分场景：
| 场景 | 推荐策略 | 原因 |
|---|---|---|
| 单次转换，源文件内部重复 | 词频取最大值，保留一条 | 重复代表同一份权重被写了两次，相加会虚高 |
| 增量合并，旧库加新库 | 词频相加，设上限截断 | 新旧两段的输入次数应该累积，但要防止个别词无限膨胀 |
| 同一份词库被重复导入 | 先做文件指纹比对，直接跳过 | 这是操作事故，靠策略救不回来 |
表格里第三行是我踩过的真实事故。同一份词库导了两次，第二次导入后所有词的词频都变成了两倍，而目标端的词频字段有上限，超出上限的词全部被截断到同一个值，结果就是几千个词挤在同一个优先级上，候选顺序变成随机的。修的办法是回滚重来，代价是半小时。
还有个细节：去重时的比较基准是"词条字符串完全相等"还是"归一化之后相等"。这两个差别很大。"ＡＢＣ"（全角）和"ABC"（半角）字符串不相等，但归一化后相等；"重庆"和"重慶"同理。我一般按归一化之后比较，保留先出现的那条（通常是词频更高的那条），这样能有效压缩体积。
3.3 打分映射：词频怎么搬才不"翻车"
这一层是决定最终手感的关键，也是我见过最多人放弃的地方——转完之后词都在，但排序不对，用起来就是别扭，最后干脆放弃迁移。
核心问题是量纲不匹配。假设源端的词频范围是 0 到 500（绝对计数），目标端的有效范围是 0 到 100（相对权重）。最直觉的做法是线性缩放，除以 5。但这么做的结果是灾难性的：源端词频 50 以下的词（也就是绝大多数只打过几十次的词）缩放完都变成了 10 以下，和目标端系统词库的默认权重混在一起完全分不出来；而源端词频 300 以上的少数词直接顶到 60，还是不够高。
我实际用的方案是分段映射，把源端词频切成几档，每档映射到目标端的一个区间，而不是做线性缩放。大致长这样：
源词频 >= 200 -> 目标 90 ~ 100 源词频 100 ~ 200 -> 目标 70 ~ 90 源词频 30 ~ 100 -> 目标 50 ~ 70 源词频 10 ~ 30 -> 目标 30 ~ 50 源词频 1 ~ 10 -> 目标 10 ~ 30 源词频 0 或无词频 -> 目标 5 ~ 10档内再做一次线性插值，保证同档内的相对顺序不丢失。这套映射的逻辑是：把你在源端最常用的那批词顶到目标端的高位，让它们和系统词库形成明显分层；中间档的词给中等权重，保证能出现在候选里但不抢位；低频词只保留存在感，不争夺排序。实测下来，这套映射比线性缩放的手感要好一个档次，尤其是在"打缩写出长词"的场景里，优先级分层非常明显。
除了词频，还有第二个加权因子：词长惩罚。原因很实际——长词条如果权重太高，会严重干扰短输入的候选列表。你打两个字母，本来想出一个双字词，结果第一候选是一个四字术语，这就是长词条权重过高的典型症状。我的做法是给超过四个字的词条乘一个衰减系数，每多一个字乘 0.92 左右，这样既能保留长词的可用性，又不会让它们到处抢位。
第三个因子是来源权重。如果你在合并多个来源的词库（比如系统词库 + 个人词库 + 团队术语库），不同来源的可信度不一样。我的默认权重是：个人实际输入词 1.2，手动整理的术语库 1.1，系统或第三方词库 0.9。这只是一个起点，具体数值要根据你导入后的实际手感微调，比如发现术语老是抢不到第一位，就把术语库的权重往上提 0.1 再试。
3.4 输出层：编码、换行、排序，三处细节定生死
输出层看着最简单，实际上翻车率不低，因为它的错误最难被发现。
编码：前面说过，默认输出 UTF-8 无 BOM。带 BOM 的 UTF-8 在很多解析器里会在第一个词条前多出三个字节，表现为第一个词条变成乱码或者变成一个奇怪符号开头的词。如果你的目标端明确要求带 BOM（少数系统会有这个要求），那就按它的要求来，但一定要事后验证第一条词条是否正常。
换行符：这是个纯粹的隐蔽杀手。文本文件在 Windows 上习惯用回车加换行两个字符，在类 Unix 系统上只用一个换行符。如果你的转换器在 Windows 上输出、目标端在类 Unix 系统上读取，而对方又没有做兼容处理，那么每个词条末尾都会残留一个不可见的回车字符。这个残留字符的后果是：词条看着正常，但匹配的时候永远匹配不上，因为输入的是一个干净字符串，词库里存的是一个带尾巴的字符串。我在这个问题上浪费过整整一个下午，最后靠十六进制查看才发现每行末尾多了一个 0D。
排序：输出文件里的词条顺序要不要按词频排？这取决于目标端怎么读。有的目标端完全依赖文件里的顺序来建立优先级，那你就必须按词频降序输出；有的目标端会读取词频字段自己排序，顺序无所谓。判断办法很简单：看目标端的文档，或者做个小实验——输出两份词条相同但顺序相反的文件，分别导入，看候选顺序有没有变化。有变化就说明顺序有意义。
还有一点，输出前做一次全量校验。校验内容包括：条数是否等于预期、有没有空行、有没有超长词条、有没有纯符号词条、第一条和最后一条是否正常可读。这五项检查加起来不到一分钟，能拦掉 80% 的导入失败。
4. 五分钟实操：从源端导出到目标端验证
4.1 源端导出：把词库"请"出来的几种姿势
第一步是把源词库从输入法里弄出来。不同产品给的口子不一样，我按常见程度排序。
桌面端输入法通常在设置里有个"词库"或"用户词库"页，里面提供导出功能，导出的格式一般是自家的二进制格式或者纯文本。如果是纯文本，直接拿走；如果是二进制，记下扩展名，转换时需要指定对应的解析器。
开源输入法框架最省事，因为它本身就是文本文件存储的。你要做的只是找到那个文件，通常在用户配置目录下，文件名里有 dict 字样。这类文件一般也带词频字段，格式规整，转换成功率高。唯一要注意的是它可能分成多个文件（主词库、用户词库、临时词库），要先搞清楚哪个是你真正想搬的。主词库通常是别人整理好打包的，搬过去意义不大；用户词库才是你实际积累的部分。
手机端输入法是最难的。很多产品只提供云端同步，不提供本地导出。这种情况下有两个办法：一是把手机端的词库通过账号同步到同品牌的桌面端，再从桌面端导出（前提是你有同品牌的桌面版）；二是放弃手机端词库，只把桌面端的搬过去，手机端靠长期使用慢慢积累。我一般选第二个，因为手机端的自学习词库以短词和网络用语为主，重建成本不高。
导出时有个细节值得注意：先清空一次"临时词库"或者"最近输入"缓存再导出。有些产品会把最近输入但未固化的词单独放在一个临时区，导出的用户词库里可能包含这些半成品，它们词频很低、拼写也不稳定，混进去纯属噪音。
4.2 一条命令完成转换：参数逐项说明
假设你手上的转换工具是命令行形态，最简的一次转换大概长这样（参数名以你手头工具的帮助文档为准，这里给的是通用结构）：
dictconv \ -i ./source/user_dict.scel \ -o ./output/target_dict.txt \ -f target-plain-utf8 \ --source-encoding auto \ --output-encoding utf-8-nobom \ --line-ending lf \ --freq-map segmented \ --len-penalty 0.92 \ --min-len 2 \ --max-len 20 \ --dedup max \ --sort-by freq-desc \ --report ./output/convert_report.log逐个说清楚每个参数在干什么，以及为什么这么设：
-i和-o是输入输出路径，没什么好说的，唯一的建议是永远不要覆盖源文件，输出单独放一个目录，转换失败时源数据还在。
-f指定目标格式。这个名字取决于工具，你需要查它的格式列表。选错格式的典型表现是：文件生成成功，但内容格式完全不对，导入端报"格式不支持"。
--source-encoding auto让工具自动探测源编码。如果你的源文件编码明确（比如你自己导出时就知道是 UTF-8），直接指定可以省掉探测时间，也更可靠。
--output-encoding utf-8-nobom和--line-ending lf是前面反复强调的两项，跨平台迁移时必设。
--freq-map segmented启用分段映射。如果工具只提供线性映射，那就得手动算系数，或者用后处理脚本重算词频——这也是我偏好支持自定义映射工具的原因。
--len-penalty 0.92是词长衰减系数。这个值我在不同场景下调过几次：日常聊天场景用 0.92 比较合适；如果是术语密集的专业场景，术语普遍较长，衰减太狠会导致术语永远排不上来，这时候要放宽到 0.96 甚至 0.98。
--min-len 2和--max-len 20是长度过滤。最短两个字是因为单字词条在多数输入法里由系统词典负责，个人词库塞单字意义不大，反而容易造成候选污染。最长二十个字是我试出来的经验值，超过二十字的"词条"基本是句子，不该进词库。但要注意，不同目标端对词条长度的上限不一样，导入前最好确认一下，超限的词条有的会被截断，有的会被直接丢弃，后者更隐蔽。
--dedup max是去重策略，取词频最大值。前面表格里讲过，单次转换用 max，增量合并用 sum。
--sort-by freq-desc按词频降序输出，配合那些依赖文件顺序的目标端。
--report生成一份转换报告。这个参数强烈建议加上，报告里会写清楚解析条数、过滤条数、去重条数、最终输出条数。这四个数字必须能对上账：解析条数减去各类过滤条数，再加上去重合并省下的条数，应该等于最终输出条数。对不上就说明有环节出了问题。
4.3 导入后的验证清单：五项手感检查
转换完成不等于迁移成功，导入之后必须验证。我固定做五项检查，十分钟内能做完。
第一项，条数核对。目标端的词库管理界面通常会显示词条数，和你转换报告里的最终输出条数比对。数量差很多说明导入被大量过滤；差一点点（几条到几十条）通常是目标端自己的长度或字符限制导致的，属于正常损耗。
第二项，生僻自造词测试。挑三到五个你词库里最冷门的词，输入它们的完整拼音，看能不能出现在第一候选。这是验证"词条是否真的进去了"最直接的办法。如果第一候选没有但翻几页能找到，说明进去了但权重太低；如果完全找不到，说明被过滤或者匹配不上。
第三项，缩写命中测试。输入一个长词的首字母缩写，看词能不能出来。这一项验证的是注音信息和匹配逻辑，比第二项更严格——有些词条本身在词库里，但注音信息没转对，缩写就匹配不上。
第四项，常用词位置的回归测试。挑十个你平时打得最多的词，逐个输入完整拼音，看第一候选是不是你要的。这是验证词频映射有没有生效的关键。如果常用词跑到后面去了，说明映射参数需要调；如果所有词的第一候选都是同一个奇怪的东西，说明有重复词条叠加。
第五项，长句输入测试。连续打一段二三十字的正常句子，观察候选过程有没有异常卡顿、有没有把词组切得乱七八糟。这一项主要验证词库体积和词长分布是否合理，词库过于臃肿或者长词条过多，都会在这个测试里暴露出来。
五项测试里只要有任意一项不过，就先别急着删源文件。保留源词库和中间产物，把问题定位清楚再收尾，这个过程省下来的时间远比重新导一遍要多。
5. 高频故障排查实录
5.1 乱码与丢词：两种表现的排查路径完全不同
乱码的特征是内容可见但字符错误，比如本该是中文变成问号、方块或者奇怪的拉丁字母。排查时先区分范围：如果全部乱码，是编码整体不匹配，把输出编码换一个再试；如果只有首条乱码，是 BOM 问题；如果只有部分词条乱码，通常是源端的双字节编码覆盖不了那些字符，属于数据源本身的损失，转换环节救不回来，只能改用覆盖范围更大的编码重新导出源文件。
还有一个隐蔽情况：乱码只在特定位置出现，比如所有包含某个字的词条都乱。这往往不是编码问题，而是该字符在目标端的字符集里不存在，被替换了。解决办法是确认目标端的字符集范围，或者把这些词条单独拎出来做替换处理。
丢词的特征是数量对不上或者特定词找不到，但没有任何报错。排查路径是分层的：先看转换报告里解析了多少条，和源端统计对比，确认是不是解析阶段就漏了；如果解析条数对得上，再看过滤和去重阶段丢了多少，判断是不是过滤规则太激进；如果中间产物里有这个词但最终文件里没有，那就是输出阶段的长度限制或者字符过滤干掉的。
我遇到过一次特别绕的丢词，最后发现是换行符导致的：目标端在读取时把整个文件当成了一行，因为文件用的是单换行符而目标端期待双字符换行，结果它只认识第一条记录。这种问题靠数条数是发现不了的（因为它会报"只导入了 1 条"），但如果目标端不报错而是安静地只加载第一条，你就会以为是丢词。所以换行符这一项，一定要在导入前用十六进制确认。
5.2 候选顺序全乱：三个层次的原因
这是最常见的抱怨，但原因分层很明显，逐层排查能快速定位。
第一层，词频全是同一个值。打开输出文件看词频字段，如果全是 0 或者全是一个固定数，说明映射环节没生效。可能是源词库压根没有词频字段，可能是映射参数没被识别，也可能是目标端不接受词频字段、自己重新排了序。这种情况下先用一个小样本（几十条词）手动指定不同的词频测一遍，确认目标端是否真的认这个词频。
第二层，词频有区分但整体偏低。表现为你要的词都在候选里，但位置普遍靠后，被系统词库压着。这是映射区间设得太保守，把整体权重往上抬一档就好。判断方法是拿一个你确定高词频的词，看它的目标词频值和系统词库里同类词的默认值差多少。
第三层，个别词异常靠前，挤掉了正常词。这基本可以确定是重复词条叠加或者长词条权重过高。先做一次去重，再看长词条的权重衰减有没有开。还有一种少见情况：某个词的词频字段被解析成了极大值（比如源端用 -1 表示"无词频"，被当成数值参与了排序），这种要在解析阶段就做特殊值处理。
5.3 生僻字、多音字、超长词条这三类特殊数据
生僻字的问题在于编码和显示两处。编码层面，只要统一用 UTF-8 就能覆盖绝大多数汉字；真正麻烦的是输入法本身可能不认这些字，输入时打不出来。这类词条我一般单独列一个清单，导入后手动验证，打不出来的就从词库里删掉，不占位置。
多音字是注音层面的老问题。转换器如果只做字符搬运不做注音重建，那注音信息就得靠目标端自己反查，反查错了就匹配不上。高频多音词其实不多，常见的就是地名、姓氏、专业术语里那几十个。我的做法是维护一份"多音字纠正表"，格式是"词条 + 正确拼音"，转换时把这份表作为覆盖层传进去，优先级高于自动注音。这份表我积累了三年，一共不到一百条，但解决了我 90% 的多音字问题。
超长词条的处理要分两步看。第一步是判断它该不该进词库——超过二十字的"词条"基本是句子或者整段复制粘贴进来的，直接过滤，没有保留价值。第二步是判断目标端的长度上限，如果目标端只支持十几个字，那么介于两者之间的词条会被截断，截断之后可能变成一个毫无意义的短词，这种危害比直接丢弃更大。所以我宁可把上限设在目标端限制之下，主动丢弃，也不让截断发生。
5.4 常见问题速查表
| 现象 | 最可能原因 | 快速验证 | 处理办法 |
|---|---|---|---|
| 首条词条乱码 | UTF-8 BOM 未去除 | 十六进制看文件头是否 EF BB BF | 重新输出无 BOM 编码 |
| 全部词条匹配不上 | 换行符残留 | 十六进制看行尾是否多 0D | 统一输出为目标端换行符 |
| 条数明显偏少 | 解析阶段未读完整 | 对比转换报告解析条数与源端统计 | 换工具或指定正确源格式 |
| 常用词位置靠后 | 词频映射区间偏低 | 抽样看目标词频值 | 整体上调映射区间 |
| 若干净词仍无候选 | 词条超长被截断或丢弃 | 查看该词条长度 | 放宽上限或拆分词条 |
| 个别词异常靠前 | 重复叠加或特殊值 | 统计该词出现次数 | 去重并处理负值特殊标记 |
| 缩写打不出长词 | 注音信息缺失 | 用完整拼音测试能否命中 | 引入多音字纠正表重建注音 |
| 导入后界面显示 0 条 | 格式不匹配或编码不识别 | 用纯文本最小样本测试 | 切成最简格式逐项排除 |
这张表我贴在便签里放了很久，每次换设备或者帮人迁移都翻出来对着走一遍，基本能在十分钟内定位到具体环节。
6. 词库瘦身与长期维护，比转换本身更重要
6.1 十万词条怎么砍到能用的规模
很多人以为词库越大越好，实际上超过一定规模之后，词库会拖慢输入响应，还会制造大量错误候选。我手上有一份积累多年的个人词库，最初有十二万多条，导入后打字明显卡顿，候选列表里还老出现一些莫名其妙的组合。后来做了一轮瘦身，砍到两万八千条，输入体验提升非常明显。
瘦身我按四刀砍：
第一刀，按词频砍。保留词频排名前 N 的词条，剩下的丢弃。N 取多少取决于你的使用场景，日常输入两万到三万足够，专业场景可以到五万。判断依据是词频分布曲线——大多数人的词频分布是极端长尾的，前 20% 的词条覆盖了 90% 以上的实际输入。找出那条拐点，砍在拐点之后。
第二刀，按词长砍。去掉单字词条（交给系统词典）和超过十六字的词条（基本是句子）。这一刀通常能砍掉 10% 到 15%。
第三刀，按字符类型砍。去掉纯数字、纯符号、纯英文单词开头的词条。这几类在拼音输入场景下价值低，还容易污染候选。但要注意，如果你的工作涉及大量英文术语混排，第三刀要放宽，保留含英文的词条。
第四刀，去重。前面讲过，按归一化之后的字符串比对，保留词频最高的一条。
四刀砍完，再做一次候选质量回归测试——挑二十个高频词和十个术语，看第一候选是否正常。如果砍完之后某些词找不到了，说明砍过头了，把词频阈值往下调一档重来。
6.2 用版本管理做增量合并
词库这东西是持续生长的，你今天加十个术语，下周加二十个人名，如果每次都全量转换一遍，很容易把之前手工修过的地方覆盖掉。我的做法是把主词库存成一个纯文本文件，纳入版本管理，每次新增走增量合并。
具体流程是：主库文件里一行一条，格式是"词条 + 制表符 + 词频"。新增的词单独写在一个增量文件里，格式相同。合并时用一个几十行的脚本，按词条去重，词频相加并设上限，然后输出新的主库。整个过程可以提交、可以 diff、可以回滚。
这个流程最大的价值是可追溯。有一次我发现某个常用词突然跑到很后面，用 diff 一查，是某次合并时这个词在增量文件里被写成了低词频，覆盖了原来的高值。如果没有版本管理，这种问题根本查不出来。
增量合并时的词频累加策略要特别小心。如果增量文件里出现了一个已经在主库的词，累加是对的；但如果增量文件本身被重复合并了两次，词频就会翻倍。我的办法是给每次合并记录一个合并标记，合并前先检查标记，重复合并直接拒绝。
6.3 从个人词库扩到团队术语库
个人用顺手之后，很自然会想到把这套东西推到团队里——统一术语、统一缩写、统一人名写法，减少沟通成本。这件事技术上不难，难在治理。
我的经验是把词库拆成两层：基础层和个人层。基础层是所有成员都要导入的公共术语库，由一个人维护，改动走评审，版本号明确；个人层是每个人自己的词库，随意改。导入时先导基础层再导个人层，个人层的权重略高，这样个人习惯能覆盖公共规则。
公共术语库的词频设定有个技巧：不要把所有术语都设成最高权重。全部设最高，等于没有区分，术语之间互相抢位，反而谁都排不上第一。正确做法是按使用频率分档，最常用的那批给最高档，长尾的给中档，确保核心术语稳定靠前，边缘术语能出现但不干扰。
还有一个治理上的坑：术语库要定期清理，尤其是项目制团队，项目结束后相关术语就成了噪音。我一般每个季度做一次清理，把过期的术语降权或者移除，同时做一次全量回归测试。这个习惯看起来麻烦，但比重建一次词库省事得多。
7. 几个只有反复折腾才会固化的习惯
最后说几条我个人在实践中固化下来的习惯，都不算技术点，但确实省过不少事。
第一条，永远保留源文件。哪怕转换成功、导入成功、用了三个月都正常，源文件也不要删。我遇到过目标端升级后词库格式变更，需要重新转换的情况，那时候源文件就是唯一的救命稻草。
第二条，小样本先行。每次转换前，先从那十几万条里随机抽两百条跑一遍完整流程，确认无误再全量。这个动作花两分钟，能提前暴露绝大多数格式和编码问题。
第三条，参数记在文件里。我用一个纯文本文件记下每次转换用的完整命令和参数，包括为什么这么设。半年后回头再看，那些当时觉得"肯定记得住"的理由早就忘了，只留下一个数字，完全不知道为什么是 0.92 而不是 0.94。
第四条，每次迁移后手写五十个高频词做回归。这五十个词是我日常输入里频率最高的，能不能在第一候选出现，直接决定我用得舒不舒服。这个清单我一直在更新，每次换设备都拿它对一遍，出问题立刻能定位到是映射还是注音。
第五条，接受不完美。词库迁移不可能 100% 还原，总有几条词会因为编码、长度、字符集的原因丢掉。我现在的标准是：核心的两三百个词必须在，长尾的丢几条无所谓。把精力放在核心词的验证上，比追求条数完全一致要实际得多。
