1. 项目概述：从 VSCode 插件到独立应用的演进
先说结论：标题里那句“从 VSCode 扩展到独立应用”，其实点出了一个非常典型的桌面端演进路径——先在一个成熟宿主里做插件验证玩法，再单独打包成独立应用分发。Electron + Vue 3 这个组合，放在打字游戏这个场景里，最大的好处是“一套代码，三端通吃”：Windows、macOS、Linux 全平台覆盖，UI 用 Vue 3 写起来效率极高，底层又能直接调用 Node.js 的 fs、child_process 等系统能力。
我最初接到这个需求时，用户是想做一个类似“打字练习 + 关卡挑战”的小工具。但一开始的形态是一个 VSCode 插件——在编辑器里开一个 Webview 面板，用 TypeScript 写逻辑，用 HTML/CSS 渲染界面。VSCode 插件的好处是启动成本低、不愁安装渠道、还能顺手读取当前打开的文件作为打字素材。但坏处也很明显：插件受限于 VSCode 的扩展 API，窗口控制、全局快捷键、独立存储、系统托盘这些桌面应用的基本能力全都受限制。
这就是标题里“架构改造”的核心动机——把跑在 VSCode Webview 里的应用，迁移到一个独立的 Electron 主进程 + 渲染进程架构中。改造不是重写，而是把渲染层尽量保留，把主进程能力补全，再通过 preload 脚本做安全的上下文桥接。
这个项目适合谁参考？如果你正打算把 VSCode 插件、浏览器页面，或者一个纯前端项目改造成桌面应用，这篇文章可以帮你少踩很多坑。即便你只是对 Electron + Vue 3 的开发模式感兴趣，里面的工程化配置、进程通信方案、打包发布细节，也都是可以直接抄作业的。
2. 架构改造前的设计思路
2.1 先搞清楚：VSCode 插件和 Electron 应用到底差在哪
很多从插件转独立应用的开发者，最容易犯的错就是“把 VSCode Webview 那套直接搬过来”。表面上看都是 HTML + CSS + JS，但底层的运行模型完全不同。
VSCode 插件里，你的前端跑在一个受限的 Webview 环境中，想要读写文件必须通过 vscode.workspace.fs 这类 API，由插件主进程代为操作。而 Electron 应用里，渲染进程默认不开放 Node.js 能力，但你可以通过 preload 脚本把需要的主进程能力暴露给渲染层。这个差异直接决定了你改造时的代码边界。
我建议先画一张“能力清单”表格，把当前插件里用到的所有 VSCode API 列出来，再逐个判断在 Electron 里用什么方案替换。这个步骤别跳过，我见过太多人改到一半发现某个功能在 Electron 里没有对应实现，被迫返工。比如：
- vscode.window.showInformationMessage 替换为 electron.dialog.showMessageBox
- vscode.workspace.fs.readFile 替换为 fs.promises.readFile
- vscode.commands.registerCommand 替换为 ipcMain.handle
- vscode.window.createWebviewPanel 替换为 BrowserWindow 的 loadFile
2.2 为什么选 Vue 3 而不是 React 或原生
选 Vue 3 不是因为它比 React 好，而是因为这个项目原本就是一个 Vue 项目。但如果你是从零开始，我仍然会推荐 Vue 3 + Vite 这套组合。
原因有三：第一，Vue 3 的组合式 API 在处理打字游戏这种“高频状态更新 + 多关卡配置”的业务场景时非常顺手，ref、computed、watch 的组合天然贴合“当前输入内容、打字进度、统计结果”这类相互依赖的数据流；第二，Vite 的 dev server 启动速度快，配合 Electron 的热更新，开发体验接近纯前端项目；第三，Vue 的模板语法让 UI 结构一目了然，后期不管是你自己维护还是交给别人接手，门槛都低。
另外，Vue 3 的响应式系统在管理打字游戏的计时器、错误计数、速度统计时，性能表现足够好。这并非说 React 不行——它在处理大型列表上有优势，但打字游戏的核心是单行文本逐字对比，数据量很小，Vue 的细粒度响应反而更省心。
2.3 主进程、渲染进程、preload 三者的职责划分
这是整个改造工程里最关键的架构决策。我采用的方案是标准的“三明治”结构：
- 主进程（main）：负责窗口创建、菜单设置、文件读写、快捷键注册、系统托盘、自动更新
- preload 脚本：通过 contextBridge 暴露安全的 API 给渲染层，比如 readFile、saveRecord、getAppVersion
- 渲染进程（renderer）：纯 Vue 3 应用，只通过 window.electronAPI 调用主进程能力，不直接触碰 Node.js
有人可能觉得“直接在 webPreferences 里把 nodeIntegration 设为 true 不就行了，省事”。确实省事，但绝不推荐——安全风险极大。任何注入到渲染进程的第三方脚本，一旦拿到 Node.js 权限，就等于拿到了用户电脑的完全控制权。我见过有项目因为贪图省事这么干，后来被安全审计点名。
用 contextBridge 暴露 API 的好处是：渲染层只能调用你显式暴露的方法，权限最小化。比如我只暴露了：
// preload.js const { contextBridge, ipcRenderer } = require('electron') contextBridge.exposeInMainWorld('electronAPI', { readTextFile: (path) => ipcRenderer.invoke('file:read', path), saveGameRecord: (data) => ipcRenderer.invoke('record:save', data), getGameConfig: () => ipcRenderer.invoke('config:get'), onWindowControl: (callback) => { ipcRenderer.on('window:control', (_event, action) => callback(action)) } })渲染层拿到的只是一个带有安全方法的对象，根本接触不到 ipcRenderer 本身，也无法向主进程发送任意消息。这个设计，我建议不要妥协。
3. 关键工程搭建与核心细节
3.1 Electron + Vite + Vue 3 的项目初始化
现在创建一个 Electron + Vue 3 项目，我推荐直接用 electron-vite 这个构建工具，而不是手动拼接。它能帮你把主进程、preload、渲染进程三部分的构建配置一次性理清楚，同时天然支持热更新——改主进程代码后自动重启，改渲染层代码走 Vite HMR，体验很好。
初始化步骤很简单：
npm create @quick-start/electron@latest typing-game # 选择 Vue 3 + TypeScript 模板 cd typing-game npm install npm run dev这块要注意的是 Node 版本，electron-vite 要求 Node.js 18+ 或 20+，老项目如果是 16 的话建议先升级。我第一次在这上面卡了十几分钟，编译报错提示模块找不到，最后才发现是 Node 版本太低。
项目结构上，标准模板会给你这个布局：
src/ main/ # 主进程代码 preload/ # preload 脚本 renderer/ # Vue 3 应用如果你从 VSCode 插件迁移，原来插件的 src 目录基本对应这里的 renderer，只是需要删掉 vscode 模块的引用，把调用 vscode API 的地方替换成 window.electronAPI。
3.2 打字游戏的核心逻辑：不仅仅是统计 WPM
打字游戏这块，我重点想讲讲速度和准确率的计算逻辑——这是整个游戏体验的命门。
很多打字网站用的 WPM（Words Per Minute）算法差别都不大：统计正确输入的字符数除以 5（约定一个单词等于 5 个字符），再除以用时分钟数。但这里有个细节，要不要把错误输入的字符算进去？
我的做法是分两个指标展示：
- 毛速（Gross WPM）：所有输入字符 / 5 / 时间
- 净速（Net WPM）：正确字符 / 5 / 时间，如果为负数则归零
这两者同时展示，玩家能看到“我打得很快但错得多”和“我打得慢但很稳”之间的差异，游戏的目标感更清晰。
准确率计算看起来简单——正确字符数除以总字符数——但有个坑：当用户按下退格键修正错误时，之前的错误字符要不要计入最终准确率？我最初是按“实时状态”算的，也就是玩家随便乱打然后全部退格删掉重打，准确率会逼近 100%，这显然不公平。最后改成了“所有被替换过的错误字符都累计计数”，哪怕后来退格修正了，也仍然计入错误量。这样更公平，也更有挑战性。
代码里我用了一个简单的状态机来跟踪每个字符的状态：
interface CharState { char: string status: 'pending' | 'correct' | 'incorrect' | 'corrected' }每输入一个字符，对比目标文本对应位置的字符。匹配则设为 correct，不匹配则设为 incorrect，同时把累计错误数加 1。退格键只回退位置，不回退错误统计。这个设计能保证最终成绩反映真实水平。
3.3 关卡系统与文本素材管理
游戏之所以能有“从插件到独立应用”这样的定位变化，关卡系统的完整性是一个关键因素。插件阶段受限于 VSCode 扩展包体积，素材只能内置一小部分；变成独立应用后，就可以把文本素材做成可扩展的目录结构。
我在应用内设计了一个 assets/texts 目录，每一关对应一个 JSON 文件：
{ "id": "level-01", "title": "基础按键练习", "description": "练习主键盘区的字母与符号", "duration": 60, "texts": [ "The quick brown fox jumps over the lazy dog.", "Pack my box with five dozen liquor jugs." ] }主进程启动时扫描该目录，把关卡列表通过 IPC 传给渲染层。后续想加新关卡，直接往目录里丢 JSON 文件即可，不用重新打包。这个思路是从游戏 Mod 机制学来的，数据驱动的内容扩展方式是独立应用相比插件形态的一大优势。
计时器逻辑上，我采用的是“从第一个字符输入开始计时”，而不是“点击开始按钮后立刻计时”。这样能把玩家阅读题目的时间排除掉，成绩更公平。一旦时间到，不论当前打到哪里，强制结束并展示统计面板。
3.4 数据持久化：成绩与设置如何存储
VSCode 插件时代，配置存在全局状态里，跟编辑器的配置混在一起，导出和备份都麻烦。独立应用之后，我改用了一个用户数据目录下的 JSON 文件来存储所有内容。
Electron 提供了 app.getPath('userData') 来获取各平台的标准用户数据目录路径——Windows 在 %APPDATA%/typing-game，macOS 在 ~/Library/Application Support/typing-game，Linux 在 ~/.config/typing-game。我在这个目录下建了一个 data.json，保存历史成绩、设置项、解锁关卡进度。
每次游戏结束，渲染层通过 preload 调用 saveGameRecord 接口把成绩传给主进程，主进程读取现有数据、追加新记录、写回文件。为了避免频繁写盘磨损 SSD，我做了一个小优化：只有在游戏结束后才写入，不每次击键都写。
一个容易踩的坑：不要把数据文件放在资源目录（resources）或者应用安装目录里。因为打包后的应用目录通常是只读的，尤其 macOS 下签名应用目录只读，数据根本写不进去。我第一次打包测试时发现成绩无法保存，排查半天才意识到是路径选错了。老老实实用 userData 不会错。
3.5 主进程窗口管理与菜单定制
独立应用和 VSCode 插件最大的体验差异，就是窗口可以自由定制。我单独写了一个窗口管理模块，负责创建 BrowserWindow、监听窗口事件、动态调整菜单。
function createMainWindow() { const win = new BrowserWindow({ width: 1024, height: 720, minWidth: 800, minHeight: 600, title: '打字训练营', autoHideMenuBar: true, webPreferences: { preload: path.join(__dirname, '../preload/index.js'), contextIsolation: true, nodeIntegration: false } }) if (process.env['ELECTRON_RENDERER_URL']) { win.loadURL(process.env['ELECTRON_RENDERER_URL']) } else { win.loadFile(path.join(__dirname, '../renderer/index.html')) } return win }菜单方面，我没用默认菜单，而是自定义了一个精简菜单：文件、关卡、设置、帮助。其中“设置”里放“切换深浅色主题”“重置所有进度”两个选项。这里有一个贴士：通过 Menu.setApplicationMenu(null) 或者 autoHideMenuBar: true 可以隐藏菜单栏，但 Windows 用户习惯看到菜单栏，建议保留一个极简菜单而不是彻底移除。
3.6 开发模式与生产模式的环境切换
Vite 的 dev server 和生产构建环境差异很大，Electron 项目尤其要注意。开发时你要加载 http://localhost:5173，打包后你得加载本地文件。electron-vite 已经帮你处理了大部分，但我在代码里还是保留了显式的环境判断——就是上面 createMainWindow 里的那个写法。
这么做的好处是，不管 dev 还是 prod，你都知道当前走的是哪条分支，排查窗口白屏问题时会快很多。如果生产环境加载了 dev server 地址，窗口必然白屏并报错；如果开发环境误加载了本地文件，你又会失去热更新能力。这两类问题我都被坑过，明确分支之后再也没有出现过。
4. 实操过程：完整跑通一局游戏的开发流程
4.1 搭好脚手架后第一步：跑通 IPC 链路
我建议在写游戏玩法之前，先把 IPC 最小链路打通。也就是说，页面上放一个按钮，点击后能弹出一个由主进程生成的原生对话框。这一步的意义是确认主进程、preload、渲染层的连接是通的，后续所有功能都建立在这个链条上。
这个最小验证的代码量很小。主进程里注册一个 handle：
ipcMain.handle('dialog:open', async () => { const result = await dialog.showOpenDialog({ filters: [{ name: '文本文件', extensions: ['txt'] }] }) return result })preload 里暴露：
openFileDialog: () => ipcRenderer.invoke('dialog:open')渲染层 Vue 组件里点击按钮调用 window.electronAPI.openFileDialog()，拿到所选文件路径后，再调用 readTextFile 读取内容，显示在页面上。这一条链路跑通，你的应用就已经有资格叫“桌面应用”了。
4.2 从外部导入自己的打字素材
独立应用相比 VSCode 插件的一个显著优势是可以自由选择文本来源。我加了一个“导入素材”功能：用户选择本地的 TXT 文件，主进程读取内容后，渲染层把文本按照句子长度自动分段，生成一局自定义游戏。
具体逻辑是从 txt 中读出的全文，按句号、感叹号、问号切分句子，再过滤掉长度小于 20 或大于 200 的句子，然后随机取 10 句组成一局。这样，用户可以把新闻稿、小说片段、甚至代码注释变成练习素材。代码注释这个场景是我后来才想到的——程序员打代码时英文注释最常出错，如果训练素材就是英文注释，效率会直接翻倍。
4.3 统计面板的数据可视化
我用了 ECharts 来渲染历史成绩的折线图，展示最近 20 局的速度变化趋势。ECharts 本身不是 Vue 3 专用库，但在 Vue 3 里用很简单：
import * as echarts from 'echarts' import { onMounted, ref } from 'vue' const chartRef = ref<HTMLDivElement>() onMounted(() => { const chart = echarts.init(chartRef.value!) chart.setOption({ xAxis: { type: 'category', data: historyDates }, yAxis: { type: 'value', name: 'WPM' }, series: [{ type: 'line', data: historyWpm, smooth: true, areaStyle: {} }] }) })如果你不想引入体积较大的 ECharts，也可以直接用 Canvas 2D 画一个简版折线图——就一个坐标系加一条折线，代码量不到一百行。我最后选择了 ECharts，是因为它还顺带支持了热力图展示按键错误分布，这个视觉呈现对用户来说很直观。
4.4 全局快捷键：快速打开或隐藏应用
独立的电脑小工具，一个高频刚需是“随手呼出”。我用 electron 的 globalShortcut 注册了一个快捷键组合，比如 CommandOrControl+Shift+T，默认情况下若窗口不可见则将窗口显示并聚焦，相当于一键呼出打字练习界面。
这个功能看似简单，但有一个交互细节要注意：不要在游戏进行中强制切换窗口。我通过判断当前界面是否在游戏中，如果是，则弹出原生通知提示“游戏进行中，按 Esc 可暂停”，而不是直接把窗口抢到前台。这种细节会给用户很强的专业感。
注册全局快捷键的代码：
globalShortcut.register('CommandOrControl+Shift+T', () => { const win = BrowserWindow.getAllWindows()[0] if (!win) return if (win.isMinimized()) win.restore() if (!win.isVisible()) win.show() win.focus() })每次开发调试完，记得在应用退出时撤销注册，否则快捷键可能会残留到下次启动，导致重复注册冲突。
5. 常见问题与排查技巧实录
5.1 窗口白屏：最常见也最令人抓狂
Electron 窗口白屏几乎是每个新手都会遇到的，原因五花八门。我见过最多的是生产模式下加载路径不对。前面提到的环境判断就为此埋了伏笔——你没判断 dev / prod，用了 loadURL 指向 dev server，但打包后 dev server 已经不存在了，自然白屏。
另一个原因是 BrowserWindow 创建时机过早，渲染进程还没准备好。可以等待 ready-to-show 事件再显示窗口：
win.once('ready-to-show', () => { win.show() })这样可以避免窗口闪烁白屏后再渲染内容的体验问题。
排查白屏的第一步永远是打开开发者工具看 Console。你会发现：要么资源文件 404，要么 JS 报错导致 Vue 没挂载，要么 CSP 阻止了内联脚本执行。Electron 的安全默认值比较严格，如果你用了内联脚本，默认会被 CSP 挡住，需要在 index.html 里加 meta 标签放行或者直接把脚本外置。我强烈建议直接把脚本外置，而不是放宽 CSP。
5.2 IPC 调用无响应：preload 路径一定要检查
很多次我问“为什么 window.electronAPI 是 undefined”，最后都发现是 preload 脚本路径写错了。因为 electron-vite 构建后 preload 脚本的输出目录跟源代码目录不一样，如果你写成了相对路径且没有正确指向，preload 就不会被加载。
一个排查技巧：在 preload 脚本里加一条 console.log，如果它在开发者工具里没打印出来，说明 preload 根本没加载。然后再确认 webPreferences 里 preload 路径是否指向了构建产物中的实际文件。
5.3 打包后字体和图标资源丢失
开发时用相对路径引用资源没问题，但打包后页面加载的是 file:// 协议，相对路径解析的基准目录会变化，很容易导致资源找不到。我的解决方式是统一用 electron-vite 的资源处理机制——所有静态资源放到 src/renderer/src/assets 下，通过 import 导入，构建时会自动处理路径。
另外，字体文件如果体积较大，建议重新压缩一下。我用中文字体打包后体积增加了几十 MB，最后用 fontmin 做了子集化处理，只保留用到的几百个常用字，体积立刻降下来了。打字游戏里其实用不到全部汉字，游戏界面只要显示必要的字就行。
5.4 游戏卡顿和内存泄漏
打字游戏本身负载不高，但如果页面长时间运行，还是会出现卡顿。我遇到过一次是因为图表组件没销毁——切换到历史成绩页时创建了 ECharts 实例，切回游戏页时没有调用 dispose，多切几次就堆积了大量实例。
在 Vue 3 的 onUnmounted 钩子中调用 chart.dispose() 是必须的。另一个常见泄漏点是 setInterval 计时器没有清理——游戏过程中每秒都要更新剩余时间，我用了 setInterval 且起始于游戏开始，结束时清晰定位清理掉引用。
一个容易被人忽略的点是按键盘事件监听：如果全局监听了 keydown，却一直没有移除，切换路由后监听还在，导致同一个键盘事件触发多次比较逻辑。一定要在游戏结束或者组件卸载时调用 window.removeEventListener。
5.5 不同平台的兼容性差异
Electron 虽然号称跨平台，但细节上的坑不少。窗口关闭行为在 macOS 上默认是隐藏窗口而不是退出应用，很多从 Windows 开发习惯转过来的人会不适应。处理方式是监听 window-all-closed 事件，在非 macOS 平台调用 app.quit()，macOS 则保持应用常驻。
还有全屏快捷键，Windows 和 Linux 上是 F11，macOS 上则是 Ctrl+Command+F，并且这个快捷键在 macOS 上如果应用没有正确配置，可能默认不生效。我在菜单里加入了“切换全屏”的显式选项，至少让用户可以通过菜单完成这个操作。
字体渲染在三个平台上也不完全一致：Linux 上中文字体有时会比较模糊，Windows 和 macOS 会好一些。如果追求一致的呈现，可以在 CSS 里指定跨平台字体栈，并在 Linux 上建议用户安装 Noto Sans CJK。我实际测试过，装上之后每个平台的观感基本统一。这些小细节虽然不影响功能，却显著影响用户对应用质量的第一印象。
5.6 开发中的热更新问题
electron-vite 的默认设置下，主进程和 preload 改了之后，应用会自动重启。但如果你正在游戏过程中，突然重启会导致当前进度丢失，体验不好。我后来加了一个小习惯：调试功能时先存好游戏记录再改主进程代码。
如果你发现改了 preload 代码后没有生效，多半是因为 electron-vite 没有触发 reload 事件。你需要手动刷新窗口——按 Ctrl+Shift+R 或者重启 npm run dev。这个问题出现的频率不高，但遇到了别钻牛角尖，直接重启即可，不值得为此浪费时间。
6. 打包发布与后续扩展建议
6.1 electron-builder 配置要点
打包我选择了 electron-builder，它跟 electron-vite 配合得很好。最基础的配置在 electron-builder.yml 里，需要指定 appId、productName、文件目录、NSIS 配置等。
appId: com.example.typinggame productName: 打字训练营 directories: buildResources: build files: - out/**/* - resources/**/* win: target: - target: nsis arch: - x64 nsis: oneClick: true perMachine: false allowToChangeInstallationDirectory: true createDesktopShortcut: true这里比较关键的坑在于文件过滤。如果没有把 resources 里的关卡素材目录加进去，打包后的应用会提示“找不到关卡文件”。我最初遇到过打完包以后应用能启动、游戏也能显示，但加载关卡列表时一片空白——就是资源没打包进去。
6.2 自动更新的思路
对于独立应用来说，自动更新是一个很加分的功能。Electron 官方有 autoUpdater 模块，配合 electron-builder 的 publish 配置可以对接 GitHub Releases 或自建服务器。
但我不建议第一版就做自动更新。因为需要额外搭建一个更新服务器，还要处理 sig 签名校验，属于后续迭代的范畴。先把核心游戏体验做好，更新机制最后再加也不迟。
如果你确实想加，最简单的方案是 electron-updater，它比原生 autoUpdater 好用很多，支持配置私服地址，并且可以在渲染层监听下载进度事件来显示进度条。
6.3 后续扩展：游戏化与社区化
游戏本身做扎实之后，可以往两个方向扩展：一是本地增强——增加多种游戏模式，比如限时模式、单词冲刺模式、错误回顾模式；二是线上联动——个人成绩对比、每日挑战、经验值与等级体系，让用户有持续玩下去的动力。
技术层面，考虑到打字游戏的核心数据就是“按键时间戳 + 按键事件”，这些数据非常适合用来做各种复盘的呈现，比如按键热力图、错误模式分析、输入节奏曲线。如果后续想加入多语言版本，把文本资源和 UI 翻译做成国际化模块，Vue 3 的 vue-i18n 可以轻松接入。
7. 项目中的一些实用心得
整个改造过程中，最深的体会是：架构改造不是炫技，而是为了给用户更完整的产品体验。VSCode 插件阶段，打字游戏更像一个编辑器里的彩蛋功能；变成独立应用后，它才真正获得了自己的完整产品形态——有自己的窗口、自己的菜单、自己的数据目录、自己的更新机制。
从技术栈的角度看，Electron + Vue 3 确实是桌面端小工具类应用的高效组合之一。Electron 生态成熟、社区资源丰富、跨平台方案稳定，Vue 3 的工程化体验和组件化开发效率都很高，两者搭配几乎没有明显的短板。
最后分享一个小技巧：在做 Electron 应用开发时，强烈建议把主进程代码尽量做薄，所有业务逻辑能放渲染层就放渲染层，主进程只做资源管理、系统交互、数据持久化这类脏活累活。主进程一旦崩溃，整个应用都会退出，而渲染进程崩了你还能通过 webContents.reloadIgnoringCache() 重新加载，容错性好很多。
如果你打算做一个类似的桌面应用，不管是不是打字游戏，这条架构边界都值得认真遵守。
