44. 版本演进与升级

本节目标

• 理解 Electron 的语义化版本（SemVer）映射规则。
• 了解其 8 周发布周期与稳定分支机制。
• 掌握一次主版本升级的标准步骤。
• 知道从哪里查 breaking changes。
• 警惕升级原生模块与 Chromium 行为的连锁影响。

1-1 版本号背后的含义

从 2.0.0 起，Electron 遵循语义化版本（SemVer）规范。版本号 主.次.补丁 的每一位，对应不同的变更类型，而且它不仅反映 Electron 自身，还连带映射 Chromium 与 Node.js 的版本。

递增类型	触发条件
主版本（Major）	Electron 破坏性 API 变更、Node.js 主版本更新、Chromium 大版本更新
次版本（Minor）	Electron 非破坏性 API 变更、Node.js 次版本更新
补丁（Patch）	Electron Bug 修复、Node.js 补丁、Chromium 修复性补丁

值得注意：多数 Chromium 更新会被视为破坏性变更，因为 Chromium 内部行为变化可能间接影响你的应用。补丁版本则主要承载安全与稳定性修复，通常会从 main 挑选（cherry-pick）回去。

本书基线为 Electron v43.2.0（2026-07-21 发布，对应的 Chromium 为 150.0.7871.129，内嵌 Node.js 运行时）。写作与示例都以该版本为准，遇到差异请以此校准。

1-2 发布周期与稳定分支

Electron 采用约 8 周 的常规发布周期，关键节点与 Chromium 的发布节奏对齐。当某个大版本进入稳定期后，会从其对应的稳定分支（命名形如 43-x-y）持续接收安全与稳定性相关的挑选提交，这些分支不会合并回 main。

稳定分支机制的好处是：你不用为了拿一个安全补丁而被迫升级到带破坏性变更的新大版本。例如某个零日漏洞修复后，维护者会把它回灌到仍在支持的 43-x-y 分支，发布 43.0.1 这样的补丁版本，你只需小幅升级即可。

1-3 为什么要及时升级

用旧版 Electron 打包出的应用，相当于带着旧版 Chromium 与旧版 Node.js 一起发布。针对这些旧组件的漏洞利用手法更公开、更容易获取，因此老版本应用更容易成为攻击目标。保持较新版本，意味着潜在的已知漏洞大多已被修复。

升级的另一个动力来自生态：新的 Node API、新的 Chromium 特性、性能改进都会随版本到来。建议把「跟踪 Electron 大版本」纳入常规维护，而不是等到被迫升级时手忙脚乱。

1-4 标准升级步骤

一次稳妥的大版本升级，推荐按下面的节奏进行：

第一步，逐大版本推进。不要从 v40 一口气跳到 v43，而是一档一档升（40→41→42→43）。每升一档，先跑通再升下一档，问题更容易定位。

第二步，查阅 breaking changes。官方有专门的「Breaking Changes」文档，列出每个大版本移除或改动的行为。升级前先对照清单改代码。

第三步，升级依赖与重新编译原生模块。大版本通常伴随 Node ABI 变化，所有原生模块都要用 @electron/rebuild 重新编译，否则运行会报 NODE_MODULE_VERSION 不匹配。

# 升级到最新稳定版
npm install --save-dev electron@latest

# 重新编译原生模块（Electron Forge 会自动调用）
./node_modules/.bin/electron-rebuild

第四步，本地回归测试。重点验证：窗口行为、BrowserWindow 选项、IPC、自动更新、原生模块功能，以及任何依赖 Chromium 内部行为的代码。

第五步，发布前先在预发布渠道验证。先用小流量验证新版本表现，再全量推送。

1-5 常见 breaking changes 与处理

不同大版本的具体变更要去官方文档查，但有几类最常被踩到：

• remote 模块相关：如果老代码用了 remote（Electron 14 已移除），必须改成 contextBridge + ipcRenderer。v43 里完全不存在 remote，任何相关写法都会直接报错。
• webPreferences 默认值变化：contextIsolation 自 12 起默认 true、nodeIntegration 默认 false、sandbox 自 20 起默认开启。老代码若依赖旧默认，需要显式补齐新默认值。
• 被移除/重命名的 API：部分模块或方法会在大版本被删，需替换为新接口或官方推荐方案。
• Chromium 行为变更：网页标准、CSP、权限模型的变化可能间接影响渲染进程行为，需要回归测试界面。

下面把「老式调用」改写成安全 IPC 的思路做个对照。所谓老式写法，是指从渲染进程直接取主进程窗口对象、再改它的标题——这种跨进程直接拿对象的方式在 v14 之后已不可用。正确做法是由 preload 暴露一个受控函数，渲染进程只管调用，真正的窗口操作留在主进程。

// ❌ 老思路（v14 起已移除，v43 不可用）
// 渲染进程直接拿到主进程窗口并改标题 —— 这种跨进程取对象的写法已失效
// 此处不写出具体调用，因为它在 v43 里不存在，写出来只会误导读者

// ✅ v43 写法：渲染进程经 preload 调主进程
// preload.js
contextBridge.exposeInMainWorld('electronAPI', {
  setTitle: (t) => ipcRenderer.invoke('set-title', t)
})
// 主进程
ipcMain.handle('set-title', (e, t) => {
  e.sender.getOwnerBrowserWindow().setTitle(t)
})

1-6 版本相关的工程建议

把 Electron 版本固定写进 package.json 的 devDependencies，并锁进 package-lock.json，保证团队成员与 CI 环境一致。不要写 ^ 之类的浮动范围去自动跨大版本，否则一次 npm install 可能把你推到不兼容的新版。对于自动更新，客户端也应支持灰度与回滚，避免坏版本一次性铺开。

养成跟踪版本的习惯也很重要：订阅 Electron 官方博客与 GitHub 的 release 通知，每次大版本发布后第一时间看 release notes 里的「Breaking Changes」小节；把升级动作排进每个季度的例行维护，而不是等安全公告迫在眉睫才动手。很多团队会专门建一个「依赖升级」看板，把 Electron、Chromium 行为变化、原生模块兼容性逐项记录，这样下次升级就有据可查、不会重复踩坑。把版本管理当成持续工程，而不是一次性任务，应用的长期安全才有保障。

小结

Electron 的版本号同时承载了自身、Chromium 与 Node.js 三者的变更，理解 SemVer 映射和 8 周发布节奏，能让你对升级有预期。稳妥的升级是「逐大版本推进 + 查 breaking changes + 重编译原生模块 + 回归测试」。记住：remote 已在 v14 移除，v43 只能用 contextBridge + ipcRenderer。下一章我们收尾，给出学习路线与生态资源。