Electron+Vue3桌面应用架构迁移实战：从VSCode插件到独立应用-育师

1. 为什么这个打字游戏项目值得深挖：从 VSCode 插件到独立桌面应用的底层逻辑

Electron + Vue 3 桌面打字游戏实战——光看标题，很多人第一反应是“又一个玩具项目”。但如果你真做过 VSCode 插件开发，再碰过 Electron 打包发布，就会立刻意识到：这根本不是简单套个壳的事。它是一次典型的跨平台架构迁移实战，背后牵扯的是运行时环境、模块加载机制、UI 渲染上下文、权限模型和构建链路的全面重构。我去年帮一家教育科技公司把内部用的 VSCode 打字训练插件（基于 Webview API + Vue 2）迁移到独立桌面端，前后花了三周时间踩坑、重写、压测，最终用户留存率从 42% 提升到 79%。核心原因就一条：VSCode 插件本质是“寄生系统”，而 Electron 应用是“自治系统”——前者依赖编辑器宿主提供沙箱、API 和生命周期，后者必须自己扛起整个前端生态栈。

这个项目标题里藏着三个关键断层点：VSCode Webview 的受限 DOM 环境 vs Electron 主进程/渲染进程双线程模型；Vue 2 的 Options API 习惯 vs Vue 3 的 Composition API + Vite 构建范式；浏览器级 API（如 localStorage）的默认可用 vs Electron 中需显式桥接 Node.js 模块（如 fs、serialport）的权限管控。热搜词里反复出现的 “electron serialport” 不是偶然——它恰恰暴露了真实业务场景的刚需：打字游戏后期必然要接入物理外设（比如 USB 键盘响应延迟检测仪、自定义机械轴体反馈盒），而这类硬件交互在 VSCode 插件里根本不可行，因为 Webview 被严格禁止访问 Node.js 原生模块。所以，“架构改造”四个字，不是技术炫技，而是业务演进的刚性门槛。

适合谁参考？如果你正在维护一个功能渐丰的 VSCode 插件，发现它越来越像一个独立产品（比如带用户数据同步、本地音效库、硬件联动），那这个项目就是你的路线图。如果你是 Vue 3 新手，想避开“Vue CLI + Electron Forge”的过时组合，直接上手 Vite + Electron Builder 的现代链路，这里每一步配置都有实测参数。更关键的是，它不教你怎么“把网页转成 exe”——那种方案连键盘事件监听都可能失准——而是告诉你如何让 Vue 3 组件真正活在 Electron 的渲染进程中，能调用 nativeImage 捕获屏幕、用 remote 模块控制菜单、通过 contextBridge 安全暴露 serialport 实例。开头这几百字，不是铺垫，是帮你判断：这个项目值不值得你花三小时精读。答案很明确：只要你的需求超出“静态展示”，它就值。

2. 架构设计全景拆解：为什么必须放弃 VSCode Webview 模式

2.1 VSCode 插件模式的三大硬伤与 Electron 的对应解法

VSCode 插件中的 Webview 是个精巧的“安全牢笼”。它用 Content Security Policy（CSP）锁死所有危险行为：无法 require('fs')、不能 new WebSocket('ws://localhost:3000')、甚至 document.write() 都被禁用。我们原来的打字游戏插件就卡在这里——想加个“本地词库导入”功能，用户点击按钮后，本该弹出系统文件选择框，结果只看到控制台报错：Refused to evaluate a string as JavaScript because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy。这不是代码写错了，是 VSCode 主动切断了你和操作系统之间的通道。

Electron 的解法不是绕开限制，而是重建信任链。它把 UI 渲染层（Renderer Process）和系统能力层（Main Process）物理隔离，再通过预加载脚本（preload.js）和 contextBridge 暴露最小必要接口。举个具体例子：在 VSCode 插件里，你想读取用户 home 目录下的 .typinggame/config.json，只能靠 VSCode 提供的 workspace.fs API，且路径必须是工作区根目录下；而在 Electron 中，你可以在 preload.js 里这样桥接：

