告别老旧 Qt/wke 外壳！键盘小鹿如何用 Electron + Vue 3 同构桌面免安装版与 Web 在线版？

一、 为什么必须推翻旧版 Qt/wke 外壳？——第一性原理剖析

国内众多打字训练软件的历史可以追溯到上世纪 90 年代或 PC 互联网初期。在漫长的技术演进中，大部分项目为了兼顾 Windows XP 等老旧系统，长期依赖基于 WebKit 早期分支裁剪出的微内核（如 wke、Miniblink）或 C++ Qt 4/5 混合方案。随着现代 Web 技术与操作系统生态的发展，这种旧架构暴露出了致命的物理瓶颈：

• QtCore -> |复杂 IPC 序列化| WkeView
• QtCore -> |逻辑漂移 / 无法共享| WebVer
• UnifiedSrc -> ViteDesktop
• UnifiedSrc -> ViteWeb
• ViteDesktop -> WinClient["Windows ia32 绿色免安装包<br>(解压即用 / 零弹窗)"]
• ViteWeb -> NginxWeb["Web 在线端 (keydeer.cn/online)<br>(免安装 / 跨设备即开即练)"]
• 1. 渲染内核老化与现代 CSS 规范缺失： 早期裁剪版 WebKit 内核受限于体积，移除了大量现代浏览器标准： - 无法原生支持现代排版：不支持 CSS Grid、Flexbox 高级特性、Subgrid 以及针对不同屏幕分辨率的容器查询（Container Queries）； - 动画硬件加速缺失：不支持 GPU 驱动的 CSS transform3d 硬件合流、Canvas 双缓冲与 WebGL 2.0，导致虚拟键盘敲击动效、指法呼吸引导灯与粒子动效出现明显的掉帧与卡顿； - 现代 JavaScript 特性受限：不支持 ES2022+ 语法，无法直接使用可选链（Optional Chaining）、空值合并（Nullish Coalescing）以及异步迭代器，必须经过繁琐的 Babel 转译与 Polyfill 垫片，反而引入了额外的运行期开销。
• 2. 双轨开发契约漂移与“重复造轮子”： 在旧模式下，产品如果同时提供桌面版与网页端，通常由两套团队或两拨代码独立开发： - 桌面端用 C++ 写了一套按键拦截、退格判定、打字速度（KPM/WPM）与准确率算法； - Web 端为了在浏览器中运行，又用原生 JavaScript 或老旧 jQuery 重新实现了一套判定逻辑； - 业务逻辑漂移灾难：一旦教研团队需要微调“退格键是否计入击键总数”或“中文拼音候选词确认判定规则”，两端逻辑极易出现不一致，导致同一用户在客户端与网页端测试出的成绩产生巨大偏差，破坏测评公信力。
• 3. 分发包袱重与运行环境地狱： 传统 Windows 客户端严重依赖特定的 Visual C++ Redistributable（VC 运行库）或系统全局动态链接库（DLL）。用户在没有管理员权限的校园多媒体机房、企事业单位机房解压后，经常遭遇 MSVCR120.dll 缺失 或 0xc000007b 应用程序无法正常启动 等崩溃报错，客服支持成本极其高昂。

二、 键盘小鹿双端同构设计核心规范与选型矩阵

为了彻底根治上述顽疾，键盘小鹿研发团队确立了核心架构演进路线：以 Web 前端标准为单一真理源（Single Source of Truth），通过 Electron 赋予桌面端底层特权，通过 Vite 驱动双轨高精度同构编译。

核心技术方案横向评测：

三、 双轨编译管线与条件摇树实现

键盘小鹿在工程中维护同一套业务代码目录 src/，通过配置化的打包入口分离桌面与网页两种交付目标：

// electron.vite.config.ts 桌面端同构打包核心配置
import { defineConfig, externalizeDepsPlugin } from 'electron-vite'
import vue from '@vitejs/plugin-vue'
import { resolve } from 'node:path'

export default defineConfig({
  main: {
    plugins: [externalizeDepsPlugin()],
    build: {
      rollupOptions: {
        input: {
          index: resolve(__dirname, 'electron/main/index.ts')
        },
        output: {
          entryFileNames: '[name].js'
        }
      }
    }
  },
  preload: {
    plugins: [externalizeDepsPlugin()],
    build: {
      rollupOptions: {
        input: {
          index: resolve(__dirname, 'electron/preload/index.ts')
        },
        output: {
          entryFileNames: '[name].js'
        }
      }
    }
  },
  renderer: {
    resolve: {
      alias: {
        '@': resolve(__dirname, 'src'),
        'csd-public': resolve(__dirname, 'csd-public/src')
      }
    },
    define: {
      __IS_ELECTRON__: true,
      __KEYDEER_VERSION__: JSON.stringify(process.env.npm_package_version || '2.0.0')
    },
    plugins: [vue()]
  }
})

