Electron 打包模式对比分析：base-electron vs electron-build

对比对象：base-electron 分支与 electron-build 分支

【定论 · 2026-08-22 更新】基于当前分支改造：搬入 base-electron 的声明式打包（electron-builder）+ 全仓 TypeScript；支持麒麟 + 资源自定义，代码保护须做加固（不接受破解）。详见「零、定论」。

零、定论（2026-08-22）：采用 base-electron，代码保护须加固

底座采用 base-electron（electron-builder 声明式链路）；代码保护按新需求做加固、不接受破解（否则离线 License 的验签逻辑暴露在可解包 JS 里，License 形同虚设）；并澄清 electron-build 与 base-electron 在 Linux/麒麟侧同源。

0.1 结论

采用 base-electron，五条依据：

1. 麒麟系统支持 ✅（0.2）：electron-builder 的 linux.target 原生支持 deb/rpm/AppImage，覆盖银河麒麟（Debian/Ubuntu 系）、中标麒麟（CentOS 系）与信创 arm64。
2. 打包资源自定义支持 ✅（0.2）：extraResources/extraFiles/asarUnpack/files 满足 FFmpeg、Rust .node、License 公钥等自定义注入。
3. 代码保护另行加固（0.3）：base-electron 原生 asar 可被 asar extract 解包，不满足「不接受破解」，需移植 electron-build 的加固能力。
4. electron-build 与 base-electron 在 Linux/麒麟同源（0.4）：electron-build 的 Linux 出包本就调用 electron-builder，只有 Windows 才额外走 Inno。
5. 基于当前分支改造：搬入 base-electron 的声明式打包 + 全仓 TypeScript（0.5）：base-electron 值钱的只有三个小片段（TS 主进程骨架、electron-builder.json 声明式配置、vite-plugin-electron 集成），半天即可抄进当前分支；当前分支的地基（monorepo、依赖栈、packages、业务 UI）是健康的，问题只在打包层与语言层，应原地翻新而非换分支重建。语言采用 TypeScript，与 PRD §4.5/§7.2、技术架构 §7.2 一致。

0.2 两个能力确认：麒麟 + 资源自定义

麒麟系统支持 ✅

electron-builder linux.target 支持 deb / rpm / AppImage / tar.gz / snap / flatpak：

麒麟发行版	基座	出包格式
银河麒麟 V10	Ubuntu / Debian	deb（或通用 AppImage）
中标麒麟	CentOS	rpm（或通用 AppImage）
信创（飞腾/鲲鹏 arm64）	麒麟 arm64	deb（arch: [x64, arm64]）

结论：支持。配置 linux.target: [deb, rpm, AppImage] + arch: [x64, arm64] 即覆盖麒麟系（含信创 arm64）；AppImage 作兜底，跨发行版免安装运行。

打包资源自定义 ✅

electron-builder 四类资源定制入口：

入口	作用	弈境用途
extraResources	拷贝到 resources/	FFmpeg 二进制、License 公钥
extraFiles	拷贝到安装根目录	Rust Core 相关脚本
asarUnpack	从 asar 解包原生模块	better-sqlite3 .node、napi 产物
files	控制 asar 内容	排除 source map

结论：支持。Rust napi .node、FFmpeg、公钥等均可在打包时自定义注入（与发布打包文档 §3 一致）。

0.3 代码保护：需求变更，必须加固

需求变更：原 License 方案 §5.2「接受破解、不做加固」作废。新立场——做加固、不接受破解。

base-electron 原生只有 asar（asar extract 可秒解包），不构成加固。加固方案是把 electron-build 的「三板斧」移植到 base-electron 的 vite 配置（与「NSIS 还是 Inno」正交，不破坏 electron-builder 出包）：

加固层	手段	移植来源
渲染层	敏感 JS（业务 index-*）AES-256-GCM 加密，主进程 interceptFileProtocol 解密	buildPlugin.closeBundle + main.js decodeJs
主进程	bytenode 编译 main.cjs → main.jsc 字节码	devPlugin.buildElectron(true)
全量	rollup-obfuscator 混淆	vite.config.js

