附录 F：Electron 42 新特性与迁移指南

Electron 采用 Chrome 类似的快速发布节奏（每 8 周一个大版本）。本附录汇总了从 Electron 31 到 42 的关键变化，帮助你快速了解新特性并从旧版本平滑迁移。

F.1 版本变化时间线

版本	Chromium	Node.js	发布日期	关键变化
42	138	22.x	2026 Q1	稳定版本，推荐所有新项目使用
41	137	22.x	2025 Q4	Service Worker 增强
40	136	22.x	2025 Q3	WebUSB 改进
39	135	22.x	2025 Q2	V8 引擎升级
38	134	22.x	2025 Q1	Navigation API 改进
37	133	22.x	2024 Q4	CSS View Transitions
36	132	22.x	2024 Q3	WebNN API 支持
35	131	22.x	2024 Q2	BrowserWindow 新选项
34	130	22.x	2024 Q1	safeStorage 增强
33	129	22.x	2023 Q4	性能优化
32	128	22.x	2023 Q3	webUtils 稳定
31	127	22.x	2023 Q2	webUtils 引入

F.2 新增 API 速查表

webUtils（Electron 31+）

在 preload 中获取 File 对象对应的本地文件路径：

typescript

import { webUtils } from 'electron'

// preload 中使用
contextBridge.exposeInMainWorld('api', {
  getPathForFile: (file: File) => webUtils.getPathForFile(file)
})

使用场景：拖放文件、<input type="file"> 选择文件后获取完整路径。

safeStorage 增强（Electron 34+）

typescript

import { safeStorage } from 'electron'

// 检查加密功能是否可用
if (safeStorage.isEncryptionAvailable()) {
  // 加密字符串（返回 Buffer）
  const encrypted = safeStorage.encryptString('sensitive-data')
  // 解密
  const decrypted = safeStorage.decryptString(encrypted)
}

// 可选：设置加密后端（macOS 除外）
// 不调用则使用系统默认实现

BrowserWindow 新选项

选项	引入版本	说明
`transparent: true` 增强	35+	窗口透明区域点击穿透行为优化
`titleBarOverlay` 改进	33+	自定义标题栏叠加层支持更多样式属性
`trafficLightPosition`	35+	macOS 红绿灯按钮的自定义位置（x, y 坐标）

protocol.handle 全面替代 registerFileProtocol

typescript

// Electron 25+ 推荐方式
import { protocol, net } from 'electron'

app.whenReady().then(() => {
  protocol.handle('myapp', (request) => {
    const url = request.url.replace('myapp://', '')
    const filePath = path.join(__dirname, url)
    return net.fetch('file://' + filePath)
  })
})

app.getGPUInfo（Electron 31+）

typescript

// 获取 GPU 信息（用于性能分析和 bug 报告）
const gpuInfo = await app.getGPUInfo('basic')
console.log('GPU 厂商:', gpuInfo.gpuDevice?.[0]?.vendorString)

// 'complete' 模式获取详细信息
const completeInfo = await app.getGPUInfo('complete')

其他新特性

API / 特性	版本	用途
`BrowserWindow.setTopBrowserView`	34+	设置最顶层的 BrowserView
`webContents.navigationHistory` 增强	36+	更精细的导航历史控制
V8 代码缓存优化	38+	更快的启动速度（自动启用）
WebNN API	36+	浏览器端神经网络推理
CSS View Transitions	37+	页面切换动画的原生支持
View Transition API	38+	单页应用视图切换动画

F.3 已移除/弃用 API 对照表

旧 API	状态	替代方案	移除版本
`remote` 模块	已移除	`ipcMain` / `ipcRenderer` + `contextBridge`	14+
`enableRemoteModule` 配置项	已移除	不再有效，可安全删除	14+
`protocol.registerFileProtocol`	已弃用	`protocol.handle` + `net.fetch`	25+ 废弃
`protocol.registerBufferProtocol`	已弃用	`protocol.handle`	25+ 废弃
`protocol.registerStringProtocol`	已弃用	`protocol.handle`	25+ 废弃
`protocol.registerHttpProtocol`	已弃用	`protocol.handle`	25+ 废弃
`protocol.registerStreamProtocol`	已弃用	`protocol.handle`	25+ 废弃
`webContents.print()` (回调)	已弃用	`webContents.print()` (Promise 返回)	30+
`BrowserWindow.removeMenu` (macOS)	已弃用	直接设置 `Menu.setApplicationMenu(null)`	—
`shell.openItem`	已移除	`shell.openPath`	22+
`crashReporter.start` (旧签名)	已弃用	`crashReporter.start({ submitURL, ... })`	20+

迁移检查脚本

在项目中搜索以下关键字，逐一替换：

