1. 项目概述为什么要把打字练习从 VSCode 搬到独立桌面应用先交代一下背景。我大概两年前开始用 VSCode 写代码后来养成了一个挺有争议的习惯——在编辑器里直接练打字。当时用的是某个第三方打字插件在 VSCode 的命令面板里输入快捷键呼出一个打字面板然后开始敲英文单词。平心而论那个插件的基本功能是能用的词库也不算差击键判定、速度统计都有。但用着用着问题就来了VSCode 本身是个编辑器它的核心任务是给你写代码插件运行在编辑器的渲染进程里稍微做点动画就得跟语言服务、代码高亮、智能提示抢 CPU。我经常开着两三个项目窗口再加上一个打字插件一敲快一点编辑器就开始掉帧。更难受的是插件的 UI 受限于 VSCode 的布局体系想做一套像样的排行榜、热力图、练习记录统计怎么放都觉得别扭。后来我干脆决定独立做一个打字练习应用技术栈用的是 Electron Vue 3。这个决定还挺有意思的——VSCode 本身就是用 Electron 写的也就是说我等于是在做一个“VSCode 同款技术底座”的独立应用然后把原来寄居在编辑器里的插件能力迁移过去。这篇文章就把这次架构改造的过程完整记录下来包括为什么选 Electron、进程模型怎么设计、打字判定的核心逻辑怎么写、数据怎么持久化、最后怎么打包分发。对于想用 Electron 做事、或者想把某个 Web 小工具改造成桌面应用的开发者这篇应该能少走不少弯路。2. 架构改造的整体设计思路2.1 从插件宿主到主进程 渲染进程消息通道的重新设计VSCode 插件其实是一个运行在宿主进程里的 JavaScript 模块它通过 VSCode 提供的 extension API 访问编辑器状态、注册命令、创建 Webview。说白了插件不需要关心窗口生命周期、菜单注册、文件读写这些事因为宿主已经把这些能力封装好了。但独立应用不一样Electron 应用里你面对的是两套进程主进程负责窗口管理、系统集成、文件访问渲染进程负责 UI 渲染和业务逻辑。两者之间靠 IPC 通信说白了就是通过ipcMain和ipcRenderer来回传消息。这个差异是整个架构改造里最重要的一点。打字插件在 VSCode 里词库文件存在哪存在工作区目录里通过workspace.fs读写。独立应用里词库文件应该存在用户数据目录下通过 Electron 主进程里的fs模块读写。插件要显示打字统计直接在 Webview 里渲染独立应用里打字数据要落盘就得走“渲染进程发起请求 → 主进程写文件 → 渲染进程收到确认”这条路。我在设计初期就把所有涉及文件系统的操作统一封装成了一组 IPC 事件比如dictionary:load、record:save、record:read渲染进程永远不直接碰 Node API只发消息和收结果。这个模式我在工程上叫“渲染进程哑终端”——UI 只负责展示和交互所有真正的 IO 都在主进程那边完成。2.2 为什么选 Electron Vue 3技术栈取舍技术选型上其实没有太多悬念。Electron 最大的优势是我可以把 Web 技术栈直接拿来用Vue 3 的响应式系统和组件化开发对打字游戏这种强交互应用来说很合适。打字游戏本质上是一个高频状态更新的场景——击键、光标位置、计时、进度、正确率这些状态一秒要刷新好几次。Vue 3 的 Composition API 配合ref和computed处理这种细粒度状态更新非常顺手不像以前用 jQuery 手动操作 DOM 那样容易漏更新也不像 React 那样需要额外操心重渲染性能。而 Electron 的另外一层价值在于VSCode 本身就是它做出来的东西。这意味着 Electron 在代码编辑、多窗口管理、系统托盘、自定义菜单这些桌面场景下是经过大规模验证的不是说那种只能做演示小工具的轮子。我最终确定的方案是 Electron 30 Vue 3.4 Vite 5工具链上electron-vite这个打包插件把主进程、预加载脚本、渲染进程三部分的构建都串起来了开发体验比早期的electron-forge或者手动配置 Webpack 舒服不少。你可能想问为什么不用 TauriTauri 确实更轻打包产物更小内存占用也更低。但我当时评估下来Tauri 的 Rust 后端对我这个场景没有额外优势打字游戏不需要调用底层系统能力反而 Electron 的生态成熟度让我更放心什么自动更新、崩溃上报、原生菜单这些都有现成的库。桌面应用开发有一个很原始的道理你不想在发布前最后一周去跟一个没人用的打包插件搏斗选择一个文档最全、社区最大、案例最多的方案本身就是一种工程决策。2.3 目录结构与工程初始化架构改造不只是一堆抽象讨论落地到目录上我推荐这样组织 Electron Vue 3 的项目typing-trainer/ ├── src/ │ ├── main/ # 主进程代码 │ │ ├── index.ts # 入口创建窗口 │ │ ├── ipc.ts # 注册所有 IPC handler │ │ └── storage.ts # 文件读写、数据存储 │ ├── preload/ # 预加载脚本 │ │ └── index.ts # 通过 contextBridge 暴露安全 API │ └── renderer/ # 渲染进程Vue 3 应用 │ ├── index.html │ ├── src/ │ │ ├── main.ts │ │ ├── App.vue │ │ ├── components/ # 打字面板、统计卡片、词库管理 │ │ ├── composables/ # useTypingEngine、useTimer、useStats │ │ └── stores/ # Pinia 状态管理 │ └── assets/ ├── resources/ # 图标、安装包资源 ├── electron.vite.config.ts └── package.json初始化工程我用的是npm create quick-start/electron这是 electron-vite 官方推荐的脚手架命令会自动生成主进程、预加载脚本和渲染进程三个入口的模板。生成完之后第一件事就是把默认模板里的contextIsolation: false改成true把nodeIntegration改成false。这两个配置现在算是 Electron 安全基线了——渲染进程不直接拥有 Node 能力所有需要系统能力的操作必须通过预加载脚本暴露的 API 走。打字应用虽然不像网银那么敏感但养成好的安全习惯没有坏处万一以后你想往里面加云同步功能或者从网上下载词库这个基础就打好了。3. 核心功能模块拆解与实现3.1 打字游戏的核心循环输入判定与进度追踪打字游戏的核心说白了就是一个“键位事件 → 字符比对 → 状态推进”的循环。用户在键盘上按下字符程序判断这个字符是否跟当前目标文本的下一个字符一致一致就前进一格不一致就记录一次错误。听起来很简单但实现细节里至少有四个坑。第一个坑是全局键盘监听。现在桌面应用里按键盘是很常见的需求但不能直接在渲染进程里window.addEventListener(keydown)就完事因为渲染进程获取焦点的时候才能收到键盘事件万一用户点击了其他地方焦点跑了打字就没反应。我最终是在渲染进程里监听keydown但在窗口失焦的时候自动暂停打字并且用window.addEventListener(focus/blur)做状态切换。这个体验很像游戏里的暂停——你切走再回来计时不会虚增成绩更真实。第二个坑是输入法的干扰。中文输入法在打字过程中会拦截字母按键导致keydown事件里的key值变成Process这时候直接去比对字符必然出错。我的处理是打字窗口强制使用英文输入模式在启动时用compositionstart和compositionend事件做一次拦截如果在输入过程中出现isComposing true的状态直接忽略该轮输入并给出提示。这个方法不能 100% 解决系统层面的输入法拦截但实测可以规避九成以上的问题。第三个坑是特殊字符的判定。英文练习文本里经常出现空格、逗号、句号、引号、连字符这些符号的key值跟char值之间不是一一对应的。比如按Shift 8得到星号*key的值是*这个没问题但是按Shift ,得到key的值有时候是取决于键盘布局。我统一用e.key拿到的值做比对因为它代表的是“实际输入的那个字符”而不是“物理按键”。物理按键那套e.code是给游戏用的打字练习得按实际字符来。第四个坑是退格键的定位。退格能否使用关系到打字游戏的难度和公平性。我设计的方案是退格键允许回退但回退到已包含错误字符的位置时错误记录不会消除只允许重新输入正确字符直到越过那个错误点才能继续前进。这样既保留了退格的容错能力又不会让错字统计失真。实现上我用了一个caretIndex当前光标位置和一个errorMap记录每个位置的错误次数每次击键先更新errorMap再移动caretIndex通过 Vue 3 的响应式绑定来驱动 UI 刷新。这个核心循环我封装成了一个独立的 Composable叫useTypingEngine它的核心数据结构是这样interface TypingEngineState { targetText: string[]; // 目标字符数组 inputHistory: string[]; // 用户实际输入数组 caretIndex: number; // 当前位置 errorMap: Recordnumber, number; // 每个位置的错误次数 startTime: number | null; endTime: number | null; isFinished: boolean; }每轮击键的处理流程在一个handleKeyInput(key: string)方法里逻辑大致是比对当前字符、更新errorMap、推进或停滞caretIndex、检查是否完成。然后用一个currentChar的 computed 属性来给 UI 提供高亮信息。整体上这个设计可以保证打字判定逻辑跟 UI 完全解耦未来要加自定义键盘布局、支持多语言、甚至接入语音输入都只需要扩展handleKeyInput内部的分支不用动组件。3.2 词库系统内置词库与自定义词库打字练习没有好的词库就像射击游戏没有好的地图很快就会腻。所以词库系统是这次独立应用相比 VSCode 插件提升最大的模块之一。我把词库设计成了三层结构第一层是内置词库包括英语基础 500 词、程序员高频词汇 300 词、英文段落练习改编自开源短文集和数字符号专项。每个词库在应用里就是一个 JSON 文件结构是{ id: english-500, name: 英语高频 500 词, type: word, content: [apple, banana, ...] }。播放的时候从content里随机提取一段组成目标文本词库条目越多每次练习的随机性就越大。第二层是用户自定义词库。这里我用了一个比较有意思的设计词库文件放在用户数据目录下的dictionaries/文件夹里用户可以在应用界面里点击“导入词库”选择.txt文件每行一个词或一句话。主进程读这个文件解析成词库 JSON然后存到dictionaries/目录里下次启动时自动加载。这样做的理由是很多英语学习者会整理自己的生词本直接导入比在应用里手敲要高效得多。第三层是练习历史记录。每次完成一篇打字练习应用会保存一条记录包含词库 ID、目标文本、用时、总击键数、错误数、WPM、精度。这个数据存在一个records.json文件里渲染进程通过 IPC 调用record:list来读取然后渲染成历史列表和简单的成绩趋势图。趋势图我一开始想自己用 Canvas 画后来觉得没必要直接用一个轻量的 SVG 折线图组件就搞定了数据量不大不需要引入 Chart.js。内置词库的管理在架构上有一个值得一提的点内置词库在安装目录里resources/dictionaries自定义词库在用户目录里app.getPath(userData)/dictionaries。渲染进程请求加载所有词库时主进程会同时读取两个目录然后合并返回。这样应用升级时内置词库可以被覆盖更新用户的词库却不会丢。这是个非常小的细节但很多人做 Electron 应用容易把用户数据和程序数据混在一起升级时数据就没了教训很惨痛。3.3 计时与统计WPM/精度计算打字游戏里最激动人心的是最后那个成绩数字WPMWords Per Minute每分钟单词数和精度。 WPM 的计算公式业界其实有几种不同流派最常用的是“标准单词”算法一个标准单词等于 5 个字符包括空格。所以 WPM 正确击键数 / 5 / 总分钟数。具体到我的实现里正确击键数怎么算不是“用户总共打了多少字符而其中对的那些”而是“目标文本总字符数减去错误期间额外的击键数”。一开始我直接用targetText.length / 5 / minutes但这样退格后的重打就等于白费力气虽然从“完成文本”角度来看是合理的但从“真实打字水平”来看不太公平。后来我改成统计“净正确击键数”——用户在正确位置上的击键次数。也就是说每个位置首次输入正确算 1 个正确击键后续因为错误回退再打对的都算额外击键不计入分子。精度 净正确击键数 / 总击键数 * 100%。计时方面有一个特别容易踩的坑用户点击“开始”之后什么时候启动计时器最合理的设计是“首键启动”。用户点开始进入准备界面显示目标文本第一个按键落下的瞬间才开始计时。如果你在用户点“开始”的时候就计时那用户阅读文本、调整姿势的几秒钟都会被算进去成绩完全没有意义。我在useTypingEngine里专门维护了一个startTime初始为null第一次按键时才赋值Date.now()这样可以保证 WPM 反映的是真实打字速度。4. 架构改造的关键环节4.1 进程模型改造从插件 API 到 IPC 通信前面提到 VSCode 插件可以直接用 extension API 来操作文件、显示弹窗但独立应用必须自己处理进程间通信。这其实是架构改造中最需要耐心的环节。Electron 的 IPC 通信有一个很反直觉的坑ipcMain.on和ipcRenderer.send是单向的、异步的但如果你在主进程里想给渲染进程推送数据比如词库自动更新了不能通过同一个事件的回参来完成而是要调event.sender.send再发一个新事件。我在实际开发中统一用了ipcRenderer.invoke和ipcMain.handle这套 request/response 模式渲染进程调用invoke发送请求主进程的handle返回一个 Promise渲染进程拿到结果后await。这套模式比sendon的回调方式更简洁代码可读性高很多而且天然支持异步处理。主进程侧我建议把所有 IPC handler 集中注册在一个文件里而不是散落在各个模块中。我在src/main/ipc.ts中写了统一注册函数每个 handler 都有固定的注册模式校验参数、调用存储模块、返回结构化结果。结构化结果统一成{ code: 0, data: X }或者{ code: -1, message: 错误描述 }。这个统一格式让我在调试时面对几百个 IPC 调用也能快速定位问题。预加载脚本是渲染进程和主进程之间的安全桥梁。我通过contextBridge.exposeInMainWorld暴露一个window.api对象里面只包含白名单上的方法比如loadDictionaries()、loadRecords()、saveRecord(record)。渲染进程不直接 importelectron而是通过window.api调用。这样即使渲染进程被注入恶意代码攻击面也仅限于这几个白名单方法不会直接拿到fs或者shell这种危险权限。打字应用虽然不涉及严肃数据但这个架构习惯是从更严谨的项目里带过来的属于白捡的安全保障。4.2 数据持久化从工作区设置到本地存储VSCode 插件的数据持久化靠workspaceState和globalState说白了一个是项目级 key-value一个是用户级 key-value。独立应用里没有这套现成机制得自己设计存储层。我的存储策略分两级普通配置窗口大小、主题、音效开关、默认词库 ID用 JSON 文件存到userData/config.json练习记录用 JSON 数组存到userData/records.json词库数据则是独立文件存到userData/dictionaries/目录。选 JSON 而非 SQLite 的原因很简单——数据量太小用数据库属于杀鸡用牛刀。等到记录超过几千条再考虑迁移到 SQLite届时只需要改storage.ts一个模块的内部实现IPC 接口完全不用动。这里不得不提到文件写入原子性的问题。如果程序在写入records.json的过程中崩溃文件可能损坏所有记录就没了。我的解决方案是“临时文件 重命名”先把数据写入records.json.tmp写完关闭文件句柄再用fs.renameSync替换掉旧文件。rename在同一个文件系统内是原子操作不会出现半写状态。这个技巧在处理小规模数据持久化时非常实用成本极低但能避免一次灾难性数据丢失。4.3 窗口、菜单与系统集成独立应用相比 VSCode 插件在系统集成上多了很多自由度也多了很多事。窗口这块我采用了比较克制的设计主窗口固定 1000x700最小 800x600关闭时保存窗口位置和大小下次启动恢复。应用启动时先显示一个简单的启动画面splash screen等 Vue 应用加载完再显示主窗口这个细节虽然是锦上添花但给用户的第一印象完全不一样。菜单方面排除了默认菜单之后自定义了一套精简菜单包括文件打开词库目录、退出、练习重新开始、随机换一组、主题浅色、深色、跟随系统、帮助关于、查看文档。取消了所有代码编辑器相关的菜单项因为打字应用用不到。最后在 Windows 和 macOS 的差异上也做了适配比如 macOS 的第一个菜单必须是应用名菜单关闭窗口按钮的行为在当前平台也不一样这些逻辑用process.platform判断就行但一定要测一遍两个平台。还有一个很有用的集成是系统托盘。我加了一个托盘图标右键菜单可以快速开始练习、暂停练习、显示/隐藏窗口。打字练到一半想切换到浏览器查东西窗口最小化到托盘不碍事要回来的时候一键恢复。这个功能在 VSCode 插件里是完全做不到的算是独立应用带来的体验提升。有一点要注意托盘图标在 macOS 上建议用 16x16 的模板图片在 Windows 上建议用 ico直接塞一张 png 放大容易糊。5. 打包与分发5.1 electron-builder 配置要点打包分发是 Electron 应用绕不开的环节。我用的是electron-builder它跟 electron-vite 配合得不错。打包配置放在electron-builder.yml里几个关键点值得单独说明。第一应用图标。Windows 需要.icomacOS 需要.icnsLinux 可以用.png。如果只做了 pngelectron-builder 也能自动生成但效果一般。我直接用了一套开源的打字图标素材用icon-gen工具转换成了对应的格式。注意图标文件不要放 src 里要放在resources/目录下并在electron-builder.yml里指定路径。第二文件打包范围。用files字段明确打包哪些文件避免把node_modules里用不到的依赖塞进去。electron-vite 构建出来的out/目录是最终要打包的所有代码所以files一般写成覆盖out/**/*和resources/**/*即可。依赖方面通过npm安装的纯 JS 库如果只在渲染进程里用可以不放进dependencies而是放进devDependencies这样 electron-builder 在打包时不会把它们视为生产依赖。打字应用的渲染进程依赖只有vue、pinia主进程几乎没有第三方运行时依赖最后产物体积能控制在 100MB 左右Electron 运行时占了主要部分这个数字对 Electron 应用来说算正常偏瘦。第三自动更新。一开始我想接入electron-updater但打字应用的用户量短期内不大自动更新涉及服务器部署、签名验证工作量不可小觑。权衡之后做了一个很朴素的版本检查启动时从 GitHub Releases 拉最新版本号跟当前版本对比有新版就在界面上提示用户去下载。等以后用户量大了再考虑 electron-updater 的完整方案。小项目用渐进式方案不做过度设计。5.2 体积优化与性能调优Electron 应用的性能问题九成出在渲染进程。打字游戏对动画流畅度要求不算特别高但每秒 60 帧的终端反馈是必须的——打字的时候字符高亮要跟着指尖走卡顿会直接影响练习体验。我的性能优化主要做了三件事。第一列表渲染优化。目标文本按字符拆成数组每个字符渲染成一个带有颜色的 span。一篇文章 1000 个字符就是 1000 个 spanVue 3 的 diff 在这种规模下完全没压力。真正需要优化的是不要在每次击键时重建整个数组而是通过v-for配合track-by-index让 Vue 只更新变化的部分。实测下来1200 字符以内无感知。第二事件节流与取消。输入事件不需要节流击键是天然低频的。需要节流的是统计信息刷新比如实时 WPM、进度百分比、速度曲线这些如果每次击键都同步刷新会造成大量不必要的重渲染。我用requestAnimationFrame做了调度把 WPM 数据的更新延后到下一帧保证最多 60 次/秒的刷新频率。这个优化在打字速度飙升到 120 WPM 的时候仍然足够平滑。第三Vue 3 的shallowRef。打字光标状态、错误 Map 这类嵌套数据其实不需要深度响应式shallowRef就够用了。我用shallowRef来持有TypingEngineState整个对象内部字段的更新在打字引擎内部完成Vue 只监听引用级别的变化。这样避免了 Vue 3 对深层对象做 Proxy 代理的开销也减少了很多不必要的响应式依赖追踪。对于打字这种高频状态更新场景这个优化能肉眼感知到变流畅。6. 实战踩坑记录常见问题与排查6.1 问题速查表开发过程中前前后后遇到不少问题我把典型的几个整理成了速查表按问题现象、可能原因、解决方案三列来看问题现象可能原因解决方案打字时中文输入法闯入第一个字母被吃掉系统输入法处于中文模式keydown被标记为Process在compositionstart时设置isComposing标记忽略该轮输入启动时尝试切换到英文模式并在界面上给出当前输入法状态打包后字体文件丢失界面渲染异常electron-builder未将resources/fonts包含在files中在files增加resources/fonts/**/*规则确保自定义字体被打包用户数据目录里的词库加载失败路径含有特殊字符或者目录不存在在storage.ts初始化时调用fs.mkdirSync(userData/dictionaries, { recursive: true })目录不存在就创建Windows 上窗口大小记不住窗口关闭时保存逻辑未处理maximized状态在close事件中读取win.getBounds()和win.isMaximized()两者一起存档开发环境正常打包后 IPC 请求无响应contextIsolation配置在打包环境被重置检查electron.vite.config.ts中build.rollupOptions.output是否正确注入主进程入口确保preload文件被正确打出打字完成后统计面板显示 NaNstartTime为null计算耗时取到 0统计计算前先判断startTime是否存在没有就返回 0 而不是做除法6.2 独家避坑技巧第一个技巧跟日志有关。一开始开发 Electron 应用主进程里的console.log输出是能看到的但打包成安装版之后这些输出就进了黑洞。后来我在主进程里写了一个极简的文件日志模块把所有console.log转发到userData/logs/main.log渲染进程的console也通过 IPC 转发过来。遇到用户报告问题第一件事就是让他把日志目录发给我五分钟内定位问题。这个习惯在后来的开发中救了我无数次。第二个技巧是关于 Vue 3 和 Electron 的热更新陷阱。electron-vite默认支持渲染进程的 HMR非常爽但主进程修改后需要手动重启应用。我一开始经常改完主进程代码就继续点界面结果发现修改没生效浪费时间排查。后来我在开发脚本里加了electron-vite dev --watch的辅助参数主进程代码变化后自动重启 Electron 应用。工具链的自动重启虽然慢一点但可以确保你测试的是最新代码。第三个技巧跟打字引擎的自动化测试有关。打字判定逻辑是纯函数非常适合做单元测试。我在useTypingEngine里把核心循环抽成了一个不依赖 Vue API 的纯 TypeScript 类然后在 Vitest 里写了 50 多个测试用例覆盖各种击键序列、退格行为、错误计数、完成判定。实践下来这类测试每次改动词库逻辑或判定算法时都会跑一遍能挡住九成以上的回归 bug。UI 组件测试反而测的少因为打字游戏 UI 变动频繁写测试的成本跟收益不成正比。7. 写在最后一点个人心得这次从 VSCode 插件迁移到 Electron Vue 3 独立应用的架构改造前后花了两周晚上加周末的时间整体来说收益非常明显。最直观的感受是应用打开速度比 VSCode 插件的 Webview 快许多内存占用也从 VSCode 进程里剥离出来打字时的卡顿完全消失了。更重要的是独立应用在 UI、交互、数据存储上的自由度是插件完全没法比的你能按照一个“产品”的标准去打磨它而不是依附在编辑器的框架里做一个“功能”。如果让我给打算做类似项目的人一些建议我会说先想清楚你的核心用户是谁核心场景是什么然后再决定架构。Electron 的灵活度很高但也很容易让人沉迷于各种“高阶优化”最后做出来一个复杂但不好用的东西。打字游戏这个项目我最大的收获就是学会了克制——用最朴素的 JSON 文件存储用最标准的 IPC 通信用最直接的 Vue 响应式绑定所有的复杂度都收敛在打字引擎这一个核心模块里。这种“把笨功夫下在刀刃上”的做法可能是这次改造最值得分享的工程经验。