同步项：License 方案详设 §5.2/§5.3「接受破解、不做加固」需改写为「做加固，加密/字节码/混淆提高逆向成本」；开发计划 §375 风险表「接受一定破解风险」同步调整。

0.4 关键澄清：electron-build 与 base-electron 在 Linux/麒麟同源

「electron-build 是一套独立于 base-electron 的打包链路」是误读。看 buildPlugin.buildInstaller()：

if (win)   → electron-builder --dir（只解包）→ Inno Setup iscc.exe 出 exe
else       → electron-builder --config（直接出 deb）   ← 与 base-electron 完全一致

即：Linux/麒麟下，electron-build 本身就是用 electron-builder（= base-electron 链路）出 deb；只有 Windows 下才额外用 Inno 打 exe。

因此 electron-build 相对 base-electron 的真实增量只有两点：① Windows 的 Inno 深度定制出 exe（文件关联/注册表/静默参数）；② 全局代码加固（AES+字节码+混淆）。其余（Linux/麒麟 deb、三平台出包底座）都落在 electron-builder 上，两者同源。

推论：采用 base-electron 的声明式链路后，麒麟/Linux 打包天然不变；Windows 用 electron-builder 原生 NSIS（base-electron 骨架自带，与发布打包文档 §2.1 一致），Inno 作为 electron-build 的历史包袱一并丢弃——除非后续确有文件关联/静默安装的强需求再引入。

0.5 开发主线与语言策略

决策：基于当前分支改造（不切分支），全仓采用 TypeScript。

两条路：① 把功能搬到 base-electron 分支（换地基）；② 把 base-electron 的打包模式 + TS 搬进当前分支（原地翻新）。选 ②，理由：

