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 上正确响应 CmdQ 退出”上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 应用的对应关系L1Domain Layer领域层封装打字游戏核心规则单词生成策略、评分算法WPM/准确率/错误类型、练习状态机准备/进行/暂停/结束、词库解析器支持 CSV/JSON/TXT 多格式完全复用无任何 VSCode API 依赖完全复用无任何 Electron API 依赖L2Adapter Layer适配层桥接领域层与平台 API提供统一的StorageAdapter读写配置/记录、NotificationAdapter弹窗/系统通知、KeyLoggerAdapter高精度按键捕获实现为VscodeStorageAdapter、VscodeNotificationAdapter、VscodeKeyLoggerAdapter实现为ElectronStorageAdapter、ElectronNotificationAdapter、ElectronKeyLoggerAdapterL3Presentation Layer表现层Vue 3 组件、Router、Pinia Store负责 UI 渲染、用户交互、状态同步src/webview/下的 Vue 组件通过window.vscodeApi.postMessage()与插件主线程通信src/renderer/下的 Vue 组件通过window.electronAPI.send()与主进程通信L4Platform 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 进程直连 DOMaddEventListener(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对象支持getstring[](wordLists)、update(theme, dark, vscode.ConfigurationTarget.Global)等链式操作。但在 Electron 中你需要自己实现一套持久化方案。我们没有选择electron-store这类第三方库而是基于 Node.js 原生fs.promisesapp.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 getT(key: string, defaultValue?: T): PromiseT { 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): Promisevoid { 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.getstring[](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 需要额外安装libappindicator1UOS 需要在package.json的linux配置中指定category: Utility否则系统托盘服务会过滤掉你的应用。这是electron-builder文档里绝不会提的细节。3.3 键盘日志适配器高精度按键捕获与防抖策略打字游戏的灵魂是“按键即反馈”。VSCode 插件通过vscode.window.onDidChangeTextEditorSelection监听光标变化但这本质是文本变更的副作用无法捕捉到纯按键如 CtrlC 不改变文本。我们必须在 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一旦设为 trueevent.preventDefault()将被忽略导致无法阻止空格键翻页。国产系统 Chromium 内核对此更敏感必须显式声明。4. 实操全流程从零搭建可分发的 Electron Vue 3 应用4.1 项目初始化与目录结构约定我们不使用vue-cli-plugin-electron-builder因为它的抽象层太厚遇到国产系统适配问题时难以调试。而是采用“手撕式”初始化全程可控# 1. 创建 Vue 3 项目使用 Vite比 Vue CLI 更轻量 npm create vitelatest 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/LinuxmacOS 保持 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: typinggameexample.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.AppImageUOS/麒麟通用typing-game_1.0.0_amd64.debDebian/Ubuntu/UOStyping-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 definedcontextIsolation: 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 --installedgrep appindicatorbr2. 检查/usr/share/applications/typing-game.desktop 内容
Electron+Vue3桌面打字游戏：VSCode插件到独立应用的架构迁移实战
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 上正确响应 CmdQ 退出”上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 应用的对应关系L1Domain Layer领域层封装打字游戏核心规则单词生成策略、评分算法WPM/准确率/错误类型、练习状态机准备/进行/暂停/结束、词库解析器支持 CSV/JSON/TXT 多格式完全复用无任何 VSCode API 依赖完全复用无任何 Electron API 依赖L2Adapter Layer适配层桥接领域层与平台 API提供统一的StorageAdapter读写配置/记录、NotificationAdapter弹窗/系统通知、KeyLoggerAdapter高精度按键捕获实现为VscodeStorageAdapter、VscodeNotificationAdapter、VscodeKeyLoggerAdapter实现为ElectronStorageAdapter、ElectronNotificationAdapter、ElectronKeyLoggerAdapterL3Presentation Layer表现层Vue 3 组件、Router、Pinia Store负责 UI 渲染、用户交互、状态同步src/webview/下的 Vue 组件通过window.vscodeApi.postMessage()与插件主线程通信src/renderer/下的 Vue 组件通过window.electronAPI.send()与主进程通信L4Platform 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 进程直连 DOMaddEventListener(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对象支持getstring[](wordLists)、update(theme, dark, vscode.ConfigurationTarget.Global)等链式操作。但在 Electron 中你需要自己实现一套持久化方案。我们没有选择electron-store这类第三方库而是基于 Node.js 原生fs.promisesapp.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 getT(key: string, defaultValue?: T): PromiseT { 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): Promisevoid { 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.getstring[](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 需要额外安装libappindicator1UOS 需要在package.json的linux配置中指定category: Utility否则系统托盘服务会过滤掉你的应用。这是electron-builder文档里绝不会提的细节。3.3 键盘日志适配器高精度按键捕获与防抖策略打字游戏的灵魂是“按键即反馈”。VSCode 插件通过vscode.window.onDidChangeTextEditorSelection监听光标变化但这本质是文本变更的副作用无法捕捉到纯按键如 CtrlC 不改变文本。我们必须在 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一旦设为 trueevent.preventDefault()将被忽略导致无法阻止空格键翻页。国产系统 Chromium 内核对此更敏感必须显式声明。4. 实操全流程从零搭建可分发的 Electron Vue 3 应用4.1 项目初始化与目录结构约定我们不使用vue-cli-plugin-electron-builder因为它的抽象层太厚遇到国产系统适配问题时难以调试。而是采用“手撕式”初始化全程可控# 1. 创建 Vue 3 项目使用 Vite比 Vue CLI 更轻量 npm create vitelatest 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/LinuxmacOS 保持 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: typinggameexample.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.AppImageUOS/麒麟通用typing-game_1.0.0_amd64.debDebian/Ubuntu/UOStyping-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 definedcontextIsolation: 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 --installedgrep appindicatorbr2. 检查/usr/share/applications/typing-game.desktop 内容
