原文项目：钟毓英语衡水体字帖生成器
重构前后：PyQt6 v1.1.1 → Electron v2.0.x（跨平台 Windows / macOS / Linux）
关键词：electron-vite、Canvas 2D、tesseract.js OCR、electron-builder、pickle 兼容、Bottles 交叉打包

前言

笔者手上有一款用 PyQt6 开发的英语衡水体字帖生成器，功能挺全乎：四种生成模式（描红/抄写/描红+抄写/字帖）、两种线格、多标签页、PDF 导出，还有个自定义的 .zyecb 工程文件格式。原版在 Windows 上跑得好好的，可架不住用户问"Linux 有吗"、“mac 能装吗”——Python 桌面应用的分发短板一下就暴露了：PyInstaller 体积大、跨平台得各开一台机器、系统库依赖分分钟给你整出兼容玄学。

得，那就用 Electron 彻底重构吧。本文不整"为什么选 Electron"这种正确的废话，直接上干货：构建思路怎么定的、关键决策怎么做的、以及踩过的那些真实坑和最终怎么爬出来的。正在折腾桌面应用重构的朋友，希望能帮你少走点弯路。

---

一、整体架构与技术选型

1.1 技术栈

层面	选型	说明
构建工具	electron-vite 2 + Vite 5	主/预加载/渲染进程统一构建，HMR 香得很
运行时	Electron 33.4.11	直接上 33，别问，问就是被 Node 20.14 坑过（见第六节坑 4）
渲染	原生 JavaScript + Canvas 2D	无框架，直接复刻 QPainter 自绘逻辑
打包	electron-builder 24.13.3	NSIS / AppImage / deb / rpm / dmg / zip 一网打尽
OCR	tesseract.js v7	截图识别，语言数据内置，离线可用

1.2 目录与多入口设计

原版就是个单窗口 QMainWindow 套 QTabWidget。到了 Electron 这边，我把"全屏自绘"的场景拆成了独立 HTML 入口，各司其职：

src/
├── main/          主进程：IPC、窗口、菜单、打印、OCR
├── preload/       contextBridge 桥
└── renderer/
    ├── index.html     主界面（标签页 + 控件 + 预览 Canvas）
    ├── print.html     隐藏窗口：渲染 A4 页面供 PDF 导出 / 打印
    ├── sel.html       截图选区窗口（每显示器一个，全屏无边框）
    └── preview.html   打印预览窗口

四个入口在 electron.vite.config.mjs 的 rollupOptions.input 里注册。这种"按全屏场景拆入口"的设计，比在单个 BrowserWindow 里切视图清爽多了——打印和预览窗口本来就不需要主界面那一堆控件。

1.3 逐像素对齐原版：别瞎优化

重构桌面应用，最忌讳的就是"顺手优化一下"，结果用户一打开感觉"这味儿不对啊"。我的策略很简单：页面坐标系、字号、颜色、行高全部一比一复刻。

• 页面尺寸 800×1131px，边距 (20, 20, 760, 1091)，头部高 100；

• 四线三格行高 40、组距 40（线位 y+0/13/26/39），单横线行高 30、组距 0；

• QFont 的 pt 字号按 96 DPI 换算：px = pt × 4/3；

• 描红色 #ff6464、网格线 #c0c0c0、页码 #a0a0a0。

排版引擎集中在 src/renderer/src/engine/copybook.js 的 buildPages，一次排版分页。顺带还修了原版一个潜伏 bug：单横线模式下原版按四线三格行高估算页容量，跨页时单词会重复出现，重构版按实际行高算就好了——算是重构附赠的彩蛋。

---

二、工程文件双向兼容：pickle 这个老顽童

原版的 .zyecb 工程文件是 Python pickle（Py3 默认协议 4）。老用户迁移是刚需，新版必须能读；要让用户在新旧版本间自由切换，新版存的文件原版最好也能打开。

2.1 读取：手写协议 0~4 子集解析器

pickle 本质是个基于栈的虚拟机字节码。我吭哧吭哧手写了一个解析器，把常用 opcode 都覆盖了：PROTO、STOP、MARK、EMPTY_LIST/DICT/TUPLE、APPEND、SETITEM、BINUNICODE、SHORT_BINUNICODE、GLOBAL、REDUCE 等等，协议 4 的 FRAME、MEMOIZE 也没落下。这活儿不复杂但碎，建议边对照 pickletools.dis() 的输出边写，事半功倍。