// preload.js const { contextBridge, ipcRenderer } = require('electron') const path = require('path') const fs = require('fs').promises contextBridge.exposeInMainWorld('api', { getConfig: async () => { const configPath = path.join(process.env.HOME, '.typinggame', 'config.json') try { const data = await fs.readFile(configPath, 'utf8') return JSON.parse(data) } catch (e) { // 文件不存在则返回默认配置 return { theme: 'dark', wpmTarget: 60 } } }, saveConfig: async (config) => { const configPath = path.join(process.env.HOME, '.typinggame', 'config.json') await fs.writeFile(configPath, JSON.stringify(config, null, 2)) } })

这段代码的关键不在语法，而在设计哲学：它没把 fs 模块直接扔给前端，而是封装成两个原子操作 getConfig/saveConfig，并限定只操作固定路径。这就是 Electron 架构的精髓——不开放能力，只开放契约。VSCode Webview 开放的是“有限的 Web API 子集”，Electron 开放的是“可审计的 IPC 契约”。当你的打字游戏需要接入 serialport（比如连接 Arduino 制作的实体按键响应板），这种契约模式就变成刚需：你绝不会把 serialport 实例直接挂到 window 上，而是通过 IPC 发送 { action: 'connect', port: '/dev/ttyUSB0' }，由主进程验证端口合法性后再建立连接。

2.2 Vue 3 + Vite 为何成为 Electron 渲染进程的最优解

很多教程还在用 Vue CLI + electron-webpack，这是三年前的老路。Vite 的优势在 Electron 场景下被放大了十倍：冷启动速度、HMR 稳定性、构建产物体积。我们实测对比过：一个含 5 个 Vue 组件、3 个第三方库（lodash-es, dayjs, @vueuse/core）的打字游戏项目，在 Vue CLI 模式下，Electron 启动后首次 HMR 热更新平均耗时 4.2 秒；换成 Vite + @vitejs/plugin-electron-renderer 后，降到 0.8 秒。原因很简单——Vite 的按需编译（ESM 动态 import）和原生 ES 模块支持，让 Electron 渲染进程能直接加载 .ts 文件，省去了 webpack 的 bundle 解析开销。

更重要的是，Vite 的插件生态天然适配 Electron 的双进程模型。比如 @vitejs/plugin-electron-renderer 这个插件，它会在开发时自动注入 preload.js 的路径到 index.html 的 script 标签中，并确保 renderer 进程的 vite.config.ts 与 main 进程的 vite.config.ts 分离配置。我们项目里 renderer 的 vite.config.ts 关键配置如下：

// vite.config.renderer.ts import { defineConfig } from 'vite' import vue from '@vitejs/plugin-vue' import { resolve } from 'path' export default defineConfig({ plugins: [vue()], resolve: { alias: { '@': resolve(__dirname, 'src') } }, build: { outDir: resolve(__dirname, '../dist/renderer'), emptyOutDir: true, sourcemap: true // 开发期必须开启，否则调试时看不到源码 } })

注意outDir指向../dist/renderer，这和主进程的../dist/main形成物理隔离。而主进程的 vite.config.ts 则完全不用 vue 插件，只用 rollup 打包：

// vite.config.main.ts import { defineConfig } from 'vite' export default defineConfig({ build: { outDir: resolve(__dirname, '../dist/main'), emptyOutDir: true, lib: { entry: resolve(__dirname, 'src/main/index.ts'), name: 'Main', formats: ['cjs'] } } })

这种分离不是为了炫技，而是为了解决一个致命问题：Vue 的 runtime 必须运行在渲染进程，而 Node.js 的 native 模块（如 serialport）必须运行在主进程。如果强行用 webpack 把两者打包进同一个 bundle，要么 runtime 找不到 dom 元素（主进程无 window），要么 serialport 在渲染进程报错（缺少 node-gyp 编译环境）。Vite 的双配置模式，从工程层面就杜绝了这种混淆。

2.3 从 Webview 到 Electron 的菜单与系统集成重构

VSCode 插件的菜单是“借来的”——你只能往 VSCode 自己的菜单栏里塞几个 item，比如“View: Open Typing Game Panel”。但独立桌面应用必须拥有完整的原生菜单。Electron 的 Menu 模块提供了精细控制，但陷阱在于：macOS 和 Windows 的菜单规范完全不同。我们最初照着文档写了个通用菜单，结果在 macOS 上，应用菜单（TypingGame）被塞进了右上角的系统菜单栏，而 Windows 用户却找不到“关于”和“退出”按钮。

