Qwerty Learner 词典导入完全指南：从零搭好你的个性化打字练习词库-开发者社区

Qwerty Learner 词典导入完全指南：从零搭好你的个性化打字练习词库

【免费下载链接】qwerty-learner为键盘工作者设计的单词记忆与英语肌肉记忆锻炼软件 / Words learning and English muscle memory training software designed for keyboard workers项目地址: https://gitcode.com/GitHub_Trending/qw/qwerty-learner

Qwerty Learner 是一款为键盘工作者设计的单词记忆与肌肉记忆训练软件，而 Qwerty Learner 词典导入功能让你可以把任意单词整理成 JSON 词库装进软件里，让打字练习用的词完全由你说了算。本文用四步讲清从零到跑通的完整流程。

为什么值得为你的词库花点心思

先问自己一个问题：内置词库够用吗？Qwerty Learner 已经内置了四六级、考研、托福雅思、编程语言 API 等大量词库，程序员练习工作高频词的场景开箱即用：

但你的真实需求未必被覆盖——你工作中反复出现的专业术语、孩子教材里的单元词、你反复打错的薄弱词，这些只有你自己能定义。而把「背单词」和「敲键盘」绑在一起，恰恰是这个软件最锋利的地方：词是你选的，练的也是你最需要的，枯燥的死记硬背自然就被干掉了。

如何导入自定义词典：从写词库到验证的四步流程

下面每一步先说清楚它解决什么问题，跟着走即可。

第一步：写一份合格的 JSON 词库

这一步解决「词库长什么样」。Qwerty Learner 的词典就是一个 JSON 数组，每个词条只需要两个必填字段：

[ { "name": "example", "trans": ["示例", "范例"] } ]

name：单词本身，字符串
trans：释义，数组形式，一个单词放多个义项也没问题

两个细节提前交代：文件用UTF-8 编码保存（后面避坑环节会再强调），文件名建议用词典名加.json后缀。如果你手头是 CSV、Excel 之类的源数据，可以用在线转换工具或者让 AI 帮你写个转换脚本，内容不多时手动整理也完全可行。

词量上有个甜区：单本词典 1000~3000 词。太少撑不起一次完整练习，太多会让单轮练习拖得太长，练习节奏反而变差。

第二步：词库放哪里

这一步解决「文件落点」。把处理好的词库放进 public/dicts/ 目录，和现有的数百本词库并排存放即可。路径对了，后面注册索引时url字段才好指。

第三步：在词典索引里登记你的新词库

这一步解决「让软件认识你的词库」。光把文件放进public/dicts/还不够，词典列表是由 src/resources/dictionary.ts 这个索引文件驱动的，你需要在这里补一条登记信息：

{ id: "my-dict", name: "我的专属词库", description: "自建练习词库", category: "英语学习", url: "/dicts/my-dict.json", length: 1200, language: "en", languageCategory: "en", }

字段含义一句话版：id必须全局唯一；name/description是用户看到的名字和描述；category选一个现有分类，保证词库目录清爽好找；url指向你在第二步放的文件；length是词数，可以用 scripts/update-dict-size.js 脚本自动计算，不用手数。

第四步：本地跑起来验证

这一步解决「提交前确认导入成功」。本地部署只需三步：

git clone https://gitcode.com/GitHub_Trending/qw/qwerty-learner cd qwerty-learner && yarn install && yarn dev

然后打开http://localhost:5173，在词典列表里找到你新登记的词库，点开试打几个词。能正常练习，说明整条链路已经通了。

做错会怎样：三个最常见的导入翻车点

走到这一步，大概率你会在某个地方被卡住。对照下面三条自查，基本能覆盖 90% 的问题。

词库放了却不显示

最常见的原因有三个，按出现概率排序：忘了在dictionary.ts里登记索引、JSON 不是数组而是单个对象、url路径和实际文件名对不上。先用浏览器或文本编辑器打开你的 JSON，确认整体是一个数组，再逐字段核对索引里的url。

释义显示乱码

九成是编码问题。确认词库文件以UTF-8保存（无 BOM 最佳），如果源文件来自 Windows 记事本或某些工具导出，建议重新另存一次再导入。

词条显示异常或加载报错

检查每个词条是否都带了name和trans两个字段；trans里如果出现引号等特殊字符，记得正确转义。拿不准时挑出单个词条做最小化测试，定位到具体那条再修。

让词库长期用起来：练习、分享与系列化

词库跑通只是开始，怎么让它持续产生价值？

让词库真正参与练习流程

导入后你会发现，练习结束后软件支持默写模式，会要求你把刚练过的词重新默写一遍，把「打得出来」和「记得住」两件事一起巩固：

再配合音标显示、发音播放和速度/正确率统计，一本你自己定的词库就变成了一条完整的训练闭环。

把你的词库变成社区公共资源

词库打磨好了，不妨让它服务更多人，两条路都可以：

会一点开发：按官方文档 docs/toBuildDict.md 的流程提交 PR，审核通过后你的词库就会随版本发布给所有用户
不想写代码：直接以「Dictionary Request」开头提一个 Issue，描述需求并附上词典来源，社区开发者会帮你完成导入；没有编程基础也可以在社区群里提需求

反过来也一样：别人贡献的专业词库（编程语言 API、考试高频词等）你都可以直接取用。更进一步，可以围绕自己的学习节奏建一套词典系列——按难度分级、按薄弱专项拆分、按兴趣主题组织，让词库管理跟着你的计划走。