2.2 写入：用协议 0，但小心 \uXXXX

输出我选了 协议 0（纯 ASCII），任何 Python 版本都能读，出问题了肉眼也能 debug。

这里有个能把人逼疯的坑：协议 0 里字符串 opcode V 后面跟一行以 \n 结尾的 raw-unicode-escape 字符串。Python 的 raw-unicode-escape 只认 \uXXXX 形式的转义，不认 \n、\\ 这种简写。所以字符串里的换行、反斜杠、控制符必须全部编码成 \u000a、\u005c 等形式，否则原版 pickle.load 轻则 UnicodeDecodeError，重则读到一堆乱码。

2.3 回归测试

双向跑一遍：

• 原版保存一批典型工程（特殊字符、空内容、长文本都来点）→ 新版打开；

• 新版保存 → 原版打开；

• 断言渲染结果一字不差。

最终实现了真正的双向兼容，用户双击 .zyecb 就能用新版打开（通过 electron-builder 的 fileAssociations 注册文件关联）。

---

三、打印与打印预览：一条管线走天下

原版"导出 PDF"和"打印"走的是 QPrinter。到了 Electron，我把这两条路合并成一条渲染管线，再额外加了个"打印预览"窗口——毕竟都 2026 年了，没预览的打印是不完整的。

3.1 三路复用的渲染窗口

主进程 ipc.js 抽出 createRenderWindow(data)：

1. 建一个隐藏的 BrowserWindow，加载 print.html；

2. IPC 把排版数据塞过去，渲染进程用 Canvas 2D 按 A4 尺寸逐页画；

3. 画完了 IPC 回报，主进程按 sender id 过滤（多窗口串消息这种事，防一手），设个 30s 超时兜底；

4. 根据调用场景分流：

   • pdf:export → webContents.printToPDF；

   • print:direct → webContents.print 弹系统打印对话框；

   • print:preview → 复用单例预览窗口显示。

打印参数统一为 { printBackground: true, pageSize: 'A4', margins: { marginType: 'none' } }。划重点：新版 Electron 用 margins 对象，旧的 marginsType 已经被打入冷宫。

3.2 高清渲染：2 倍 DPR

A4 页面按 2 倍 DPR（192 DPI） 绘制（794×1123 @96dpi 的 2 倍），打出来的字边缘那叫一个锐利。打印和 PDF 共用同一份 Canvas 数据，效果完全一致，用户再也不会说"PDF 看着挺好，打出来糊了"。

3.3 打印预览窗口的那些小细节

• 单例复用：重复打开就 focus + 重渲染，别傻乎乎每次新建窗口；

• 渲染完再 show()：不然用户看到白屏闪烁，体验分骤降；

• setMenu(null)：非 macOS 下附加窗口默认带应用菜单栏，必须手动清掉，不然预览窗口顶个文件编辑帮助菜单怪尴尬的；

• CSS zoom 缩放：别用 transform: scale，zoom 是参与 Chromium 布局计算的，滚动条和页码定位才对得上；

• "适应页宽"算法：zoom = (clientWidth - 两侧留白) / 794，794 是 A4 宽 @96dpi 的像素值；

• 页码跟随滚动：用 getBoundingClientRect 找"最后一个 top ≤ 视口 35% 的页"当当前页。别问我为什么知道——初版用 current++ 写了个差一 bug，翻第一页显示"第 2/2 页"，当场社死。

3.4 Linux 下验证的小坑

在 deepin 上做自动化验证时发现一个有意思的现象：GTK 打印对话框打开期间，父窗口渲染进程的 JS 被模态阻塞了，CDP Runtime.evaluate 直接超时，对话框一关立马恢复。所以测试时系统对话框那块（选打印机、点确认）得交给 xdotool，应用内交互（点预览按钮、拖缩放）才能用 CDP。

另外 xdotool 在 GTK 保存对话框里 type 路径会被输入法劫持，斜杠还会被吃掉，解决方案是测试导出时先接受默认文件名，事后再改回去。

---

四、截图识别：desktopCapturer + tesseract.js

光有手动输入哪够，必须上个截图识别——看到屏幕上的英文直接框一下就进字帖，多香。

4.1 完整流程走一遍

1. 主窗口先藏起来；

2. desktopCapturer.getSources({ types: ['screen'] }) 截屏，thumbnailSize 设成显示器物理尺寸 × scaleFactor，HiDPI 下才不会糊；

