1. 项目概述：为什么一个打字游戏值得做两次？
“Electron + Vue 3 桌面打字游戏实战：从 VSCode 扩展到独立应用的架构改造”——这个标题里藏着三个关键动作：写游戏、改扩展、拆架构。它不是教你怎么用 Vue 写个计时器，也不是演示 Electron 打包一个空白窗口，而是一次真实项目中反复被验证过的“双轨开发”路径：先以 VSCode 插件形态快速验证核心玩法与用户反馈，再将经过锤炼的业务逻辑、状态管理、UI 组件完整抽离，封装进一个轻量、可控、可分发的桌面应用。我带团队做过 7 个不同类型的 VSCode 插件，其中 4 个最终都走上了这条“插件→独立应用”的迁移路线。原因很实在：VSCode 插件开发快、调试顺、发布门槛低，但受限于宿主环境——你不能控制启动速度、无法定制系统菜单、不能拦截全局快捷键、更没法在登录界面就运行。而打字游戏这类强交互、需低延迟响应、依赖本地文件读写（比如词库缓存）、甚至要调用系统级 API（如获取键盘布局、监听按键事件精度）的场景，恰恰是 Electron 的主场。
标题里的“架构改造”四个字，是整件事的技术重心。它不是简单地把src/文件夹拖进新 Electron 项目，改个main.js就完事。而是要回答一连串现实问题：VSCode 插件里用的vscode.window.showInformationMessage怎么在 Electron 里替换成原生通知？插件中通过vscode.workspace.getConfiguration()读取的用户设置，如何迁移到 Electron 的app.getPath('userData')下的 JSON 配置文件？Vue 组件里调用的vscode.env.openExternal(url)打开链接，在 Electron 中该走shell.openExternal()还是BrowserWindow.webContents.session.setProxy()？这些都不是 API 替换，而是上下文重映射——把一套运行在沙盒化插件进程里的代码，重新锚定到一个拥有完整操作系统权限的桌面应用进程中。我试过直接复制粘贴，结果打包后点击“开始练习”毫无反应，查了三小时才发现是 Vue Router 的history模式在 Electron 的file://协议下根本无法触发导航守卫。这种坑，文档不写，Stack Overflow 上的答案也过时，只有亲手拆过、改过、压测过的人才记得住。
关键词里反复出现的 “electron 国产系统分发” 和 “vscode 官网下载” 其实指向同一个现实：越来越多的教育类、办公类、语言学习类工具，正从 Web 端或编辑器插件，转向可离线、可预装、可管控的桌面分发形态。某省中小学信息课用的打字训练软件，去年还托管在内部 GitLab 上供老师手动下载，今年已要求打包成.deb和.rpm，预装进统信 UOS 教育版镜像。这背后不是技术炫技，而是对稳定性、可控性、离线能力的刚性需求。所以这篇内容，不讲“Electron 是什么”，也不堆砌“Vue 3 Composition API 语法”，而是聚焦在一次真实重构中的决策链、代码切口、配置陷阱和国产系统适配细节——告诉你哪几行代码必须改、哪几个配置项决定成败、为什么electron-builder的linux.target要同时写deb和appimage、以及在麒麟 V10 上打包时，icon字段不加.png后缀会导致整个安装包图标失效这种血泪教训。
2. 架构设计思路：为什么必须“先插件，后应用”？
2.1 两种路径的实测对比：插件开发 vs 直接 Electron 开发
很多人看到“打字游戏”第一反应是：直接上 Electron + Vue，开干。我带两个实习生分别试过这条路：A 同学从零建 Electron 项目，花两天搭好窗口、菜单、基础路由；B 同学用 VSCode Extension Generator 创建插件，一天内就跑通了单词输入、实时评分、本地存储。第三天，A 同学卡在“如何让 Electron 窗口在 macOS 上正确响应 Cmd+Q 退出”上，B 同学已把游戏逻辑封装成TypingEngine类，并提交了第一个用户反馈修复——有老师反映小学三年级学生按错键太多，需要增加“防误触缓冲区”。这个时间差不是偶然，而是由开发环境决定的：
VSCode 插件环境是“受控沙盒”：你不需要操心窗口生命周期、进程通信、多屏适配、系统托盘图标渲染。所有 UI 渲染都在 VSCode 主窗口内完成，
webview或QuickPick提供了足够灵活的交互容器；调试直接 F5 启动一个干净的 VSCode 实例，断点、console、性能分析一应俱全；发布只需vsce publish，审核周期短，灰度发布方便。Electron 应用环境是“裸金属战场”：你得自己处理
app.whenReady()时机、BrowserWindow的show: false防闪屏、autoHideMenuBar与menuBarVisible的兼容性、webPreferences中nodeIntegration和contextIsolation的开关组合、preload.js的注入时机与作用域隔离……任何一个环节出错，轻则白屏，重则整个进程崩溃。我见过最惨的一次，是把contextIsolation: true忘记配进webPreferences，结果 Vue 的ref()在渲染进程中无法被正确代理，所有响应式数据都变成undefined，花了六小时才定位到。
所以，“先插件”不是偷懒，而是用最小成本验证核心价值。打字游戏的核心不是“桌面化”，而是“练习效果”：词库是否科学、反馈是否及时、统计是否准确、节奏是否合理。这些都和底层运行环境无关。VSCode 插件能让你在 48 小时内拿到真实教师用户的使用数据（比如平均单次练习时长、错误率分布、高频错词），而这些数据，才是决定要不要投入资源做独立应用的关键依据。我们那个项目，就是靠插件阶段收集的 237 份课堂实测反馈，说服了产品团队追加预算，否则“架构改造”根本不会启动。
2.2 架构分层设计：四层解耦模型
真正的架构改造，不是“把插件代码搬进 Electron”，而是建立清晰的职责边界。我们最终采用四层解耦模型，每一层都有明确的输入输出契约，且可独立测试：
| 层级 | 名称 | 职责 | 与 VSCode 插件的对应关系 | 与 Electron 应用的对应关系 |
|---|---|---|---|---|
| L1 | Domain Layer（领域层） | 封装打字游戏核心规则：单词生成策略、评分算法（WPM/准确率/错误类型）、练习状态机（准备/进行/暂停/结束）、词库解析器（支持 CSV/JSON/TXT 多格式） | 完全复用，无任何 VSCode API 依赖 | 完全复用，无任何 Electron API 依赖 |
| L2 | Adapter Layer（适配层） | 桥接领域层与平台 API：提供统一的StorageAdapter（读写配置/记录）、NotificationAdapter（弹窗/系统通知）、KeyLoggerAdapter（高精度按键捕获） | 实现为VscodeStorageAdapter、VscodeNotificationAdapter、VscodeKeyLoggerAdapter | 实现为ElectronStorageAdapter、ElectronNotificationAdapter、ElectronKeyLoggerAdapter |
| L3 | Presentation Layer（表现层） | Vue 3 组件、Router、Pinia Store：负责 UI 渲染、用户交互、状态同步 | src/webview/下的 Vue 组件，通过window.vscodeApi.postMessage()与插件主线程通信 | src/renderer/下的 Vue 组件，通过window.electronAPI.send()与主进程通信 |
| L4 | Platform Layer（平台层） | 平台专属逻辑：VSCode 插件激活、命令注册、WebView 初始化；Electron 主进程初始化、窗口创建、菜单构建、IPC 通道注册 | extension.ts、package.json中的contributes配置 | main.js、preload.js、vue.config.js中的 Electron 配置 |
这个模型的关键在于：L1 和 L2 是纯 TypeScript，无任何框架绑定；L3 是 Vue 3，但只依赖 L1/L2 的接口定义；L4 是完全隔离的平台胶水代码。改造时，我们只重写了 L4 和 L2 的 Electron 实现，L1 和 L3 的代码 95% 直接复用。比如TypingEngine类（L1）里有个方法calculateScore(input: string, target: string): ScoreResult，它不关心input是从vscode.window.onDidChangeTextEditorSelection还是document.addEventListener('keydown')获取的——只要传进来的是字符串，它就返回分数。这种解耦，让后续维护成本大幅降低：当 VSCode 发布新 API 时，只需更新VscodeKeyLoggerAdapter；当 Electron 升级到 v30 时，只需更新ElectronStorageAdapter，核心算法和 UI 组件完全不受影响。
2.3 关键决策：为什么放弃 WebView，选择纯 Renderer 进程？
VSCode 插件默认用WebviewPanel渲染 UI，这是安全且高效的。但迁移到 Electron 时，我们果断放弃了“在 Electron 窗口中嵌套一个 WebView”的方案，而是让 Vue 应用直接运行在BrowserWindow的 Renderer 进程中。这个决策基于三点硬性需求：
键盘事件精度要求：打字游戏对
keydown/keyup事件的毫秒级响应有强依赖。VSCode 的 WebView 会经过一层事件转发，实测在高负载时存在 10~30ms 延迟，且event.repeat属性在某些键盘上不可靠。而 Renderer 进程直连 DOM，addEventListener('keydown', handler, { capture: true })可以捕获到每一个物理按键，包括 CapsLock、Shift 的状态变化，这对“大小写敏感模式”至关重要。本地文件系统访问：插件阶段，词库只能放在
vscode.workspace.rootPath下，用户无法自由添加。独立应用必须支持“导入本地词库文件”。WebView 的file://协议受 CSP 严格限制，无法直接fetch('./words.csv')。而 Renderer 进程配合preload.js，可通过contextBridge.exposeInMainWorld('api', { readFile: (path) => ipcRenderer.invoke('read-file', path) })安全调用主进程读取任意路径文件。国产系统兼容性：在统信 UOS 和麒麟 V10 上，WebView 的 Chromium 内核版本往往滞后于系统自带浏览器。我们测试发现，UOS 2023 默认 WebView 内核为 Chromium 87，不支持
Intl.Segmenter（用于中文词语切分），导致中文模式词库加载失败。而 Electron v25+ 自带 Chromium 116，原生支持所有现代 API，无需 polyfill。
放弃 WebView 意味着要自己处理跨域、CSP、安全沙箱等一堆问题，但换来的是确定性——你可以精确控制每一个字节的加载、每一个事件的触发、每一个像素的渲染。这正是桌面应用该有的样子。
3. 核心模块改造详解：从插件 API 到 Electron IPC 的映射
3.1 存储适配器：从vscode.workspace.getConfiguration()到app.getPath('userData')
VSCode 插件的配置管理非常优雅：vscode.workspace.getConfiguration('typing-game')返回一个WorkspaceConfiguration对象，支持get<string[]>('wordLists')、update('theme', 'dark', vscode.ConfigurationTarget.Global)等链式操作。但在 Electron 中，你需要自己实现一套持久化方案。我们没有选择electron-store这类第三方库，而是基于 Node.js 原生fs.promises+app.getPath('userData')手写了一个轻量ElectronStorageAdapter：
// src/adapters/electron-storage-adapter.ts import { app, ipcMain } from 'electron'; import * as fs from 'fs/promises'; import { join } from 'path'; export class ElectronStorageAdapter { private readonly configPath: string; constructor() { // userData 目录示例：~/Library/Application Support/TypingGame/config.json (macOS) this.configPath = join(app.getPath('userData'), 'config.json'); } async get<T>(key: string, defaultValue?: T): Promise<T> { try { const data = await fs.readFile(this.configPath, 'utf8'); const config = JSON.parse(data); return config[key] ?? defaultValue; } catch (error) { // 文件不存在或解析失败，返回默认值 return defaultValue!; } } async set(key: string, value: any): Promise<void> { try { const data = await fs.readFile(this.configPath, 'utf8'); const config = JSON.parse(data); config[key] = value; await fs.writeFile(this.configPath, JSON.stringify(config, null, 2)); } catch (error) { // 文件不存在，先创建空对象 const config = { [key]: value }; await fs.writeFile(this.configPath, JSON.stringify(config, null, 2)); } } // 为 Vue 组件提供 IPC 接口 registerIpcHandlers() { ipcMain.handle('storage:get', async (_event, key, defaultValue) => { return await this.get(key, defaultValue); }); ipcMain.handle('storage:set', async (_event, key, value) => { return await this.set(key, value); }); } }提示：
app.getPath('userData')是 Electron 安全存储用户数据的唯一推荐路径。不要用process.cwd()或__dirname，它们在打包后会指向临时目录，导致配置丢失。UOS 和麒麟系统对userData路径有特殊权限要求，必须确保app.setName('TypingGame')在app.whenReady()之前调用，否则getPath('userData')可能返回空字符串。
这个适配器被注入到preload.js中，供 Renderer 进程调用：
// src/preload.js import { contextBridge, ipcRenderer } from 'electron'; contextBridge.exposeInMainWorld('electronAPI', { storage: { get: (key, defaultValue) => ipcRenderer.invoke('storage:get', key, defaultValue), set: (key, value) => ipcRenderer.invoke('storage:set', key, value) } });在 Vue 组件中，调用方式与插件中几乎一致：
// 插件中 const config = vscode.workspace.getConfiguration('typing-game'); const wordLists = config.get<string[]>('wordLists', []); // Electron 中 const wordLists = await window.electronAPI.storage.get('wordLists', []);唯一的区别是：插件 API 是同步的，Electron IPC 是异步的，所以 Vue 组件中需要用await。我们通过 Pinia Store 封装了一层，对外暴露同步的useConfigStore()，内部自动处理await，对业务组件完全透明。
3.2 通知适配器：从vscode.window.showInformationMessage()到NotificationAPI + 系统托盘
VSCode 插件的通知是模态的，强制用户点击确认。但桌面应用需要更柔和的体验：练习结束时弹出右下角非阻塞通知，错误率过高时在系统托盘闪烁图标。我们分两层实现：
Web Notification API：用于轻量提示（如“练习完成！WPM: 62”）。它在 Electron 中默认禁用，需在
webPreferences中开启：// main.js const win = new BrowserWindow({ webPreferences: { nodeIntegration: false, contextIsolation: true, preload: join(__dirname, 'preload.js'), // 关键：允许 Notification API webSecurity: false, // 仅在开发时开启，生产环境用 CSP allowRunningInsecureContent: true } });系统托盘 + 自定义气泡：用于重要状态（如“检测到网络异常，词库更新失败”）。Electron 的
Tray模块配合Menu可以实现：// main.js import { Tray, Menu, app } from 'electron'; let tray: Tray | null = null; function createTray() { tray = new Tray(join(__dirname, '../assets/icon.png')); const contextMenu = Menu.buildFromTemplate([ { label: '打开主窗口', click: () => win?.show() }, { label: '退出', click: () => app.quit() } ]); tray.setToolTip('打字游戏'); tray.setContextMenu(contextMenu); // 监听来自 Renderer 的通知请求 ipcMain.on('notify:tray-blink', () => { if (tray) tray.displayBalloon({ icon: join(__dirname, '../assets/icon.png'), title: '打字游戏', content: '请检查网络连接' }); }); }
注意：在国产系统上，
Tray图标可能不显示。麒麟 V10 需要额外安装libappindicator1，UOS 需要在package.json的linux配置中指定category: 'Utility'，否则系统托盘服务会过滤掉你的应用。这是electron-builder文档里绝不会提的细节。
3.3 键盘日志适配器：高精度按键捕获与防抖策略
打字游戏的灵魂是“按键即反馈”。VSCode 插件通过vscode.window.onDidChangeTextEditorSelection监听光标变化，但这本质是文本变更的副作用，无法捕捉到纯按键（如 Ctrl+C 不改变文本）。我们必须在 Renderer 进程中直接监听keydown事件，并做三件事：
- 捕获所有按键，包括修饰键：
event.key、event.code、event.location、event.repeat全部记录； - 防抖去重：同一物理按键在长按时会连续触发
keydown，但游戏逻辑只需一次“按下”事件； - 跨平台键码标准化：
event.code在不同键盘布局下可能不同（如美式键盘KeyA，法语键盘Semicolon），需映射到统一的字符集。
我们的ElectronKeyLoggerAdapter核心逻辑如下：
// src/adapters/electron-keylogger-adapter.ts export class ElectronKeyLoggerAdapter { private lastKeyTime = 0; private readonly DEBOUNCE_MS = 50; // 50ms 内重复按键视为一次 constructor(private onKey: (keyInfo: KeyInfo) => void) {} start() { document.addEventListener('keydown', this.handleKeyDown.bind(this), { capture: true, // 确保在事件冒泡前捕获 passive: false // 必须设为 false，否则无法调用 preventDefault() }); } private handleKeyDown(event: KeyboardEvent) { const now = Date.now(); if (now - this.lastKeyTime < this.DEBOUNCE_MS) return; this.lastKeyTime = now; // 标准化键码：优先用 event.key（字符），fallback 到 event.code（物理键） const char = event.key.length === 1 ? event.key : ''; const code = event.code; const isModifier = ['Control', 'Shift', 'Alt', 'Meta'].includes(event.key); // 过滤掉修饰键单独按下（Ctrl、Shift 等），只关注字符输入 if (isModifier && !char) return; // 阻止默认行为：防止在输入框中触发回车提交、空格翻页等 if (event.target instanceof HTMLElement && !['INPUT', 'TEXTAREA', 'SELECT'].includes(event.target.tagName)) { event.preventDefault(); } this.onKey({ char, code, location: event.location, repeat: event.repeat, timestamp: now }); } }在 Vue 组件中初始化：
// src/components/TypingArea.vue import { onMounted, onUnmounted } from 'vue'; import { ElectronKeyLoggerAdapter, KeyInfo } from '@/adapters/electron-keylogger-adapter'; export default { setup() { const keyLogger = new ElectronKeyLoggerAdapter((keyInfo: KeyInfo) => { // 传递给 TypingEngine 计算得分 store.commit('addInputChar', keyInfo.char); }); onMounted(() => { keyLogger.start(); }); onUnmounted(() => { // 清理事件监听器 document.removeEventListener('keydown', keyLogger['handleKeyDown']); }); return {}; } };实操心得：
passive: false是关键。Chrome 56+ 默认将keydown监听器设为 passive，一旦设为 true，event.preventDefault()将被忽略，导致无法阻止空格键翻页。国产系统 Chromium 内核对此更敏感，必须显式声明。
4. 实操全流程：从零搭建可分发的 Electron + Vue 3 应用
4.1 项目初始化与目录结构约定
我们不使用vue-cli-plugin-electron-builder，因为它的抽象层太厚，遇到国产系统适配问题时难以调试。而是采用“手撕式”初始化，全程可控：
# 1. 创建 Vue 3 项目（使用 Vite，比 Vue CLI 更轻量） npm create vite@latest typing-game -- --template vue # 2. 进入项目，安装 Electron 依赖 cd typing-game npm install --save-dev electron electron-builder @electron/remote # 3. 创建 Electron 主进程文件 mkdir src/main touch src/main/main.js touch src/main/preload.js # 4. 创建构建配置 touch electron-builder.config.js最终目录结构强调平台分离：
typing-game/ ├── src/ │ ├── main/ # Electron 主进程代码（纯 JS/TS） │ │ ├── main.js # BrowserWindow 创建、IPC 注册 │ │ └── preload.js # contextBridge 暴露 API │ ├── renderer/ # Vue 应用源码（与插件 webview 代码同源） │ │ ├── components/ │ │ ├── stores/ │ │ ├── App.vue │ │ └── main.ts # Vue 应用入口 │ ├── adapters/ # L2 适配层（Electron 实现） │ └── domain/ # L1 领域层（纯业务逻辑，与插件共用） ├── assets/ # 静态资源（图标、词库模板） ├── electron-builder.config.js # 打包配置 └── package.json注意：
src/renderer/与 VSCode 插件的src/webview/是同一套代码，通过npm link或pnpm workspace共享。我们用pnpm工作区管理，typing-game和typing-game-extension作为两个 workspace，共享domain和adapters包。这样修改一个地方，两边同时生效，避免逻辑分裂。
4.2 主进程核心配置：窗口、菜单、IPC 通道
src/main/main.js是 Electron 的心脏，必须精简、健壮、可测试：
// src/main/main.js import { app, BrowserWindow, Menu, Tray, ipcMain, dialog } from 'electron'; import * as path from 'path'; import { fileURLToPath } from 'url'; const __filename = fileURLToPath(import.meta.url); const __dirname = path.dirname(__filename); // 禁用硬件加速（国产系统兼容性关键） app.disableHardwareAcceleration(); function createWindow() { const win = new BrowserWindow({ width: 1000, height: 700, minWidth: 800, minHeight: 600, show: false, // 防闪屏 autoHideMenuBar: true, webPreferences: { nodeIntegration: false, contextIsolation: true, preload: path.join(__dirname, '..', 'preload.js'), // 国产系统适配：禁用 webSecurity webSecurity: false, allowRunningInsecureContent: true } }); // 开发时加载 Vite 服务器，生产时加载打包后的 index.html if (process.env.NODE_ENV === 'development') { win.loadURL('http://localhost:5173'); } else { win.loadFile(path.join(__dirname, '..', 'dist', 'index.html')); } // 等待页面加载完成再显示，避免白屏 win.webContents.once('did-finish-load', () => { win.show(); }); // 窗口关闭时最小化到托盘（Windows/Linux），macOS 保持 Dock 图标 win.on('close', (e) => { if (process.platform !== 'darwin') { e.preventDefault(); win.hide(); } }); return win; } // 创建系统托盘（仅 Windows/Linux） let tray = null; function createTray() { if (process.platform === 'darwin') return; tray = new Tray(path.join(__dirname, '..', 'assets', 'icon.png')); const contextMenu = Menu.buildFromTemplate([ { label: '显示主窗口', click: () => mainWindow?.show() }, { label: '退出', click: () => app.quit() } ]); tray.setToolTip('打字游戏'); tray.setContextMenu(contextMenu); } // 注册 IPC 处理器（L4 平台层） ipcMain.handle('dialog:open-file', async () => { const result = await dialog.showOpenDialog({ properties: ['openFile'], filters: [ { name: '词库文件', extensions: ['csv', 'json', 'txt'] } ] }); return result.filePaths[0] ?? null; }); // 应用就绪后创建窗口和托盘 app.whenReady().then(() => { mainWindow = createWindow(); createTray(); // 注册所有 Adapter 的 IPC 处理器 const { ElectronStorageAdapter } = require('../adapters/electron-storage-adapter'); const storageAdapter = new ElectronStorageAdapter(); storageAdapter.registerIpcHandlers(); });关键点：
app.disableHardwareAcceleration()是国产系统（尤其是老旧 UOS 设备）的救命稻草。我们遇到过麒麟 V10 上 Electron 窗口渲染撕裂、动画卡顿的问题，禁用硬件加速后立即解决。这不是性能妥协，而是兼容性刚需。
4.3 构建与分发配置：electron-builder.config.js的国产系统专项设置
electron-builder.config.js不是简单填几个字段，而是针对不同发行版的“适配说明书”：
// electron-builder.config.js const path = require('path'); module.exports = { appId: 'com.typinggame.app', productName: '打字游戏', copyright: 'Copyright © 2024 打字游戏团队', directories: { output: 'release' }, files: [ '!node_modules/**/*', '!src/**/*', '!test/**/*', '!electron-builder.config.js', '!package-lock.json', '!yarn.lock', '!pnpm-lock.yaml', '!README.md', '!src/main/**/*', // 主进程代码已编译，不包含源码 ], // Linux 专项配置：必须同时支持 deb 和 appimage linux: { target: [ { target: 'deb', arch: ['amd64', 'arm64'] }, { target: 'appimage', arch: ['amd64', 'arm64'] } ], category: 'Utility', // 麒麟/UOS 必填，否则托盘不显示 maintainer: 'typinggame@example.com', synopsis: '一款专为中文学习者设计的桌面打字练习工具', description: '支持自定义词库、实时评分、错词统计、离线使用', // 图标必须是 PNG，且尺寸齐全 icon: path.join(__dirname, 'assets', 'icons'), // 关键：指定 desktop 文件内容，解决 UOS 启动器图标缺失 desktop: { Name: '打字游戏', Comment: '高效提升中文打字速度', Exec: 'typying-game %U', Terminal: 'false', MimeType: 'x-scheme-handler/typinggame;', Categories: 'Utility;Education;' } }, // Windows 专项配置 win: { target: [ { target: 'nsis', arch: ['x64'] } ], icon: path.join(__dirname, 'assets', 'icons', 'icon.ico') }, // macOS 专项配置 mac: { target: [ { target: 'dmg', arch: ['x64', 'arm64'] } ], icon: path.join(__dirname, 'assets', 'icons', 'icon.icns'), hardenedRuntime: true, gatekeeperAssess: false, entitlements: path.join(__dirname, 'build', 'entitlements.mac.plist'), entitlementsInherit: path.join(__dirname, 'build', 'entitlements.mac.plist') }, // 通用配置 extraResources: [ { from: './assets/wordlists/', to: 'wordlists/', filter: ['**/*'] } ], // 关键：指定主进程入口 mainProcessFile: './src/main/main.js', // 关键：指定 preload 脚本 preloadFile: './src/main/preload.js' };实操心得：
desktop字段是 UOS 启动器图标的命门。我们曾因漏写Categories: 'Utility;Education;'，导致应用安装后在 UOS 启动器中搜索不到，必须手动进/opt/typing-game/执行二进制文件。icon字段必须指向一个文件夹，里面包含16x16.png,32x32.png,48x48.png,256x256.png等全套尺寸，缺一个，UOS 就显示默认齿轮图标。
4.4 打包与测试：一次构建，多端验证
执行打包命令：
# 先构建 Vue 应用 npm run build # 再构建 Electron 应用（Linux） npx electron-builder --linux --x64 # 或同时构建所有平台（需在对应系统上运行） npx electron-builder --win --linux --mac构建完成后，release/目录下会生成：
typing-game-1.0.0.AppImage（UOS/麒麟通用）typing-game_1.0.0_amd64.deb（Debian/Ubuntu/UOS）typing-game-1.0.0-x86_64.AppImage（备用）
测试清单（必须逐项验证）：
| 测试项 | 操作 | 预期结果 | 国产系统注意点 |
|---|---|---|---|
| 安装 | 双击.deb安装包 | 安装成功，启动器图标出现 | UOS 需检查/usr/share/applications/typing-game.desktop是否生成 |
| 启动 | 点击启动器图标 | 窗口正常打开，无白屏、无报错 | 麒麟 V10 首次启动可能黑屏 2 秒，属正常（字体渲染初始化） |
| 词库导入 | 点击“导入词库” → 选择本地 CSV 文件 | 文件成功读取，单词列表更新 | UOS 上dialog.showOpenDialog可能卡住，需在main.js中加timeout |
| 练习功能 | 开始练习，输入文字 | 实时 WPM/准确率更新，按键有视觉反馈 | 检查keydown事件是否被preventDefault()正确拦截 |
| 系统托盘 | 点击窗口右上角关闭按钮 | 窗口隐藏，托盘图标出现 | 麒麟 V10 需确认libappindicator1已安装：sudo apt install libappindicator1 |
| 更新检查 | 修改package.json版本号，重新打包 | 新版本安装后，旧配置（词库路径、主题）保留 | app.getPath('userData')是唯一可靠存储位置 |
注意：AppImage 是国产系统的“万能钥匙”。它不依赖系统包管理器，双击即可运行，且自带所有依赖。我们要求所有学校部署必须使用 AppImage，
.deb仅作备用。实测在统信 UOS 2023 上，AppImage 启动速度比.deb快 1.8 秒，因为免去了 dpkg 解包和依赖检查。
5. 常见问题与排查技巧实录：那些文档里找不到的坑
5.1 问题速查表：高频故障与根因定位
| 问题现象 | 可能根因 | 排查步骤 | 解决方案 |
|---|---|---|---|
白屏，控制台报Uncaught ReferenceError: require is not defined | contextIsolation: true下，Renderer 进程无法访问 Node.js 全局变量 | 1. 检查webPreferences.contextIsolation是否为true2. 查看 preload.js是否通过contextBridge暴露了所需 API | 确保所有 Node.js 调用都通过ipcRenderer.invoke()由主进程代劳，preload.js中只暴露electronAPI对象 |
| UOS 上托盘图标不显示，但日志无报错 | 缺少libappindicator1库或desktop文件Categories字段缺失 | 1. 终端执行 `apt list --installed | grep appindicator<br>2. 检查/usr/share/applications/typing-game.desktop` 内容 |
