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 是一款把英语单词记忆和键盘肌肉记忆训练结合的开源工具。本文按你的真实排障旅程组织：从装不上、跑不起来，到用着不顺、数据丢了、显示错乱，每个问题只给一个最可能的原因和能直接照做的步骤，照着修就行。

症状速查表

你看到的现象	一句话解法
yarn install 卡住或报错	依赖安装失败多因网络，换 npmmirror 镜像重装
yarn start 后页面空白	5173 端口被占用，改 vite.config.ts 里的端口
选完词库一直转圈	确认 public/dicts/ 下有对应 JSON，大词库耐心等几秒
自定义词库提示格式错误	条目必须是 name/trans 结构，对照 docs/toBuildDict.md
打错一个字母后卡住不让过	设计如此：删掉重打；跳不过就换一本词库
点发音没有声音	发音依赖在线音频，网络不稳，点发音图标重试
清完缓存练习记录没了	数据存在浏览器 IndexedDB，养成导出备份的习惯
手机上看界面错位	视口小于 600px 才会自动切到 /mobile 页面

跑不起来：安装与启动

yarn install 卡住或报错

现象：执行yarn install后长时间无输出，或直接报网络错误（典型的依赖安装失败）。

最可能的原因：默认 registry 网络不通畅，依赖包拉不下来。

切换国内镜像源：yarn config set registry https://registry.npmmirror.com
删除项目里的node_modules目录
重新执行yarn install

📌 预防：先确认node -v是 LTS 版本；Windows 用户可运行 scripts/pre-check.ps1，macOS/Linux 用户运行scripts/pre-check.sh，脚本会自动检查并补装 Node、git、yarn。

yarn start 后页面空白

现象：终端里 Vite 正常跑起来了，浏览器打开却是空白或打不开。

最可能的原因：默认端口 5173 已被其他进程占用。

看终端提示里实际监听的端口
在vite.config.ts的返回对象中加上server: { port: 5174 }
重新执行yarn start，访问http://localhost:5174

📌 预防：启动前留意终端输出的 Local 地址，别只盯着 5173。

用起来不顺：词库、发音与错词

选完词库一直转圈

现象：在词库页选中某本词库后，加载指示器长时间不动。

最可能的原因：本地词库文件缺失或太大——内置词库都在 public/dicts/ 目录，自部署时构建产物里若漏掉该目录就会加载失败。

打开public/dicts/，确认对应词库的 JSON 文件存在且非空
若是你自己部署的，重新构建并部署一次
若在官方站点访问，换个网络稳定的环境刷新页面

📌 预防：GRE、IELTS 这类大词库首屏加载需要几秒，属正常现象，别急着判定为故障。

自定义词库导入报格式错误

现象：把自己的词库文件放进词库目录后，选不中或解析报错。

最可能的原因：条目字段不符合约定结构。词库文件是词典名.json，内容应为：

[ { "name": "file", "trans": ["n. 档案,公文箱,[计算机] 文件"] } ]

用任意 JSON 校验工具确认文件本身是合法 JSON
把每个条目改成name（单词）+trans（释义数组）两个字段
保存为public/dicts/下的词典名.json

📌 预防：转换前先把源文件备份，详细格式说明见 docs/toBuildDict.md。

点发音没有声音

现象：点击单词旁的发音图标后完全没声音，音标正常显示。

最可能的原因：发音走在线音频服务，当前网络拉取音频失败。

确认系统音量没静音、浏览器未拦截该站点声音
切换稳定网络后，再点一次发音图标手动触发
把 Chrome 或 Edge 升级到最新版后重试

📌 预防：发音图标逻辑在src/components/WordPronunciationIcon/，若长期无声且网络正常，多半是浏览器兼容问题。

打错一个字母后卡住不让过

现象：单词输错后没法继续往下走，感觉"卡死"了。

最可能的原因：这是刻意设计——错词必须删掉重打完整拼写，防止形成错误的肌肉记忆（详见 README.md 的设计思想）。