3. 每个显示器弹一个全屏无边框 alwaysOnTop 选区窗口（sel.html），复用主 preload；

4. 用户拖框选（宽高 < 8px 当误触处理），Enter 或双击确认、Esc 取消；

5. 裁出的 dataURL 经 IPC 扔给主进程的 tesseract.js；

6. 识别结果用 document.execCommand('insertText', false, text) 回填输入框——这样能保留原生撤销栈，还能自动触发 input 事件联动预览。

4.2 双击确认的交互坑

写的时候踩了个挺隐蔽的 bug：拖出选区后双击居然确认不了。一通 debug 发现，双击的第一次 mousedown 命中了已有选区，代码把选区重置成了一个点，到 dblclick 时选区宽高已经是 0 了，自然啥也确认不了。

修复很简单：mousedown 时如果点落在已有选区内，不重置选区，只记个起始点，把确认的机会留给 dblclick。改完 Enter 确认、双击确认、Esc 取消就各司其职了。

4.3 HiDPI 坐标换算

screen API 返回的是 DIP 尺寸（125% 缩放下 1536×864），但截图是物理像素（1920×1080）。选区坐标到图像坐标的换算就一句：sx = image.naturalWidth / window.innerWidth（也就是 scaleFactor），裁剪时 x * sx、y * sy 就行。

4.4 tesseract.js 在主进程跑

• createWorker(lang, 1, { langPath, cachePath, logger: () => {} })，worker 按语言 Map 缓存，别每次识别都新建；

• 输入用 Buffer（dataURL 先转 Buffer）；

• 语言数据用 tessdata_fast 的 .gz，丢 resources/ocr-data 里，通过 extraResources 内置，打包后路径是 process.resourcesPath/ocr-data；

• 必须在 package.json 的 dependencies 里（externalizeDepsPlugin 会把主进程依赖外部化，运行时从 node_modules require）；

• 重依赖懒加载：别在主进程入口顶层 import，首次调用时再 await import('tesseract.js')——这是第六节"四个致命坑"之一，白屏闪退的元凶。

官方 tessdata.projectnaptha.com 直连会重置连接，换 cdn.jsdelivr.net/gh/tesseract-ocr/tessdata_fast 下 plain 文件再本地 gzip 即可。

---

五、多平台打包：electron-builder 全攻略

5.1 基础配置

{"win": { "target": "nsis", "icon": "resources/app_icon.ico" },"nsis": {
    "oneClick": false,
    "allowToChangeInstallationDirectory": true,
    "createDesktopShortcut": true},"mac": {
    "target": ["dmg", "zip"],
    "icon": "resources/app_icon.icns",
    "artifactName": "${name}-${version}-${arch}.${ext}"},"linux": {
    "target": ["AppImage", "deb", "rpm"],
    "icon": "resources/icons",
    "maintainer": "Your Name <email@example.com>",
    "artifactName": "${name}-${version}-${arch}.${ext}"}}

几个要点：

• maintainer 必须带 email，不然 deb 构建给你报个莫名其妙的错；

• artifactName 用 ${name} 保持 ASCII 文件名（Windows 除外，默认按 productName 中文命名）；

• linux.icon 指向多尺寸目录而不是单张 PNG（原因见坑 3）。

5.2 架构支持矩阵

平台	x64	arm64	riscv64
Windows NSIS	✅	✅（合并包）	❌
Linux AppImage/deb/rpm	✅	✅（交叉）	❌
macOS dmg/zip	✅	✅	❌

• Linux 交叉打 arm64：npx electron-builder --linux AppImage deb rpm --arm64；

• Windows NSIS 不指定 --x64 时默认打 x64+arm64 双架构合并安装包（安装时让用户自选架构）；

• riscv64 没官方 Electron 二进制，死心吧。

5.3 Linux 上交叉打 Windows NSIS（无系统 wine，用 flatpak Bottles）

本机装不了系统级 wine，退而求其次用 flatpak 的 Bottles：

1. flatpak install flathub com.usebottles.bottles

2. 建 bottle：bottles-cli new --bottle-name builder --environment application --arch win64

3. 沙箱网络是个大坑：bottles 组件从 github 下，沙箱默认不走 host socks5 代理；Python requests 还缺 SOCKS 支持 → pip download PySocks（纯 py wheel）解到 bottles 能访问的目录，建 bottle 时加 --env=PYTHONPATH=... --env=https_proxy=socks5h://x.x.x.x:port