• base-electron 分支真正值钱的只有三个小片段——TS 主进程骨架（5 个文件）、electron-builder.json 声明式配置（51 行）、vite-plugin-electron 集成——半天就能抄进当前分支；
• 当前分支的资产是大件——monorepo 结构、naive-ui/pinia/langchain 依赖栈、packages/* 84 个 TS、renderer 17 个 Vue 组件、已跑通的 LangGraph 链路——搬到 base-electron 要重建依赖 + 搬迁 + 重新验证，一周以上且有丢东西风险；
• 当前分支的「问题」集中在打包层（自研 buildPlugin/Inno/envs/信创）与语言层（JS），属装修问题；地基（monorepo、依赖、业务）是健康的，不该为装修问题换地基。

语言现状与目标（不含 node_modules）：

层	现状	目标
主进程 apps/desktop/main	纯 JS（5 个 .js）	TS 化（base-electron 骨架本就是 TS）
渲染进程 apps/desktop/renderer	大部分 JS（28 .js + 17 .vue，仅 4 .ts）	TS 化（<script setup lang="ts">）
packages/*（Agent/数据层）	已是 TS（84 个 .ts）	保持

TS 与 PRD §4.5/§7.2、技术架构 §7.2 的「TypeScript 5.0+、无 any、100 类型覆盖」一致——需求本就要 TS，当前 JS 是 electron-build 基座带来的偏离。

改造清单（保留 vs 重写 vs 丢弃，全部在当前分支内进行）：

处置	内容	说明
保留	packages/*（Agent/数据层，已 TS）	业务资产，不动
保留并 TS 化	apps/desktop/renderer 的 17 个 Vue 组件/页面/状态	业务资产，28 个 .js 改 TS
重写	主进程（base-electron TS 骨架，按需保留窗口池/托盘/IPC）	5 个 .js 改 TS
重写	打包配置（electron-builder 声明式 + 加固插件）	弃自研 buildPlugin
丢弃	自研 buildPlugin 的 Inno/envs/信创、electron-build 的 JS 主进程	历史包袱，不留

---

一、结论先行

两个分支是两套不同定位的模板，不是同一方案的两种写法：

• base-electron：干净的现代脚手架。主进程 TypeScript 化、声明式打包、依赖新，但渲染进程基本是空的（无路由、无状态管理、无 UI 库）。
• electron-build：完整的企业级应用框架。全 JavaScript 项目，自带 UI 库/路由/状态管理/主题系统/多窗口池/代码加密/信创适配/多环境多产品发布体系，但打包链路是约 800 行的自研插件 + 外部 Inno Setup。

选型建议：做新产品、追求长期可维护性 → 以 base-electron 为主线；需要防破解、信创国产化、多产品多环境分发 → electron-build 的能力不可替代，可按需把它的打包能力移植到 base-electron 上。

---

二、评判口径说明（重要）

以下差异不作为主要评判依据，因为它们都可以低成本消除：

差异点	base-electron	electron-build	说明
Electron 版本	37.2.4	20.3.12	都可以升级，升级 electron-build 到新版本是常规操作
electron-builder 版本	26.0.12	24.13.3	同上，非破坏性升级
主进程语言	TypeScript	JavaScript	JS 可以改 TS，TS 也可以改 JS，迁移成本低
Vite 版本	7.0.6	5.1.6	可升级

真正需要看的是：整个项目用什么语言（全项目的一致性，而非单个目录）、技术栈完备度、打包架构理念、以及打包链路带来的工程能力差异。

---

三、整个项目的语言构成

文件扩展名统计（不含 node_modules）

分支	.js	.ts	.cjs	.vue	项目语言定性
base-electron	8	7	3	2	混合型：主进程全 TS，渲染进程基本 JS
electron-build	57	2	5	2	纯 JS 项目：仅入口 main.ts 和 vite-env.d.ts 是 TS 占位

base-electron 的语言分布

• electron/ 目录：全部 TypeScript（5 个文件：main/index.ts、preload/index.ts、ipc-handlers/ 下 3 个），且 IPC 处理器做了模块化拆分（file-handler、window-handler）
• src/ 渲染进程：基本是 JavaScript（views/home.vue、utils/ipcUtils.js、constants/index.js），仅入口 src/main.ts 是 TS
• 注意：仓库里只有 jsconfig.json，没有 tsconfig.json——即 TS 实际由 esbuild 转译，无独立类型检查环节，”TS 化”目前只覆盖了主进程

electron-build 的语言分布

• electronProcess/（主进程）：全部 JavaScript（main.js 562 行、windowPool.js 470 行、poolItem.js 262 行、createWindow.js 107 行）
• src/（渲染进程）：全部 JavaScript（37 个文件），入口 main.ts 只是占位
• plugins/（构建插件）、packages/（自研 release-it）：全部 JavaScript

小结

单看语言，两边都是”JS 项目 + 局部 TS”。base-electron 的差异仅在主进程目录 TS 化并有 IPC 模块化拆分；electron-build 是彻底的全 JS。由于语言可互改，语言本身不构成选型障碍；选型时更应关注语言背后的东西——electron-build 的主进程代码量（约 1400 行）承载的是窗口池等真实业务架构，迁移成本不在语言而在逻辑本身。

---

四、技术栈完备度对比（渲染进程框架）

这是两个分支差异最大的地方之一：

能力	base-electron	electron-build
Vue	3.5.18	3.4.21
路由	❌ 无	✅ vue-router 4
状态管理	❌ 无	✅ Pinia 2（含跨窗口状态同步插件 piniaStateSync、winSharePersistedState）
UI 组件库	❌ 无	✅ Element Plus 2.6（中文化、图标全局注册）
样式体系	无	✅ SCSS + 亮/暗双主题（assets/css/theme/dark、light）
网络请求	❌ 无	✅ axios 封装
自定义指令	❌ 无	✅ 水印 watermarker、拖拽缩放 dragResize 等
工具库	仅 ipcUtils.js	✅ 雪花 ID、文件加密、docx 导出、音频处理等 10+ 工具
Lint/规范化	prettier	✅ eslint + stylelint + husky + commitlint + lint-staged 全套

结论：base-electron 的 src/ 是一个 IPC 通信演示页（home.vue 195 行），加路由/状态管理/UI 库都要自己搭；electron-build 的 src/ 是一个开箱即用的中后台应用框架，且包含多窗口场景下最难做对的部分——跨窗口 Pinia 状态同步。

---

五、打包架构对比（核心）

base-electron：声明式标准链路

npm run electron:build
  = vite build（渲染进程 → dist/）
  + vite-plugin-electron（主进程/预加载 TS → dist-electron/，ESM）
  + electron-builder（读 electron-builder.json，一步出安装包）

• 配置集中在 electron-builder.json（51 行，纯声明式 JSON）
• 产物：Win NSIS / Mac DMG / Linux AppImage，三端一条命令
• 无外部工具依赖（不需要装 Inno Setup 等第三方软件）

electron-build：自研插件式链路（Windows 路径）

npm run electron:build
  = vite build（渲染进程 → dist/）
  ↓ buildPlugin.closeBundle 钩子（约 800 行自研 Vite 插件）
  ① AES-256-GCM 加密渲染进程敏感 JS（index-*.js，密钥在 decode.json）
  ② bytenode 把主进程 main.cjs 编译为字节码 main.jsc
  ③ 重写 dist/package.json（注入版本/appId/外链依赖分析）
  ④ electron-builder --dir（只解包，不封安装包）
  ⑤ 逐个字符串替换渲染 inno.iss 模板 → iscc.exe 编译出最终安装包
  ⑥ 生成 latest.yml（sha512 + 版本，供自动更新用）

• Windows 最终安装包由 Inno Setup 产出（需要构建机安装 Inno Setup 且 iscc.exe 在 PATH）
• Inno 脚本实现了：自定义安装向导、文件关联（.myp）、注册表写入、安装前杀进程、/dir /pass 静默安装参数、中文卸载文案等深度定制
• Linux 路径：deb（x64 + arm64），带信创 CPU 检测（龙芯/飞腾/海光/兆芯），deb 安装后执行 install.sh
• 多环境体系：envs/.env.std / .env.idor 驱动 appId、产品名、版本号、图标目录（icons/DemoV2、icons/DemoV3），一套代码打多个产品
• 发布流：自研 packages/release-it（fork 了 release-it 源码）管理版本与 changelog

打包能力矩阵

能力	base-electron	electron-build
配置方式	声明式 JSON，51 行	自研插件代码驱动 + 动态生成临时配置
出包命令	1 条命令全流程	vite 钩子内串联多步
Win 安装包	NSIS（electron-builder 内置）	Inno Setup（外部依赖，定制强）
Mac 支持	✅ DMG	❌ 无
Linux	AppImage（通用）	deb x64/arm64 + 信创四架构
asar 保护	仅 asar（可被 asar extract 轻松解包）	asar + 渲染层 AES-256-GCM + 主进程 bytenode 字节码 + rollup-obfuscator 混淆
自动更新元数据	❌ 无	✅ latest.yml
多环境/多产品	❌ 无	✅ envs 驱动，一套代码多产品
静默安装/注册表/文件关联	❌	✅ Inno 脚本定制
外部工具依赖	无	Inno Setup（Windows 构建机必装）
链路可维护性	高（社区标准）	中（自研代码 + 字符串替换渲染 iss 模板，排查成本高）

主进程架构附带差异

打包之外的架构差异同样影响选型：

差异	base-electron	electron-build
窗口模型	单窗口，IPC 按处理器模块拆分	窗口池（windowPool/poolItem，多窗口复用管理）
系统能力	基础	托盘、全局快捷键、crashReporter、自定义 app:// 协议
特殊依赖	—	bytenode、v8-compile-cache、@anthropic-ai/sdk 等

---

六、风险与现状

1. electron-build 分支近期不稳定：最新提交为 fix: 解决使用最新打包配置导致打包无法正常显示页面的问题，说明其打包配置发生过回退，链路当前健康度存疑。
2. electron-build 的加密密钥管理：decode.json 内含 AES 密钥且随仓库分发，若密钥写死在主进程解码逻辑中，加密强度取决于密钥隐藏方式，属于”提高逆向成本”而非绝对防护。
3. base-electron 无 TS 类型检查：仅有 jsconfig，TS 代码靠 esbuild 裸转译，没有 tsc 环节，类型收益目前只发挥了语法层面。
4. electron-build 构建机要求：Windows 出包必须装 Inno Setup；信创包需在对应 CPU 架构的 Linux 机器上构建。

---

七、最终建议

7.1 选型口径澄清（避免常见误解）

先给一个总判断：base-electron 不存在被 electron-build 独占、做不到的能力。两者差异是”现成集成好”与”自己补齐”之别，不是”有”与”没有”之别。三个易踩误解如下：

误解一：base-electron 打包”一点问题都没有”。其打包配置层面是社区标准、声明式、无外部依赖，是健康起点；但本分析未实际执行出包，且当前 src/ 仅是 IPC 演示页（195 行），真实产品打包后才会暴露资源路径、CSP、native 模块等边界问题。严谨说法：配置健康，但”无问题”待首包验证。

误解二：base-electron 做不了代码加密。加密发生在 Vite 插件层（buildPlugin.closeBundle 对渲染层 JS 做 AES-256-GCM、主进程 bytenode 编字节码、rollup-obfuscator 混淆），与”用 NSIS 还是 Inno 出安装包”是两个正交环节。把这段插件逻辑搬进 base-electron 的 vite 配置即可，不影响 electron-builder 出包。

误解三：electron-build”多了一步 Inno”是纯粹劣势。那”多一步”（electron-builder --dir 仅解包 → iscc.exe 编译 iss 出最终 exe）换回的是 NSIS 给不了的安装包深度定制：文件关联（.myp）、注册表写入、/dir /pass 静默安装参数、中文安装向导、安装前杀进程。不需要这套定制 → base-electron 的 NSIS 一步到位反而更优；确实需要 → 无论哪个分支都得引入 Inno，base-electron 也躲不开这”多一步”，但可选用比字符串 .replace 链更现代的方式接入（正规模板引擎渲染 iss）。

7.2 从 base-electron 补齐能力的路径

想要的能力	base-electron 现状	补齐方式
渲染框架/路由/Pinia/UI库/主题	❌ src 为空	搬 electron-build 的 src（与打包无关）
窗口池/托盘/全局快捷键	❌	搬 main.js 主进程逻辑
代码加密(AES+字节码+混淆)	❌	搬 buildPlugin 加密段入 vite 配置
多环境多产品(envs 驱动)	❌	加 .env + 动态生成 electron-builder.json
Linux deb x64/arm64 + 信创	配了 AppImage	改 electron-builder.json 的 linux.target
自动更新 latest.yml	❌（electron-builder 标准支持 publish）	用 electron-builder 原生 publish，比 electron-build 手写更省事
Inno 级安装包定制(文件关联/注册表/静默参数)	❌	真要这套，base-electron 也得加 Inno，同样”多一步”

7.3 主线选择

以 base-electron 为主线开发，理由：

1. 它是社区标准姿势，声明式配置、一条命令三端出包，任何 Electron 开发者接手零成本；
2. 版本新、无外部工具依赖、链路透明，出问题好排查；
3. 音频可视化这类产品当前不需要多产品分发和信创覆盖。

把 electron-build 当”能力仓库”按需移植，优先级从高到低：

1. 渲染进程框架（Element Plus + Router + Pinia 跨窗口同步 + 主题系统）——base-electron 的 src 是空的，这套直接搬能省一到两周搭建；
2. 窗口池架构（若音频可视化需要多窗口/悬浮窗，这是现成方案）；
3. 多环境多产品体系（envs + 图标目录约定）——等产品需要区分演示版/正式版时再引入；
4. 代码加密与信创打包——仅在出现明确的防破解或国产化需求时移植，并建议移植时重写 iss 模板的字符串替换渲染（改为正规的模板引擎），同时把版本先升上来再移。

不建议整体切换到 electron-build：同时背上 Electron 20→37 升级、57 个 JS 文件的语言迁移和 800 行自研插件的维护负担，收益却只是本可按需移植的能力。

✅ 【定论 · 2026-08-22】 上述「以 base-electron 为主线」的建议成立并升级为硬决策：基于当前分支改造——搬入 base-electron 的声明式打包 + 全仓 TypeScript；Windows 用 NSIS、麒麟/Linux 用 deb/rpm/AppImage；代码保护须做加固（不接受破解）。electron-build 与 base-electron 在 Linux/麒麟侧同源，见「零、定论」。