删掉已输入的错误字符，从头完整重打这个词
确实记不清拼写时，结束当前章节练习
回词库页换一本词库或换一个章节继续

📌 预防：章节完成后会提示是否默写本章，用默写模式巩固没把握的词。

数据不对劲：记录与统计

清完缓存练习记录没了

现象：浏览器清过缓存或站点数据后，历史练习记录全部消失。

最可能的原因：记录存放在浏览器的 IndexedDB 里（Dexie 封装），清站点数据等于连库一起删了。

在练习页设置面板的数据区，把全部记录导出为.gz备份文件
养成习惯：每次清缓存、换电脑前先导出
若已丢失，用之前的备份文件通过同一入口导入恢复

📌 预防：数据导出/导入的实现见src/utils/db/data-export.ts，导入会先清空现有数据再写入，备份永远是"最近一次"才最保险。

统计数字和实际练的对不上

现象：分析页的速度、正确率或字数统计与自己的练习量明显不符。

最可能的原因：用旧备份导入过数据——导入逻辑会先清空数据表再写入，新记录被旧记录覆盖了。

先导出当前数据留底
在数据区导入最近一次的正确备份
刷新页面，重新核对分析页数字

📌 预防：换机器或重置浏览器前，固定走"导出→换环境→导入"流程，别跳过导出。

显示不对劲：移动端与主题

手机浏览器里界面错位

现象：手机上打开首页，桌面版布局被挤成一团（移动端显示错乱的典型）。

最可能的原因：页面只在视口宽度小于 600px 时才切换到/mobile移动页面，缓存的旧页面没触发这个跳转。

用手机浏览器直接打开站点首页，让它自动跳转到/mobile
想在电脑上预览移动端，把浏览器窗口拖到 600px 以内
按 Ctrl+Shift+R 强制刷新一次

📌 预防：移动端页面代码在src/pages/Mobile/，路由切换逻辑在src/index.tsx，若你改了部署路径（如 GitHub Pages 子路径），basename 需保持一致。

深色模式切换没反应

现象：点击主题切换按钮后界面毫无变化，或刷新后又跳回亮色。

最可能的原因：旧缓存里的样式文件没更新，主题类名没生效——主题实现就是在<html>上挂dark类（见src/index.tsx）。

按 Ctrl+Shift+R 强制刷新页面
在浏览器设置里清除该站点的缓存后重新访问
换一个最新版 Chrome 或 Edge 打开验证

📌 预防：会往页面注入深色主题的浏览器扩展和站内主题冲突，排查时可先在无痕窗口验证。

想更进一步：插件与自托管

VSCode 插件打开是空白

现象：装了 Qwerty Learner 的 VSCode 插件，面板打开后一片空白。

最可能的原因：插件内嵌的本地服务没起来，常见于 VSCode 版本过旧或插件安装不完整。

确认 VSCode 版本 ≥ 1.60.0
在扩展列表里卸载插件，重新安装
完全重启 VSCode，再打开插件面板

📌 预防：插件发布在市场（插件名 Kaiyi.qwerty-learner），源码在独立的插件仓库中，仍打不开就去那边提 Issue。

Docker 部署报错服务起不来

现象：执行 docker-compose 后容器反复退出，端口访问不到（典型的 Docker 部署报错）。

最可能的原因：docker-compose.yaml 里映射的宿主机端口 8990 已被占用。

启动后立刻docker-compose logs -f看具体报错
确认本机 8990 端口空闲，被占则把 ports 改为'8080:5173'
修改后docker-compose up -d重启容器

docker-compose up -d docker-compose logs -f

📌 预防：镜像内是 Node 20 构建 + Nginx 托管，容器内固定监听 5173，只需要改冒号左边；想纯本地自托管不跑 Docker，也可以 clone 仓库https://gitcode.com/GitHub_Trending/qw/qwerty-learner后执行yarn install、yarn start直接跑开发服务器。