正确的做法是分平台声明菜单模板。我们的 src/main/menu.ts 如下：

import { app, Menu, MenuItemConstructorOptions } from 'electron' const isMac = process.platform === 'darwin' const template: MenuItemConstructorOptions[] = [ // macOS 应用菜单 ...(isMac ? [{ label: app.name, submenu: [ { role: 'about' }, { type: 'separator' }, { role: 'services' }, { type: 'separator' }, { role: 'hide' }, { role: 'hideothers' }, { role: 'unhide' }, { type: 'separator' }, { role: 'quit' } ] }] : []), // 文件菜单（Windows/Linux） { label: 'File', submenu: [ isMac ? { role: 'close' } : { role: 'quit' } ] }, // 编辑菜单（跨平台） { label: 'Edit', submenu: [ { role: 'undo' }, { role: 'redo' }, { type: 'separator' }, { role: 'cut' }, { role: 'copy' }, { role: 'paste' }, ...(isMac ? [ { role: 'pasteAndMatchStyle' }, { role: 'delete' }, { role: 'selectAll' } ] : [ { role: 'delete' }, { type: 'separator' }, { role: 'selectAll' } ]) ] } ] const menu = Menu.buildFromTemplate(template) Menu.setApplicationMenu(menu)

这个模板的核心技巧是：用 isMac 变量动态切换子菜单结构，而不是写两套完全独立的菜单。它保证了 macOS 用户看到的是标准的 Apple 菜单（含 About、Services、Hide），Windows 用户看到的是传统 File/Edit 菜单。更关键的是，role: 'quit'在 macOS 下不会显示为菜单项（系统会自动处理 Cmd+Q），而在 Windows 下则显示为“Exit”，这种细节决定了用户的第一印象是否专业。

提示：不要在 renderer 进程里调用 Menu.setApplicationMenu()。Electron 文档明确警告，此方法必须在主进程调用，且只能调用一次。我们曾因在 renderer 的某个组件 mounted 钩子中误调用，导致应用启动后菜单栏空白，重启才恢复。

3. 核心模块实现详解：打字游戏的三大支柱如何落地

3.1 键盘事件精准捕获与 WPM 计算引擎

打字游戏的核心不是 UI，而是输入事件的毫秒级精度。浏览器原生的 keydown 事件在 Electron 中有两大隐患：一是 macOS 的 Cmd+Space 触发 Spotlight 时，keydown 会被系统劫持；二是某些机械键盘的 N-Key Rollover（NKRO）模式下，连续按键可能触发顺序错乱。我们的解决方案是绕过 DOM 事件，直接监听底层键盘输入。

Electron 提供了 globalShortcut 模块，但它只支持注册全局快捷键（如 Cmd+Q），不能捕获普通字符输入。真正的解法是使用 node-keyboard 三方库（注意：不是 keyboard，后者已废弃）。它通过 ffi-napi 调用系统 API，在 Windows 上用 GetAsyncKeyState，在 macOS 上用 CGEventTapCreate，在 Linux 上用 uinput。安装命令：

npm install node-keyboard # 注意：必须先安装 node-gyp 和 Python 3.10+ npm install --global --production windows-build-tools # Windows # macOS 需要 Xcode Command Line Tools xcode-select --install

在 preload.js 中桥接键盘监听：

// preload.js const { contextBridge } = require('electron') const Keyboard = require('node-keyboard') contextBridge.exposeInMainWorld('keyboard', { startListen: () => { const kb = new Keyboard() kb.on('keyDown', (key) => { // 过滤掉修饰键和系统快捷键 if (['Control', 'Meta', 'Alt', 'Shift'].includes(key)) return if (key === 'Escape') return // 避免干扰全屏 ipcRenderer.send('key-input', { key, timestamp: Date.now() }) }) }, stopListen: () => { // node-keyboard 没有 stop 方法，需自行管理实例 } })

renderer 进程中启用监听：

// src/renderer/composables/useKeyboard.ts import { onMounted, onUnmounted } from 'vue' export function useKeyboard() { const handleKeyInput = (event: Electron.IpcRendererEvent, payload: { key: string; timestamp: number }) => { // 将按键事件存入 Vuex 或 Pinia store store.commit('addKeystroke', payload) } onMounted(() => { window.keyboard.startListen() window.ipcRenderer.on('key-input', handleKeyInput) }) onUnmounted(() => { window.ipcRenderer.off('key-input', handleKeyInput) }) }

WPM（Words Per Minute）计算不再是简单的(charCount / 5) / (seconds / 60)。真实打字场景中，用户会回删、停顿、长按空格。我们的算法参考了 TypingClub 的标准：

一个“word”定义为 5 个字符（含空格和标点）
有效输入时间 = 从第一个非空格字符到当前时间，减去所有 > 2 秒的停顿间隙
回删（backspace）不计入错误，但删除的字符从总字数中扣除

// src/renderer/utils/wpmCalculator.ts export class WPMCalculator { private strokes: Array<{ key: string; timestamp: number }> = [] private startTime = 0 private lastActiveTime = 0 addStroke(key: string, timestamp: number) { this.strokes.push({ key, timestamp }) if (this.strokes.length === 1) { this.startTime = timestamp } this.lastActiveTime = timestamp // 检测停顿：如果当前时间 - 上次活跃时间 > 2000ms，则视为新段落 if (timestamp - this.lastActiveTime > 2000) { this.startTime = timestamp } } getWPM(): number { if (this.strokes.length === 0) return 0 const activeDuration = (this.lastActiveTime - this.startTime) / 1000 // 秒 if (activeDuration < 1) return 0 // 计算有效字符数：过滤掉 backspace，但计入其删除的字符 let charCount = 0 let deletedCount = 0 for (const stroke of this.strokes) { if (stroke.key === 'Backspace') { deletedCount++ } else if (stroke.key.length === 1) { charCount++ } } const netChars = Math.max(0, charCount - deletedCount) return Math.round((netChars / 5) / (activeDuration / 60)) } }

注意：node-keyboard 在打包时会引入原生模块，必须在 electron-builder 的 build.nodeGypRebuild 设置为 true，并在 package.json 的 build.files 中显式包含 node_modules/node-keyboard/**。否则生产环境会报错Cannot find module 'node-keyboard'。

3.2 词库动态加载与离线缓存策略

VSCode 插件的词库只能放在 extension 目录下，更新需用户手动升级插件。Electron 应用则可以实现真正的“在线词库热更新”。我们的方案是三级缓存：内存 > IndexedDB > 本地文件。

内存缓存：Vue 3 的 reactive 对象存储当前激活的词库，避免重复解析
IndexedDB：使用 idb 库（比原生 IDB API 更友好）缓存已下载的词库 JSON
本地文件：作为兜底，将词库存于 app.getPath('userData') 目录，路径为词库名.json

renderer 进程的词库加载逻辑：

// src/renderer/composables/useWordList.ts import { ref, computed } from 'vue' import { openDB } from 'idb' const dbPromise = openDB('typing-game-db', 1, { upgrade(db) { db.createObjectStore('wordlists', { keyPath: 'id' }) } }) export function useWordList() { const currentList = ref<WordList | null>(null) const isLoading = ref(false) const loadList = async (listId: string) => { isLoading.value = true try { // 1. 先查内存 if (currentList.value?.id === listId) return // 2. 再查 IndexedDB const db = await dbPromise const cached = await db.get('wordlists', listId) if (cached) { currentList.value = cached return } // 3. 最后请求网络 const res = await fetch(`https://api.typinggame.com/lists/${listId}`) const data = await res.json() currentList.value = data // 写入 IndexedDB await db.put('wordlists', data) } finally { isLoading.value = false } } return { currentList: computed(() => currentList.value), isLoading: computed(() => isLoading.value), loadList } }

主进程提供一个 IPC 接口，用于从本地文件加载词库（当网络不可用时）：

// src/main/ipcHandlers.ts import { app, ipcMain } from 'electron' import { promises as fs } from 'fs' import path from 'path' ipcMain.handle('load-wordlist-from-file', async (event, filename) => { const wordlistPath = path.join(app.getPath('userData'), 'wordlists', filename) try { const data = await fs.readFile(wordlistPath, 'utf8') return JSON.parse(data) } catch (e) { console.error('Failed to load wordlist from file:', e) throw new Error(`Wordlist ${filename} not found`) } })

这种策略让应用在断网时仍能运行，且首次加载后，后续启动几乎零延迟。我们测试过，在 200KB 的词库文件下，IndexedDB 查询平均耗时 3.2ms，比直接读文件快 17 倍。

3.3 SerialPort 硬件交互的安全桥接实现

“electron serialport” 是热搜词，但直接 npm install serialport 在 Electron 中会失败——因为 serialport 依赖 node-gyp 编译的 native 模块，而 renderer 进程默认禁用 Node.js 集成。正确路径是：serialport 只在主进程运行，renderer 通过 IPC 发送指令。

主进程初始化 serialport：

// src/main/serialHandler.ts import { SerialPort } from 'serialport' import { ReadlineParser } from '@serialport/parser-readline' import { app, ipcMain } from 'electron' let port: SerialPort | null = null let parser: ReadlineParser | null = null ipcMain.handle('serial-connect', async (event, options) => { try { port = new SerialPort({ path: options.path, baudRate: options.baudRate || 9600 }) parser = port.pipe(new ReadlineParser({ delimiter: '\n' })) parser.on('data', (data) => { event.reply('serial-data', data) }) return { success: true } } catch (e) { return { success: false, error: e.message } } }) ipcMain.handle('serial-write', async (event, data) => { if (!port) return { success: false, error: 'Not connected' } try { await port.write(data) return { success: true } } catch (e) { return { success: false, error: e.message } } })

renderer 进程调用：

// src/renderer/composables/useSerial.ts import { ref } from 'vue' export function useSerial() { const isConnected = ref(false) const connectionStatus = ref<string | null>(null) const connect = async (path: string) => { const result = await window.ipcRenderer.invoke('serial-connect', { path }) isConnected.value = result.success connectionStatus.value = result.success ? 'Connected' : result.error } const write = async (data: string) => { const result = await window.ipcRenderer.invoke('serial-write', data) return result } // 监听来自主进程的数据 window.ipcRenderer.on('serial-data', (event, data) => { console.log('Received from serial:', data) // 触发 Vue 事件或更新 store }) return { isConnected: computed(() => isConnected.value), connectionStatus: computed(() => connectionStatus.value), connect, write } }

重要安全提示：serial-connect 的 IPC 处理函数中，必须对 options.path 进行白名单校验。我们维护了一个允许的端口列表：['/dev/ttyUSB*', '/dev/cu.usbserial*', 'COM[1-9]*']，并用正则匹配。绝对禁止将用户输入的任意字符串直接传给 new SerialPort()，否则可能触发路径遍历或设备拒绝服务攻击。

4. 构建与发布全流程：从开发到用户安装的一站式实践

4.1 Vite + Electron Builder 的现代构建链路配置

放弃 electron-forge，拥抱 electron-builder 是 2024 年的共识。它的优势在于：配置即代码、多平台一键打包、自动签名（macOS）、UPX 压缩支持。关键配置文件是 package.json 中的 build 字段：

{ "build": { "appId": "com.typinggame.app", "productName": "TypingGame", "copyright": "Copyright © 2024 TypingGame Inc.", "artifactName": "${productName}-${version}-${platform}-${arch}.${ext}", "directories": { "output": "release" }, "files": [ "!node_modules/**/*", "!src/**/*", "!tests/**/*", "!*.ts", "!*.map", "!package-lock.json", "dist/**/*", "node_modules/serialport/**/*", "node_modules/@serialport/**/*", "node_modules/node-keyboard/**/*" ], "win": { "target": [ { "target": "nsis", "arch": ["x64", "ia32"] } ], "icon": "build/icon.ico" }, "mac": { "target": "dmg", "icon": "build/icon.icns", "hardenedRuntime": true, "gatekeeperAssess": false, "entitlements": "build/entitlements.mac.plist", "category": "public.app-category.games" }, "linux": { "target": "deb", "icon": "build/icon.png", "maintainer": "TypingGame Team", "vendor": "TypingGame Inc." } } }

这个配置的精妙之处在于files数组：它显式声明了哪些文件要被打包进最终安装包。注意"!node_modules/**/*"是排除所有 node_modules，但后面又单独列出了node_modules/serialport/**/*等必需的 native 模块。这是因为 electron-builder 默认不打包 native 模块，必须手动指定。如果漏掉 serialport，安装包运行时会报错Cannot find module 'serialport'。

构建命令只需一行：

npm run build # 它会依次执行： # 1. vite build --config vite.config.main.ts （构建主进程） # 2. vite build --config vite.config.renderer.ts （构建渲染进程） # 3. electron-builder （打包成安装包）

我们实测发现，electron-builder 的--publish=never参数在 CI 环境中至关重要。否则它会尝试上传到 GitHub Releases，导致构建失败。CI 脚本中应写为：

npm run build -- --publish=never

4.2 macOS 签名与公证（Notarization）避坑指南

macOS Catalina 之后，未签名的应用会被 Gatekeeper 拦截。签名不是可选项，而是上线前提。流程分三步：证书申请 → 代码签名 → 公证。

证书申请：在 Apple Developer Portal 申请 “Developer ID Application” 证书，下载后双击导入钥匙串。注意：必须用 Mac 生成 CSR，Windows 生成的证书在 macOS 上无效。
代码签名：electron-builder 会自动调用 codesign，但需在 build.mac 下配置 identity：

"mac": { "identity": "Developer ID Application: Your Company Name (XXXXXXXXXX)", "provisioningProfile": "build/embedded.provisionprofile" }

公证：这是最易出错的环节。electron-builder 的electron-notarize插件已过时。正确做法是用 Apple 提供的 notarytool：

# 打包后，对 dmg 文件进行公证 xcrun notarytool submit release/TypingGame-1.0.0-mac.dmg \ --key-id "YOUR_APPLE_ID" \ --key-secret "APP_SPECIFIC_PASSWORD" \ --key-issuer "ISSUER_ID" \ --wait

常见失败原因：

Bundle ID 不匹配：build.appId 必须和证书的 Bundle ID 完全一致（包括大小写）
Hardened Runtime 未启用：build.mac.hardenedRuntime 必须为 true
Entitlements 文件缺失：macOS 要求 entitlements.mac.plist 必须包含com.apple.security.cs.allow-jit（允许 JIT 编译，serialport 需要）

我们的 entitlements.mac.plist：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>com.apple.security.cs.allow-jit</key> <true/> <key>com.apple.security.cs.allow-unsigned-executable-memory</key> <true/> <key>com.apple.security.device.serial</key> <true/> </dict> </plist>

注意：com.apple.security.device.serial是让应用有权访问串口设备的关键权限，没有它，serialport.open() 会静默失败。

4.3 Windows NSIS 安装包的自定义与用户体验优化

NSIS（Nullsoft Scriptable Install System）是 electron-builder 默认的 Windows 打包器。默认安装包太简陋——没有启动菜单项、没有桌面快捷方式、卸载后残留文件。我们通过自定义 nsis 脚本解决：

在 package.json 的 build.win 下添加：

"win": { "target": [ { "target": "nsis", "arch": ["x64"] } ], "nsis": { "oneClick": false, "allowToChangeInstallationDirectory": true, "installerIcon": "build/icon.ico", "uninstallerIcon": "build/icon.ico", "installerHeaderIcon": "build/icon.ico", "createDesktopShortcut": true, "createStartMenuShortcut": true, "shortcutName": "TypingGame", "include": "build/installer.nsh" } }

然后创建 build/installer.nsh：

!macro customInstall ; 创建桌面快捷方式 CreateShortCut "$DESKTOP\TypingGame.lnk" "$INSTDIR\TypingGame.exe" "" "$INSTDIR\resources\app.asar.unpacked\build\icon.ico" 0 ; 创建开始菜单快捷方式 CreateShortCut "$SMPROGRAMS\TypingGame.lnk" "$INSTDIR\TypingGame.exe" "" "$INSTDIR\resources\app.asar.unpacked\build\icon.ico" 0 ; 写入注册表，方便后续升级检测 WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\TypingGame" "DisplayName" "TypingGame" WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\TypingGame" "DisplayVersion" "${APP_VERSION}" WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\TypingGame" "Publisher" "TypingGame Inc." WriteRegStr HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\TypingGame" "DisplayIcon" "$INSTDIR\TypingGame.exe" !macroend !macro customUnInstall ; 卸载时删除快捷方式 Delete "$DESKTOP\TypingGame.lnk" Delete "$SMPROGRAMS\TypingGame.lnk" ; 删除注册表项 DeleteRegKey HKLM "Software\Microsoft\Windows\CurrentVersion\Uninstall\TypingGame" !macroend

这个脚本确保用户安装后，桌面和开始菜单都有图标，且卸载干净。我们还发现一个隐藏坑：NSIS 默认把安装路径设为C:\Program Files\TypingGame，但中文系统下，Program Files目录名可能是程序文件，导致路径解析失败。解决方案是在 nsis.script 中强制使用英文路径：

InstallDir "$PROGRAMFILES64\TypingGame"

5. 常见问题与实战排查技巧：那些文档里不会写的坑

5.1 渲染进程白屏与 DevTools 黑屏的终极诊断法

Electron 应用启动白屏，90% 的原因是 preload.js 加载失败或 contextBridge 暴露异常。但错误不会显示在页面上，只会藏在主进程日志里。快速诊断法：

启动时加 --remote-debugging-port=9222 参数：
```
npm run dev -- --remote-debugging-port=9222
```
然后打开 Chrome 访问http://localhost:9222，能看到所有渲染进程的 DevTools，即使页面白屏也能调试。
检查 preload.js 是否被正确注入：在 renderer 的 index.html 中，确认 script 标签存在且路径正确：
```
<script src="./preload.js"></script>
```
如果用 Vite，这个标签由 @vitejs/plugin-electron-renderer 自动注入，但需确保 vite.config.renderer.ts 中的 build.outDir 和 electron-main.js 中的 mainWindow.loadFile() 路径匹配。
验证 contextBridge 是否生效：在 renderer 的 console 中执行：
```
console.log(window.api) // 应该是 object console.log(window.require) // 应该是 undefined（被禁用）
```
如果 window.api 是 undefined，说明 preload.js 没执行，或 contextBridge.exposeInMainWorld() 调用位置错误（必须在 preload.js 的顶层作用域）。

实操心得：我们曾遇到一个诡异问题——开发时一切正常，打包后白屏。最终发现是 Vite 的 build.sourcemap 设为 false 导致的。因为 production 模式下，Vite 会压缩代码，而某些 minify 工具（如 terser）会把 contextBridge.exposeInMainWorld 的调用优化掉。解决方案：在 vite.config.renderer.ts 中显式设置build.sourcemap: 'inline'，确保 source map 内联，避免压缩破坏 API 暴露。

5.2 SerialPort 在不同系统上的兼容性陷阱

serialport 在 Windows 上最稳定，在 macOS 上常因权限问题失败，在 Linux 上则可能因 udev 规则缺失无法识别设备。逐个击破：

macOS 权限问题：用户首次连接 USB 设备时，系统会弹窗要求授权。但如果应用是通过 dmg 安装的，且未签名，授权窗口可能被拦截。解决方案：在 entitlements.mac.plist 中加入com.apple.security.device.serial，并确保应用已公证。

Linux 设备识别：Ubuntu 默认不允许普通用户访问/dev/ttyUSB*。必须添加 udev 规则：

echo 'SUBSYSTEM=="usb-serial", MODE="0666", GROUP="dialout"' | sudo tee /etc/udev/rules.d/99-serial.rules sudo udevadm control --reload-rules sudo usermod -a -G dialout $USER

然后重启电脑。否则 serialport.list() 返回空数组。

Windows 驱动冲突：某些 CH340 芯片的 Arduino 克隆版，在 Windows 10/11 上需要手动安装驱动。electron-builder 打包时，无法自动安装驱动。我们的应对策略是：在应用内嵌一个“驱动检测”模块，用 child_process.exec('pnputil /enum-drivers') 检查 CH340 驱动是否存在，不存在则引导用户去官网下载。