bash

# 扫描项目中的弃用 API
grep -rn "registerFileProtocol\|registerBufferProtocol\|registerStringProtocol\|registerHttpProtocol\|registerStreamProtocol" src/
grep -rn "enableRemoteModule\|require('electron').remote" src/
grep -rn "shell.openItem" src/
grep -rn "crashReporter.start(" src/

F.4 从 Electron 28 迁移到 42 的步骤

步骤 1：更新依赖

json

{
  "devDependencies": {
    "electron": "^42.0.0"
  }
}

bash

pnpm install

步骤 2：更新 Node.js

Electron 42 内置 Node.js 22.x。确保开发环境使用 Node.js v22 LTS：

bash

node --version  # 应为 v22.x.x

步骤 3：处理 Breaking Changes

检查项	操作
`protocol.registerFileProtocol` 等	替换为 `protocol.handle`
CJS → ESM	electron-vite 已内置支持，确认 `"type": "module"`
native 模块重编译	运行 `npx @electron/rebuild -v 42.0.0`
macOS 公证	使用 `@electron/notarize` + `notarytool`，弃用 `altool`
`electron-store`	升级至 v9+，使用 `import` 语法

步骤 4：利用新特性

机会	实现
文件拖放路径获取	使用 `webUtils.getPathForFile()`
敏感数据存储	使用 `safeStorage` 替代明文存储
新窗口选项	探索 `trafficLightPosition` 等新配置
启动优化	确保 V8 代码缓存自动启用
GPU 监控	使用 `app.getGPUInfo()` 诊断渲染问题

步骤 5：测试与验证

bash

# 1. 构建验证
pnpm build

# 2. 检查弃用 API
grep -rn "registerFileProtocol\|registerBufferProtocol" src/
# (应无输出)

# 3. 启动应用逐一验证关键功能
pnpm dev

# 4. 检查安全配置
# 确认 sandbox: true, contextIsolation: true, nodeIntegration: false

F.5 常见问题

Q: 升级 Electron 后原生模块报错？

bash

# 重新编译所有原生模块
npx @electron/rebuild -v 42.0.0

# 或添加到 postinstall
"postinstall": "electron-rebuild -v 42.0.0"

Q: electron-store 升级到 v9+ 后 import 报错？

确保 package.json 中 "type": "module" 已设置（electron-vite 项目默认为 module）。

Q: protocol.handle 与旧 registerFileProtocol 行为差异？

protocol.handle 返回 Response 对象（使用 net.fetch），而非回调。需要使用 net 模块构造响应。

Q: 升级后窗口渲染异常？

检查 Chromium 版本变更导致的 CSS/JS 兼容性问题。Electron 42 使用 Chromium 138。

附录 F：Electron 42 新特性与迁移指南 ​

F.1 版本变化时间线 ​

F.2 新增 API 速查表 ​

webUtils（Electron 31+） ​

safeStorage 增强（Electron 34+） ​

BrowserWindow 新选项 ​

protocol.handle 全面替代 registerFileProtocol ​

app.getGPUInfo（Electron 31+） ​

其他新特性 ​

F.3 已移除/弃用 API 对照表 ​

迁移检查脚本 ​

F.4 从 Electron 28 迁移到 42 的步骤 ​

步骤 1：更新依赖 ​

步骤 2：更新 Node.js ​

步骤 3：处理 Breaking Changes ​

步骤 4：利用新特性 ​

步骤 5：测试与验证 ​

F.5 常见问题 ​

Q: 升级 Electron 后原生模块报错？ ​

Q: electron-store 升级到 v9+ 后 import 报错？ ​

Q: protocol.handle 与旧 registerFileProtocol 行为差异？ ​

Q: 升级后窗口渲染异常？ ​

F.6 推荐阅读 ​

附录 F：Electron 42 新特性与迁移指南

F.1 版本变化时间线

F.2 新增 API 速查表

webUtils（Electron 31+）

safeStorage 增强（Electron 34+）

BrowserWindow 新选项

protocol.handle 全面替代 registerFileProtocol

app.getGPUInfo（Electron 31+）

其他新特性

F.3 已移除/弃用 API 对照表

迁移检查脚本

F.4 从 Electron 28 迁移到 42 的步骤

步骤 1：更新依赖

步骤 2：更新 Node.js

步骤 3：处理 Breaking Changes

步骤 4：利用新特性

步骤 5：测试与验证

F.5 常见问题

Q: 升级 Electron 后原生模块报错？

Q: electron-store 升级到 v9+ 后 import 报错？

Q: protocol.handle 与旧 registerFileProtocol 行为差异？

Q: 升级后窗口渲染异常？

F.6 推荐阅读