• 1. 桌面端构建契约（electron.vite.config.ts）： 在桌面端，Electron 分为主进程（Main Process）、预加载脚本（Preload Script）与渲染层（Renderer Process）。配置的核心在于：主进程与预加载脚本使用 Rollup 外部化所有 Node 原生模块，渲染层则注入跨平台别名与专有上下文。
• 2. Web 在线端构建契约（vite.web.config.ts）： 在纯浏览器 Web 环境下，任何直接对 Node.js（如 node:fs、node:path）或 Electron（electron.ipcRenderer）的静态导入都会引发浏览器运行时报错。我们通过在 Web 构建时注入条件常量 __IS_ELECTRON__: false，并借助 Vite 的 Rollup 摇树（Tree-Shaking）机制剔除所有主进程桥接逻辑：

四、 统一平台感知抽象层（Platform-Aware Abstraction Layer）

业务组件若到处充满 if (__IS_ELECTRON__) 分支，会导致业务代码严重污染、难以维护。键盘小鹿构建了单一咽喉抽象层，将所有操作系统交互与浏览器特有 API 归一化为跨平台服务接口：

!键盘小鹿键位指法与工作台实机截图

• 1. 数据持久化策略统一抽象： - 桌面端：依托 Electron 主进程特权，将用户档案、错键记录与星星徽章保存在 %APPDATA%\keydeer\learning_records.json 中，即使电脑断网，也能获得毫秒级且不受浏览器容量限制的读写支持； - Web 端：无缝降级到现代浏览器的 IndexedDB + LocalStorage 双级缓存中。当网络通畅时，通过 Outbox 队列异步推送至云端 API 同步进度。
• 2. 窗口控制与沉浸式全屏： - 桌面端：采用无边框（Frameless）窗口设计，渲染层自绘具备 Mac/Windows 双风格的胶囊标题栏，通过 IPC 与主进程 BrowserWindow 通信完成最大化、最小化和拖拽； - Web 端：检测到 __IS_ELECTRON__ === false 时，自动平滑隐藏窗口关闭与最小化按钮，并将全屏按钮绑定至浏览器的 document.documentElement.requestFullscreen()，为孩子提供不受其他网页干扰的沉浸式训练环境。

五、 实战踩坑复盘：双端同构工程中的三大边界陷阱

在长达两年的双端架构迭代中，我们攻克了多项容易被忽视但影响重大的底层缺陷：

• 1. 坑点一：Web 端静态资源打包后的相对路径陷阱： 在 Electron 中，通常使用 file:// 特权协议直接加载本地编译产物 index.html；而在 Web 端，资源往往托管在 CDN 的子路径（如 /online/）下。若在 Vite 中将 base 简单写死为 '/'，桌面版直接加载会出现白屏找不到 JS/CSS 的严重故障。 解决方案：采用动态 Base 适配器。桌面构建强制使用 './' 相对路径，Web 构建则从环境变量 VITE_PUBLIC_PATH 读取绝对 CDN 路径。
• 2. 坑点二：Electron 渲染进程内存泄漏与 DOM 节点孤岛： 打字软件在练习过程中会频繁销毁和重绘几百个带有彩色呼吸灯与拼音注音的键位 DOM 节点。在 Electron 下，若直接将 Vue 组件与原生事件监听器强绑定（如全局 window.addEventListener('keydown')），会导致组件卸载后仍然无法被 V8 垃圾回收，长时间运行内存可从 110MB 飙升至 500MB+。 解决方案：引入统一的事件调度中心（Event Bus），并结合 Vue 3 的 onBeforeUnmount 钩子对虚拟键盘绑定的所有定时器、RAF（RequestAnimationFrame）与按键捕获函数做防御性双清。
• 3. 坑点三：Web Audio 自动播放策略对双端的差异化拦截： 现代浏览器（Chrome、Edge、Safari）均启用了严格的 Autoplay Policy：在用户发生首次点击或按键手势之前，AudioContext 默认被挂起（suspended），此时若强行调用 play() 会抛出 DOMException 异常并导致音效死锁；而在 Electron 环境中，我们可以通过配置 Chromium 启动开关放行受信任音频。 解决方案：设计音频就绪状态机（Audio Ready State Machine）。在纯 Web 端，首次进入页面时拦截音频播放，并在用户点击“开始测评”或敲击首个字符时，触发一次 audioContext.resume() 优雅解锁，确保音画完全同步。

六、 生产成果与性能对比看板

通过推翻旧版 Qt/wke 外壳、全面采用 Electron + Vue 3 双端同构方案，键盘小鹿取得了显著的工程与产品收益：