我最早做这套东西的时候项目还只是 VSCode 里的一个扩展给编辑器加了个面板塞进一段英文文本键盘敲进去实时标红标绿、统计正确率和 WPM。当时听起来挺美编辑器给的扩展宿主、命令系统、Webview 全都现成我这个会写 Vue 的前端几乎零成本就把它跑起来了。但真用了一段时间就发现VSCode 扩展的“天花板”太明显了——窗口结构被编辑器模板框死游戏弹窗只能在 Webview 里挤着每次想看成绩还得点开命令面板最要命的是想让用户装一个带图标、能双击打开、能存本地记录、还能读外部文本文件的独立应用VSCode 这层壳根本做不到。所以我把项目从 VSCode 扩展“卸”下来重新做成了一个基于 Electron Vue 3 的独立桌面打字游戏。这次不是把原来的 Webview 原样搬过来而是一次真正的架构改造把打字核心逻辑从编辑器和扩展宿主中抽离让同一套代码既能编译成 VSCode 扩展继续用又能跑在 Electron 的渲染进程里变成一个独立的桌面应用。如果你也正在纠结“先做扩展还是直接上桌面应用”、或者有一个已经跑在 VSCode 里的工具想升级成独立产品这篇实战记录应该能给你一条比较完整的改造路径。1. 项目背景与架构改造动机1.1 VSCode 扩展起步方便与边界先说清楚为什么最初会选择 VSCode 扩展这个形态。对一个以打字练习为核心的产品来说VSCode 给了你一个现成的编辑器上下文文本输入、键盘事件、焦点管理这些基础能力都是现成的我通过registerWebviewPanel挂一个 HTML 页面进去再用onDidReceiveMessage接收前端事件几乎不需要关心窗口、进程、焦点这些桌面层的事情。对一个验证想法的原型来说这个速度是无敌的。但一边做一边就撞到了几堵墙。第一堵墙是产品形态。VSCode 扩展再多功能打开方式永远是“打开 VSCode → 找到图标 → 打开 Webview”而不是桌面用户习惯的“双击图标进入应用”。你要做一款让人愿意每天打开练指法的工具首先得有一个独立入口。第二堵墙是 UI 自由度。Webview 里再怎么写 CSS窗口外层还有 VSCode 的标题栏、侧边栏、状态栏游戏界面很难做成沉浸式的全屏体验。第三堵墙是数据归属。VSCode 扩展的数据通常放在globalState里导出成绩、保存训练记录、读取本地 txt 文件这些需求每一件都要绕很多弯。这里不是否定 VSCode 扩展而是要说清楚扩展适合做“编辑器功能的延伸”但如果你在做的其实是一个“产品”那么从扩展走向独立应用是迟早的事。1.2 改造成独立应用后的设计空间决定改成独立桌面应用之后我最直观的感受是开发维度的“自由度”完全不一样了。窗口是自己的你能控制大小、比例、无边框模式甚至游戏准备时可以做成一个极窄的专注条UI 是自己的Vue 3 的组件化可以放开用主题切换、动画、频谱柱状图这些东西都不用再在 Webview 的受限环境里抠系统能力是自己的读文件、保存历史记录、自定义快捷键、开机自启、托盘菜单这些能力在 Electron 主进程里都是顺手的事情。但这个自由度是有代价的。代价就是你必须自己负责进程模型、安全边界、IPC 通信、窗口生命周期以及打包分发这一整套东西。尤其是我最初在 VSCode 扩展里写了不少逻辑这些逻辑是跟“键盘事件 文本比较”直接相关的并不依赖编辑器 API。如果我只图快把它们重写成 Electron 版本那 VSCode 扩展版本就废了。所以这场架构改造的真正核心不是“写一个 Electron 应用”而是“把核心逻辑从运行环境里抽出来再让两个环境共享它”。1.3 技术选型Electron Vue 3 的理由选 Electron 而不是 Tauri 或者纯 Web最直接的理由是生态和心智负担。Electron 的进程模型和 Chromium 内核是前端团队最容易上手的这意味着 Vue 3 那套状态管理、组件系统、构建工具能原封不动地搬到渲染进程里团队里每个前端都能够立刻理解。Tauri 我也认真评估过它启动小、内存低确实很香。但它要求 Rust 后端且把系统能力暴露给前端的 IPC 方式比 Electron 要“绕”一些对大多数以 TypeScript/Vue 为日常的团队来说改造成本并不低。再有就是成熟度Electron 的打包方案、自动更新、崩溃上报、窗口持久化这些生态链都比 Tauri 完整踩坑资料也更多做一个打字游戏这个量级的产品Electron 是性价比最高的选择。Vue 3 的部分核心是 Composition API 带来的逻辑复用能力。打字游戏的计时、统计、按键处理、界面刷新彼此交错如果用 Options API 很容易散在各处用setup把“统计时序”和“键盘事件”组织成独立的useTypingEngine、useStopwatch、useKeyHandler每一块都能单独测试。所以最终技术栈定为Electron Vue 3 TypeScript electron-vite。2. 核心架构从扩展思路到桌面应用映射2.1 划清边界打字引擎与运行环境解耦架构改造里最重要的一步是给代码划分边界。我当时定的原则是凡是和键盘、文本、时间、成绩计算相关的逻辑一律不碰 DOM、不碰 window、不碰 electron API。这块代码我命名为typing-engine它只是一堆纯 TypeScript 函数和类。引擎里什么概念最重要参考文本reference、用户当前输入位置cursor、按键产生的字符key、时间戳timestamp。它只根据这些输入告诉你当前字符对还是错、是否完成以及到当前时间为止 WPM/正确率是多少。这样设计之后这套引擎可以同时被三端复用VSCode 扩展里Webview 的onDidReceiveMessage收到键盘事件后交给引擎。Electron 渲染进程里渲染层捕获 window keydown 后交给引擎。将来如果做 Web 版在页面里的 keydown 事件处理后交给引擎。为了让引擎做到这一点我用了一个很简单的接口来抽象输入来源export interface TypingInputSource { onKeyDown: (key: string, timestamp: number) void; }上面这个接口只是一个示意。真实场景里键盘事件可能会带修饰键、组合键、IME 中间态所以实际的抽象是onTextInput(char: string, meta: InputMeta)把“物理按键”和“逻辑字符”分开。这个细节后面会再展开。2.2 模块映射VSCode 扩展能力迁移到 ElectronVSCode 扩展能做的事情在 Electron 里几乎都能找到对应物。比较有价值的做法是把扩展里那些“能力点”逐条列出来再做映射而不是直接重写。当时我做的映射表大概是这样的VSCode 扩展能力在 Electron 应用里的对应方案commands.registerCommandipcMain.handle(game:start) 渲染进程调用window.api.startGame()Webview 面板主窗口的 BrowserWindow Vue Router 控制不同视图context.globalStateelectron-store 或 SQLite存用户成绩和配置window.showInformationMessage主进程 Notification API 或渲染层消息组件读取工作区文件主进程 dialog fs 读文件再通过 IPC 把内容送回渲染层状态栏项StatusBarItem自定义底部状态栏组件数据由 Pinia 驱动这张表最核心的思路是扩展里的 command 本质上是编辑器宿主与扩展代码之间的一条通道对应的桌面应用概念就是 IPC。把“命令”统一收敛成 IPC channel前端只暴露一个 type-safe 的调用对象整个架构的迁移路径就非常清晰了。2.3 双模式方案同一套核心逻辑服务两端既然引擎已经抽出来了那就没必要丢掉 VSCode 扩展版本。我的做法是把仓库分成三层packages/engine纯逻辑打字引擎、统计模块、文本解析。packages/vscode-extensionVSCode 扩展壳复用引擎提供 Webview 渲染和命令入口。packages/desktopElectron Vue 3 桌面壳复用引擎提供完整桌面 UX。两个壳的代码里都有一些“平台适配层”但加起来不超过几百行。VSCode 扩展这边负责把编辑器消息转成引擎输入Electron 这边负责把键盘事件转成引擎输入。其余大部分业务逻辑都写在引擎包里。这样在做桌面版功能时VSCode 版也能跟着吃到修复和新特性。不过要提醒一句双模式维护是有成本的如果只是为了自己用不建议两端同时维护。我保留 VSCode 版本的原因是很多用户确实需要在写代码或者看文档时顺手练一段独立应用则负责更沉浸的训练场景。两者定位不同共用引擎后维护压力已经小了很多。3. Electron Vue 3 桌面应用搭建实操3.1 初始化项目与目录结构Electron 项目我强烈建议直接用 electron-vite 脚手架不要手动拼webpack electron。electron-vite 天然处理了主进程、preload、渲染进程三套代码的构建开发时还有热更新省掉大量配置时间。我当时用的创建命令是pnpm create quick-start/electronlatest typing-trainer -- --template vue-ts装完之后目录长这样typing-trainer/ ├── src/ │ ├── main/index.ts # 主进程入口 │ ├── preload/index.ts # 预加载脚本 │ └── renderer/ │ ├── index.html │ └── src/ │ ├── App.vue │ ├── main.ts │ └── components/ ├── electron.vite.config.ts ├── electron-builder.yml └── package.json这个结构把三端分得很清楚。主进程只管窗口创建、生命周期和系统能力preload 只做 IPC 桥接渲染进程完全是一个正常 Vue 3 应用。打字引擎放在src/renderer/src/engine还是不放在渲染目录好我的建议是如果引擎将来要单独发包就放packages/engine如果不打算用 monorepo也可以先放src/shared/engine然后同时被 electron-vite 的外部化配置引用。我自己最终是用了 pnpm workspace 拆包打包时把 engine 作为普通依赖打进去即可。3.2 主进程窗口配置与 IPC 封装主进程的窗口配置里最关键的几个点是contextIsolation必须开、nodeIntegration必须关、preload 脚本路径要正确、窗口要允许自动隐藏菜单栏。我当时的主窗口配置大概长这样import { app, shell, BrowserWindow } from electron; import { join } from path; function createMainWindow() { const mainWindow new BrowserWindow({ width: 1280, height: 800, minWidth: 960, minHeight: 640, autoHideMenuBar: true, title: TypeTrainer, webPreferences: { preload: join(__dirname, ../preload/index.js), contextIsolation: true, nodeIntegration: false, sandbox: false } }); if (process.env[ELECTRON_RENDERER_URL]) { mainWindow.loadURL(process.env[ELECTRON_RENDERER_URL]); } else { mainWindow.loadFile(join(__dirname, ../renderer/index.html)); } mainWindow.webContents.setWindowOpenHandler((details) { shell.openExternal(details.url); return { action: deny }; }); return mainWindow; }关于sandbox: false这里多说一句Electron 20 之后 preload 默认沙箱化如果我在 preload 里用到了require(electron)或者一些 Node 模块必须把 sandbox 关掉否则会报错。更安全的方式其实是在 preload 里只用contextBridge和ipcRenderer这种场景下 sandbox 保持默认 true 也行。但如果 preload 里需要引入第三方模块做文件操作就需要显式设置。IPC 层面我统一用ipcMain.handleipcRenderer.invoke这个模式。处理逻辑全部集中在主进程的ipc.ts里维护避免一堆 Promise 逻辑散落在各处。ipcMain.handle(app:get-version, () app.getVersion()); ipcMain.handle(dialog:open-text-file, async () { const result await dialog.showOpenDialog({ filters: [{ name: Text, extensions: [txt, md] }], properties: [openFile] }); if (result.canceled) return null; return readFile(result.filePaths[0], utf-8); });这条链路的通用经验是渲染进程永远不应该直接拿到 Electron API所有能力通过 preload 暴露出的白名单方法访问。这样将来如果要换成 Tauri 或 Web 后端渲染层完全不需要改只需要替换 preload 和 IPC 实现。3.3 preload 安全桥接与类型声明preload 脚本做的事情就是把 IPC 的通道收拢成一个类型安全的 API 对象注入到页面里。我当时写的是import { contextBridge, ipcRenderer } from electron; const api { getVersion: () ipcRenderer.invoke(app:get-version) as Promisestring, openTextFile: () ipcRenderer.invoke(dialog:open-text-file) as Promisestring | null, saveRecord: (record: PracticeRecord) ipcRenderer.invoke(store:save-record, record) as Promisevoid, onWindowFocusChange: (callback: (focused: boolean) void) { const listener (_event: unknown, focused: boolean) callback(focused); ipcRenderer.on(window:focus-change, listener); return () ipcRenderer.removeListener(window:focus-change, listener); } }; contextBridge.exposeInMainWorld(api, api);类型声明这一步特别重要在src/renderer/src/types/api.d.ts里给 window 挂上类型这样 Vue 组件里window.api.openTextFile()这类调用就有完整补全。export interface PracticeRecord { textId: string; wpm: number; accuracy: number; duration: number; completed: boolean; createdAt: number; } declare global { interface Window { api: { getVersion(): Promisestring; openTextFile(): Promisestring | null; saveRecord(record: PracticeRecord): Promisevoid; onWindowFocusChange(callback: (focused: boolean) void): () void; }; } }这里有一个踩过的坑preload 里不能直接导出变量给渲染进程使用必须通过contextBridge.exposeInMainWorld放进 window。最开始我还试图用window.api require(./ipc)这种方式结果发现渲染进程里根本访问不到。这其实是 Electron 安全模型的硬性约束理解成“preload 是主进程和渲染进程之间的翻译官而不是可以随便向页面暴露 Node 能力的大门”就对了。3.4 窗口状态持久化与本地数据存储打字游戏需要保存训练记录、当前光标位置、配置项。这些数据如果放在 localStorage 里会被清理或丢失放在渲染进程文件里又不符合 Electron 的权限模型。正确的做法是用 electron-store 这个库或者更原始但稳妥的方案——在主进程里手动读写 JSON 文件。当时我用的是 electron-store。它内部会把数据写到系统用户目录下的 app 配置文件夹里天然支持读写、监听变化接口也简单。设置方式import Store from electron-store; type StoreSchema { records: PracticeRecord[]; settings: { theme: light | dark; soundEnabled: boolean; }; }; const store new StoreStoreSchema({ defaults: { records: [], settings: { theme: light, soundEnabled: true } } });窗口的位置和尺寸也可以用同一个 store 来持久化。每次窗口resize或move时用 debounce 把新的 bounds 写进 store创建窗口时先读 store有值就把它作为窗口初始 bounds。这里有个重要的坑不要用 localStorage 存窗口几何状态。因为窗口创建发生在渲染层挂载之前主进程必须启动时就能读到 bounds。localStorage 在渲染层加载后才可用时序根本对不上。4. 打字游戏核心模块实战细节4.1 打字输入与光标推进打字的交互模型看起来简单用户敲一个字符光标前进一位字符对就标绿、错就标红。但实际实现里有很多决策点。我先定义了一个纯逻辑的TypingEngine类它不做任何 DOM 操作只负责比较字符和维护状态export class TypingEngine { private reference: string[]; private cursor 0; private errorAt: Setnumber new Set(); private startedAt 0; private keyCount 0; private correctCount 0; constructor(referenceText: string) { this.reference referenceText.split(); this.startedAt performance.now(); } handleInput(char: string): { cursor: number; correct: boolean; done: boolean } { if (this.cursor this.reference.length) { return { cursor: this.cursor, correct: false, done: true }; } const expected this.reference[this.cursor]; const correct char expected; if (correct) { this.correctCount 1; } else { this.errorAt.add(this.cursor); } this.keyCount 1; this.cursor 1; return { cursor: this.cursor, correct, done: this.cursor this.reference.length }; } getStats() { const elapsedMinutes (performance.now() - this.startedAt) / 60000; const wpm elapsedMinutes 0 ? Math.round(this.correctCount / 5 / elapsedMinutes) : 0; const accuracy this.keyCount 0 ? Math.round((this.correctCount / this.keyCount) * 100) : 100; return { wpm, accuracy, cursor: this.cursor, done: this.cursor this.reference.length }; } }这段代码的精髓是把“打字引擎”当成一个确定性的状态机引擎只根据按键和时间返回结果界面负责把结果画出来。这样单元测试也好写传一串按键进去断言光标位置和统计结果即可。界面上我用了一个很朴素但效果好的方案把文本按字符拆成一个个span每个字符根据index cursor的判定来设置 class 是 正确、错误还是未输入。Vue 3 里用v-for渲染几千个 span 性能问题不大但如果是长文章几千字符就要考虑虚拟列表后面会单独讲。4.2 输入法冲突与边界处理中文用户用这类英文打字工具最典型的坑就是输入法拦截和组合态。用户键盘敲一个字母的时候如果输入法是中文模式keydown事件里的key可能是Process输入内容不会直接进入英文通道对打字引擎来说它期待的是单个 ASCII 字符这个中间态就会导致光标直接错乱。我的处理方式是function handleKeydown(e: KeyboardEvent) { // 处理组合中的输入法事件 if (e.isComposing || e.key Process) { e.preventDefault(); return; } // 过滤掉功能键和组合键 if (e.ctrlKey || e.metaKey || e.altKey) return; // 只接受长度为 1 的可见字符 if (e.key.length ! 1) return; engine.handleInput(e.key); }另外一个很隐蔽的坑是按住某个键不放时系统会连续触发keydown如果每次都往引擎里喂字符会导致光标一路狂奔完全不符合打字的直觉。正确做法是判断e.repeat如果为true就忽略或者将连续输入做成“允许长按重复”的开关让用户自己设置。从产品角度说专业的打字练习工具通常会将长按重复视为违规或直接忽略。还有一个边界退格键要怎么处理很多打字游戏不允许退格或者把退格当作错误计数。我最后给产品定的是默认允许退格回退但回退需要重新输入正确字符才能继续前进这样对新手更友好对追求严格训练的用户可以开启“禁止退格”模式。这个产品决策要反应到引擎 API 上所以我给引擎加了backspace()方法。4.3 数据统计WPM、正确率与时序计算WPMWords Per Minute是打字游戏最核心的指标。它的行业惯例是1 个英文单词约等于 5 个字符所以你首先要统计“用户正确输入了多少字符”除以 5 得到“正确单词数”再除以用时分钟数就是 WPM。举个例子用户用 1 分钟打了一段 120 个字符的英文文章其中正确字符 110 个用时 60 秒。那么正确单词数是 110 / 5 22WPM 22 / 1 22 WPM。如果用时 30 秒则 WPM 22 / 0.5 44 WPM。这个公式很简单但它能准确反映出“速度”和“准确性”两个维度。我做的统计还有一个细节在练习过程中WPM 应该随着实时输入更新而不是等结束后再一次性计算。这里要小心一个概念区分瞬时 WPM过去 N 秒内的实际输入速率。实时面板上显示的应该是这个值否则会出现“中途停顿很久WPM 直线下降”的误导。平均 WPM结束后整段输入的正确字符 / 总用时。最终成绩用这个。我的实现是引擎维护一个长度为 60 秒的滑动窗口时间戳数组每次输入字符时把(timestamp, correctCharCount)记录进去计算时通过二分查找找到窗口起点用窗口内的正确字符数来算瞬时 WPM。时序计算的另一个坑是“开始时间”。很多用户不会在页面加载后立刻开始打字所以我做成第一次按键才算真正的开始。startedAt在引擎第一次收到输入时才赋值这样成绩不会被准备阶段的空耗拖低。4.4 长文本性能优化与渲染策略打字游戏的界面如果只是显示短句几百个 span 完全没压力。但训练素材一旦是整篇文章比如 2000 词、一万多个字符一次性渲染上万个 span 就会卡。我的策略是做按需渲染把文章按行切成若干段只渲染“当前光标所在行 ± N 行”的内容其他行用占位高度撑住同时顶到底部自动滚动保证光标始终可见。Vue 3 里我封装了一个TypingTextView组件核心思路const visibleRange computed(() { const currentLine lineIndex.value; return { start: Math.max(0, currentLine - 5), end: Math.min(totalLines.value, currentLine 8) }; });每个可见行渲染成一个行组件行组件内部再拆成字符 span。性能优化之后1 万字符的文章也能保持 60 帧流畅滚动。还有一个和性能同样重要的细节不要每次按键都用 Vue 的响应式更新一整行所有字符的 class。正确做法是通过v-for的key精细更新或者干脆手动操作 DOM 只更新光标前后几个字符的 class。我当时实测发现用 computed 对每个字符做isCorrect(index)判断在 1 万字符场景下会带来明显的卡顿改成在输入事件里直接维护一个stateByIndex的数组并用shallowRef标记整体版本号性能好很多。5. 打包分发与踩坑实录5.1 electron-builder 配置与构建完成开发之后打包也是一个绕不开的大工程。我用的是 electron-builder配置文件里几个关键点值得写一下appId: com.typetrainer.app productName: TypeTrainer directories: buildResources: build output: release files: - out/** - package.json win: target: - target: nsis arch: - x64 nsis: oneClick: false allowToChangeInstallationDirectory: true createDesktopShortcut: true mac: target: - target: dmg arch: - x64 - arm64 category: public.app-category.educationfiles这里特别关键electron-vite 构建后产物在out目录打包时只需要把out和package.json打进去不要把整个node_modules都塞进去。electron-builder 会自动分析 dependencies把生产依赖装进 appdevDependencies 会被自动排除。我第一次打包时犯过一个典型错误在dependencies里放了一堆构建期用的库结果安装包体积直接飙到 300MB。后来把构建相关依赖全移到devDependencies只留运行时真正需要的依赖安装包立刻瘦了一半。5.2 打包后白屏与资源路径问题开发环境一切正常打完包双击 exe 就白屏是 Electron 新手最容易遇到的头号问题。白屏通常是两种原因造成的第一种是入口文件加载路径不对。开发环境下loadURL(process.env.ELECTRON_RENDERER_URL)生产环境下要loadFile(join(__dirname, ../renderer/index.html))。这里的__dirname是打包后主进程 js 文件所在的目录它和开发时的目录层级不一样路径一旦写错页面就加载不到。第二种是渲染进程里的静态资源路径用了绝对路径。Vue 项目默认base是/在打包后本地加载时/assets/xxx.js找不到。解决办法是给 electron-vite 设置renderer.base ./让资源路径改成相对路径。当时我在electron.vite.config.ts里加的就是renderer: { build: { rollupOptions: { input: { index: resolve(__dirname, src/renderer/index.html) } } } }以及环境判断时确保loadFile里用的是path.join而不是字符串拼接避免 Windows 路径斜杠问题。白屏还有一个容易被忽略的点主进程崩溃了但渲染层还在窗口显示空白。排查方法是在主进程入口处加process.on(uncaughtException, ...)日志输出再在启动时写日志文件。这套日志机制虽然糙但能省掉大量抓瞎时间。5.3 安装包瘦身与更新策略应用体积主要被两样东西影响Electron 运行时本身和 node_modules。Electron 运行时没法省但你可以做几件事把整体优化到不太离谱的程度只打生产依赖构建期依赖一律进 devDependencies。移除不需要的发行目标。比如只打 Windows 版时不要配置 mac 和 linux 的 target不要配npmRebuild去折腾一堆 native 模块。检查asar内的资源。给files配置里加!排除不必要的静态资源和文档进一步压缩安装包。关于asar多说一句默认情况下 electron-builder 会把应用代码打包进app.asar这个文件本身不可读能保护源码。鼠标指向安装包里的resources/app.asar可以直接打开吗不行需要npx asar extract app.asar ./out才能解包查看。但这不是重点重点是资源路径要基于app.getAppPath()或process.resourcesPath来写尤其是在需要读取extraResources目录时。更新策略方面如果只是个人工具最简单的做法是每次发布新版本后让用户重新下载。如果要做自动更新可以用 electron-updater配置好 publish 地址后基本开箱即用。但要注意Windows 下自动更新要求安装包必需签名否则系统会拦截更新器的执行。没有签名证书的话自动更新这件事就很容易在用户机器上翻车不如先用“检查版本 下载新包”的笨办法过渡。5.4 从 VSCode 扩展版本同步迁移的注意事项既然保留了 VSCode 扩展壳就有必要确保两端的引擎版本是同一个 tag 发出去的。我当时在 pnpm workspace 里配了engine: workspace:*两个壳子依赖同一个本地版本发布时用pnpm publish统一打 tag。这样桌面应用和 VSCode 扩展不会出现一个修复了 bug 另一个还在旧逻辑的情况。还要注意两端在“文本输入”的语义差异VSCode Webview 里用户敲键时焦点默认在 Webview 上不会自动吞掉编辑器快捷键但桌面应用里用户一打开应用就全局监听 keydown可能与系统快捷键冲突。比如按Ctrl W在浏览器里是关标签页在 Electron 里可能是关窗口。主进程里必须用before-input-event拦截这类组合或者干脆在窗口内禁用菜单栏快捷键。我当时用了一个比较简单的方案在渲染进程里只监听普通字符键组合键全部交给系统不在应用层做处理。6. 常见问题排查速查表现象可能原因解决方案打包后窗口白屏生产环境下加载路径错误检查loadFile路径是否用了path.join且基础目录是否正确渲染层访问不到window.apipreload 未执行或被 sandbox 拦截确认 preload 路径正确必要时sandbox: false键盘输入无效输入法组合态或按键被系统拦截增加e.isComposing判断过滤Process并用before-input-event排查WPM 显示异常开始时间过早或滑动窗口计算错误首次按键时初始化startedAt用正确的滑动窗口统计瞬时值长文本输入卡顿一次渲染太多字符按行虚拟渲染只渲染光标附近行安装包太大dependencies 混入构建期依赖把构建依赖移入 devDependencies压缩 files 范围双击安装后无桌面图标nsis 配置缺少快捷方式打开createDesktopShortcut确认 NSIS 配置选项应用无法访问本地文件权限或路径问题用 dialog 选文件读取后通过 IPC 传内容避免直接给渲染层 Node 权限如果要把这个项目继续往前推我个人的下一步计划是两个方向一是把自定义文章导入和生词库结合起来让打字素材更贴近用户自己的学习需求二是把练习数据做成可视化报表引入区间速度曲线和热力图。这两个方向都不需要推翻现有架构引擎已经抽得够干净桌面壳只管加 UI 和 IPC 就行。对于同样在考虑“要不要从 VSCode 扩展开到独立应用”的朋友我的建议是趁早决定、尽早抽核心。扩展做原型很快但它不是终点独立应用的入口、数据和产品体验才是这个工具能不能被用户长期使用的关键。别怕重构只要边界划清楚改造的每一步都会反哺原有版本让两个端都变得更好。