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中途报网络或版本错误Node 环境缺失或包下载超时第一节依赖安装启动后浏览器打不开或一片白屏依赖没装好或缓存残留第二节启动5173 端口被占用启动直接报错端口冲突第二节启动选完词库一直转圈大词库文件下载慢或文件缺失第三节词库点击发音没有声音发音依赖在线接口网络受限第四节练习打错单词后好像被卡住这是刻意设计不是故障第四节练习换浏览器或清完缓存记录没了数据只存在本机浏览器里第五节数据导入自定义词库提示格式错误JSON 结构与字段不符第五节数据装不起来的阶段依赖与镜像怎么查yarn install报网络错误先查环境再换镜像症状你执行yarn install时中途弹出网络超时、403 或引擎版本不兼容的报错。原因多半是 Node、Git、Yarn 三件套有缺失或从默认镜像拉包超时。处理跑一下项目自带的预检脚本缺什么它会告诉你——Windows 执行scripts/pre-check.ps1Mac 执行scripts/pre-check.sh。确认环境齐全后把镜像切到国内源再重装一次yarn config set registry https://registry.npmmirror.com yarn install预防第一次搭建本地环境时就把镜像源配好不要等装到一半才换。git clone后跑不起来必须走源码安装症状你把仓库下载解压后直接yarn start启动就报错。原因项目构建依赖 git 提交信息脱离 git 仓库的压缩包缺了这部分跑不起来。处理删掉解压目录改用 clone 获取完整仓库git clone https://gitcode.com/GitHub_Trending/qw/qwerty-learner预防本地开发一律用 git clone不要用网页上的压缩包下载。跑起来不对劲的阶段启动、端口与白屏5173 端口被占用换端口启动症状yarn start后终端提示 5173 端口已被占用浏览器打不开页面。原因电脑上已经有别的开发服务或上一次没关干净的 Vite占着这个端口。处理不用改任何配置文件启动时直接追加端口参数即可yarn start -- --port 5174预防同一台机器跑多个前端项目时习惯性给每个项目指定不同端口。启动后一片白屏缓存与残留进程症状终端没有报错但浏览器打开后是一片空白。原因依赖没有装完整或浏览器里残留了旧的站点数据。处理先确认终端输出里有正常的 Vite 启动地址然后清除该站点的浏览器数据按 CtrlShiftR 强制刷新。还不行就停掉所有 Vite 进程重新yarn start。预防升级或改动本地环境后先清站点数据再访问能避开大半白屏问题。手机打开变成推广页其实是正常行为症状你在手机浏览器访问本地或线上地址看到的不是练习界面而是介绍页。原因项目对窗口宽度 600px 以下会自动切到移动端页面这是设计如此。处理移动端页面目前以引导介绍为主练习功能请在桌面浏览器里用把窗口拉宽到 600px 以上就会回到练习界面。预防需要边看手机边练的场景当前版本暂不支持直接在电脑上练习即可。用出毛病的阶段词库与练习手感选完词库一直转圈大词库别催它症状你在词库列表里选中一个词库后界面长时间停在加载中。原因词库是放在public/dicts/目录里的 JSON 文件GRE、IELTS 这类大词库体积不小弱网下要等几秒。处理先等 3~5 秒确认对应 JSON 文件在public/dicts/目录里存在且能正常解析。本地开发时文件缺失会导致一直转圈补齐文件再刷新即可。预防弱网环境下先打开小词库如 CET-4试水确认正常后再切大词库。打错单词被要求重打这不是故障症状你打错一个单词后感觉软件卡住了不让你进入下一个词。原因这是刻意的练习设计——避免错误肌肉记忆被强化所以单词必须重打到正确为止。处理直接重新输入一遍实在不想纠结这个词点击单词上方的跳过该词按钮就能过。预防把它当成刻意训练的一环接受下来跳过功能留给真正生僻的词。点击发音没有声音在线音源被网络挡住了症状你点击单词旁的发音图标始终没有声音。原因发音走的是有道词典的在线音源网络受限或浏览器拦了音频播放就会无声。处理检查系统音量确认网络能访问外网到设置里看一眼发音开关与音量换 Chrome 或 Edge 最新版再试。预防练习前先把发音设置过一遍别在弱网环境依赖发音功能。数据出问题的阶段记录与自定义词库换设备后练习记录不见了数据只在本机症状你换了浏览器或清过缓存之前的练习记录、错词本全都没了。原因练习记录存在浏览器的 IndexedDB 里只跟本机 本浏览器绑定清站点数据就等于删记录。处理无法找回被清掉的数据。养成习惯重要阶段用页面自带的导出功能把记录存成文件。云同步功能当前版本暂不支持。预防换浏览器前、清缓存前先导出一份记录备份。导入自定义词库报格式错误字段要对齐症状你把自制词库放进项目词库列表里却没有它或加载时直接报错。原因文件格式不符合约定——每条必须带name单词和trans释义数组两个字段。处理把 JSON 改成下方结构放入public/dicts/目录并在src/resources/dictionary.ts里补一条索引id 必须唯一重启开发服务即可看到[ { name: example, trans: [n. 例子] } ]预防动手前读一遍 docs/toBuildDict.md格式问题几乎都写在里面。找不到答案时的求助通道问题反馈到项目仓库的 Issue 区提交附上浏览器控制台输出F12 打开和截图方便维护者复现社区求助词库需求、使用疑问都可以在 Issue 里发起或加入项目社区群动手修 Bug贡献流程详见 docs/CONTRIBUTING.md欢迎提交 PR。小贴士遇到任何怪异表现先做三件事——重启浏览器、强制刷新、清一次站点数据。大部分玄学问题都是缓存残留别急着怀疑软件本身。【免费下载链接】qwerty-learner为键盘工作者设计的单词记忆与英语肌肉记忆锻炼软件 / Words learning and English muscle memory training software designed for keyboard workers项目地址: https://gitcode.com/GitHub_Trending/qw/qwerty-learner创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考