4. 新 wine（soda runner 11.x）wow64 合并了，只有 wine 没有 wine64，而且 standalone 是个 bash 脚本不是二进制

5. 写个 wine 包装器（wine 和 wine64 都软链到它）：

   export LD_LIBRARY_PATH=<runner>/lib:<runner>/lib/wine/x86_64-unix:<runner>/lib/wine/i386-unix
   export WINEPREFIX=<bottle路径>export PATH=<runner>/bin:$PATHexec <runner>/bin/wine "$@"

6. PATH=/tmp/eb-wine:$PATH npx electron-builder --win nsis --publish never

实测验证：rcedit（exe 版本信息能塞中文产品名）、makensis 都正常，还能在 bottle 里 Setup.exe /S 静默安装走一遍流程。

5.4 Linux 上出 macOS zip

dmg-license 是 macOS 专属可选依赖，Linux 上装不上（原生库 invalid ELF header）。绕法：npm i --no-save dmg-license --force 然后把它的 index.js 替换成 module.exports = {} 桩模块（zip 目标只 require 不调用）。dmg 必须在 macOS 上构建（要 hdiutil），Linux 上没办法。完事 npm prune 清掉。

5.5 rpm 4.20 环境的特殊处理

本机 rpm 4.20 和 electron-builder 内置的 fpm 1.9.3 八字不合：fpm 传的 --define buildroot X 被 rpm 4.20 当空气，结果就是 “File not found”。解法：写个 rpmbuild 包装器，把 --define buildroot X 翻译成 4.20 还认的 --buildroot X，构建时 PATH 前置。

另外非 root 跑需要用户级 rpmdb：rpm --initdb 初始化 ~/.cache/rpmdb，在 ~/.rpmmacros 写 %_dbpath /home/<user>/.cache/rpmdb，不然会报 /var/lib/rpm/rpmdb.sqlite 打不开。

---

六、四个致命的打包坑（真实用户机器上栽过的跟头）

这节是全文最有含金量的部分——这四个问题本地开发压根测不出来，都是打包后扔到真实用户环境才现原形的。

坑 1：Windows 安装后白屏闪退

现象：安装一切正常，双击快捷方式，窗口一闪而过，连个错误日志都不给你留。

根因：src/main/ocr.js 顶层写了 import { createWorker } from 'tesseract.js'，构建产物在主进程入口变成 require("tesseract.js")，某些打包/系统环境下初始化失败，直接闪退白屏。

修复：改成函数内 await import('tesseract.js') 懒加载，首次用到 OCR 时才加载。

教训：主进程顶层永远别 import 重依赖，这条记住能救命。

坑 2：deepin/UOS 装 deb 报 EXDEV 硬链接错误

现象：dpkg: 错误：新建硬链接 ... 无效的跨设备链接 (EXDEV)。

根因：app_icon.png 既当 extraResources（装到 /opt/…/resources/）又当 linux.icon（装到 /usr/share/icons/hicolor/），electron-builder staging 阶段用 hardlink 复制，fpm 1.9.3 把硬链接写进 tar（条目类型 h）。deepin/UOS 这类不可变系统 /opt 和 /usr 是不同挂载点，dpkg 解包时 link() 跨设备直接失败。

冷知识：fpm 1.9.3 没有 --deb-no-hardlinks 选项（1.10+ 才有），配 deb.fpm 会直接构建失败，别在这上面浪费时间。

根治：图标别放 extraResources，打进 app.asar（files 里加 "resources/app_icon.png"），打包后 join(__dirname, '../../resources/app_icon.png')，nativeImage 支持 asar 路径，三平台通吃。这样 hicolor 成了唯一物理文件，硬链接条目数直接归零。

验证方法：

• deb：ar x pkg.deb && tar tvf data.tar.* | grep -c '^h'

• rpm：rpm2archive pkg.rpm | tar tv | grep -c '^h'

坑 3：Linux 图标显示"未知类型"占位图

现象：deb 装上了，启动器里应用图标是个灰色的"未知类型"占位图，丑得离谱。

根因：linux.icon 给单张 PNG 时，electron-builder 只把它扔到 /usr/share/icons/hicolor/0x0/apps/。0x0 不符合 hicolor-icon-theme 规范，deepin/UOS 的启动器直接不索引。

