Qwerty Learner 自定义词库扩展教程：1个JSON文件+1行配置，装进你的专属单词表-育师

Qwerty Learner 自定义词库扩展教程：1个JSON文件+1行配置，装进你的专属单词表

【免费下载链接】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 文件、加一条索引记录，专属单词表就能出现在词库目录里。

👥 这事适合谁做

会写 JSON、能在编辑器里保存文件就够了，不需要会前端开发。你手上有一张现成的单词表（Excel、TXT、扫描件整理稿都行）就具备开工条件；如果连仓库怎么跑起来都不熟，也可以直接按 docs/toBuildDict.md 的流程把需求提给社区，让开发者帮你导入。

📋 动手前30秒速览

要碰的东西	在哪	长什么样
词库文件	public/dicts/ 目录	一个`.json`文件，如`my_vocabulary.json`
词库 JSON 结构	同上	数组，每项含`name`（单词）、`trans`（释义数组），可选`usphone`/`ukphone`（音标）
词库索引	`src/resources/dictionary.ts`	在对应分类的数组里加一条记录
索引关键字段	同上	`id`（全局唯一）、`name`、`description`、`category`、`url`、`length`（单词数）、`language`
单词数计算	`scripts/update-dict-size.js`	跑一次脚本，自动按 JSON 实际条数回填`length`

🛠 完成扩展

词库文件放在哪

把单词表整理成 JSON 数组，每项一个单词，存到 public/dicts/ 目录下，文件名起个有意义的，比如my_vocabulary.json。最小可用的结构长这样：

[ { "name": "file", "trans": ["n. 档案, 公文箱; 文件"] }, { "name": "command", "trans": ["n. 命令; 指令"], "usphone": "kəˈmɑːnd" } ]

name和trans必填，trans是字符串数组，一条释义占一个元素
usphone、ukphone可选，写上之后练习界面才会显示美式/英式音标
单词多到不想手敲？用在线转换工具把 CSV 转成 JSON，或把源文件片段贴给大模型让它生成转换脚本，都是现成路子

让应用识别词库

词库文件放好后，应用还看不到它——因为目录页渲染的名单来自src/resources/dictionary.ts。打开这个文件，在和你词库对口的分类数组里加一条：

{ id: 'my-vocabulary', name: '我的自定义词库', description: '自制的专业词汇表', category: '其他', url: '/dicts/my_vocabulary.json', length: 100, language: 'en', languageCategory: 'en', }

id必须和文件里其他条目不重名，重复了以后排查问题会很麻烦
category先翻一遍现有分类再填，挂错 tab 等于白加
length可以先手填占位，跑一次node scripts/update-dict-size.js，它会扫描 public/dicts/ 下所有 JSON，把length改成真实条数

🔍 确认生效

改完别急着关编辑器，yarn dev起本地服务后对着这三条自查：

词库目录页能看到你加的卡片，且挂在正确的分类 tab 下
点开词库详情，单词和释义正常渲染——JSON 只要漏一个引号，这里就会加载失败，所以这一步能抓住大部分格式错误
卡片上显示的词数和 JSON 实际条数一致，对不上就重跑一次scripts/update-dict-size.js

⚠️ 常见坑

现象：词库目录里死活看不到新词库 →原因：dictionary.ts里索引没加，或category填了不存在的分类名 →处理：对照同文件里的其他条目逐字段核对一遍
现象：点开词库报 404 或页面空白 →原因：url和 public/dicts/ 下的文件名对不上，大小写也算对不上 →处理：确认url写成/dicts/文件名.json，并与磁盘上的文件逐字符比对
现象：卡片词数显示是错的 →原因：length手填后没更新 →处理：跑node scripts/update-dict-size.js自动回填
现象：想分享词库但不知从哪入手 →原因：社区贡献走的是 Issue/PR 流程，不是直接发文件 →处理：按 docs/toBuildDict.md 的说明，发起 Dictionary Request 或提交 PR