修复：弄个多尺寸图标目录 resources/icons/，塞进去 16/24/32/48/64/128/256/512 的 NxN.png（用 PIL LANCZOS 从 256px 源图生成，512 是放大的），linux.icon 指向这个目录，构建后就装到各 hicolor/<size>/apps/ 了。

验证：模拟 XDG 数据目录后用 GTK Gtk.IconTheme.get_default().lookup_icon(name, 256, 0) 能解析出来。注意 offscreen 下 PyQt 的 QIcon.fromTheme 连系统图标都查不到，别拿它验证，纯属浪费时间。

坑 4：Windows 12 代+ Intel 大小核 CPU 上 Node 初始化崩溃

现象：Windows 11 真机装完打不开（退出码 0），但同一个安装包扔 VirtualBox Win10 里跑得欢，VS Code 等其他 Electron 应用在这台机器上也正常。

根因：Electron 31 内置的 Node 20.14 在 Intel 大小核混合 CPU（12 代及以后）上调 GetLogicalProcessorInformationEx 枚举处理器组时缓冲区越界，直接 fatal。

修复：升级到 Electron 33.4.11（Node 20.18，修了这 bug）。少数处理器组信息异常的机器，还得检查 BIOS 或 Windows 启动参数（bcdedit 里的 groupsize/maxgroup/numproc/usegroup）。

教训：新项目直接 Electron ≥33，别给自己找麻烦。

---

七、菜单助记符的跨平台玄学

这是个小坑但烦人的很。Electron 的菜单在 Linux GTK 和 Windows 上，对 (&X) 的处理还不一样：

• 顶层菜单：(&F) 会被整体从显示文本剥离，只注册 Alt 助记符——所以顶层得双写 `文件(F)(&F)`，才能既显示 (F) 又有 Alt+F；

• 子菜单项：只剥 & 符号本身，新建(&N) 显示带下划线的 N，原生写法就行；

• && → 字面 &（不注册助记符）；_ 在 GTK 不当下划线语法，原样显示。

封装两个 helper 一劳永逸：

const topMenuLabel = (text, key) => `${text}(${key})(&${key})`const itemLabel = (text, key, suffix = '') => `${text}(&${key})${suffix}`

---

八、没有商业 UI 测试工具？这套组合拳顶用

deepin 上做验证，没有付费测试工具，全靠开源凑：

• CDP：--remote-debugging-port=9223，临时装个 ws 包（Node 20 没全局 WebSocket）写脚本，Runtime.evaluate 读 DOM/canvas 像素、Input.dispatchKeyEvent 驱动应用内按键；

• xdotool：负责 GTK 原生对话框（菜单导航 key --delay 200 alt+f，不加 delay 菜单丢键）；

• Pillow：ImageGrab.grab(xdisplay=':0') 截图（物理分辨率，坐标按像素算）；

• tkinter：造 OCR 测试素材——overrideredirect + topmost 置顶窗显示已知文本，setsid nohup 启动防 shell 退出连带杀进程，文字四周留足 padding，不然贴边字母识别错；

• pkill 技巧：pkill -f 的模式如果匹配到自身命令行会自杀，用 [x] 括号技巧，比如 pkill -f '[e]lectron .'。

---

九、总结

从 PyQt6 到 Electron 的重构，最大的收获是跨平台分发能力的质变：一套代码产出 Windows NSIS、Linux AppImage/deb/rpm、macOS zip/dmg，OCR、打印、文件关联这些原生能力也都齐活。代价嘛，就是得重新适应浏览器环境下的渲染、IPC、打包模型。

几个扎心的经验：

1. 逐像素对齐原版是桌面应用重构的第一原则，别擅自"优化"用户已经习惯的视觉；

2. 文件格式双向兼容是迁移的生命线，pickle 协议 0 写入的 \uXXXX 坑一定要绕开；

3. 主进程顶层不 import 重依赖，一律懒加载，白屏闪退能防一大半；

4. 打包坑全在真实环境暴露：EXDEV 硬链接、hicolor 0x0 图标、Intel 大小核崩溃——这些本地开发永远测不出来，必须上目标系统验；

5. 打印预览要单例、渲染完再 show、记得清菜单，细节决定体验。

重构这趟下来，感觉 Electron 做桌面应用其实没网上传的那么不堪，关键是别把它当网页写，得有"桌面应用"的意识——窗口生命周期、系统对话框、原生菜单、文件关联，一个都不能少。

希望这篇踩坑记录能帮到正在做类似重构的你。有问题欢迎评论区开麦 🎤