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

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

F.1 版本变化时间线

版本	Chromium	Node.js	发布日期	关键变化
43	150	24.17.0	2026 Q3	稳定版本，推荐所有新项目使用
42	138	22.x	2026 Q2	稳定版本，macOS 通知需代码签名
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 Electron 43 新特性

对话框默认路径变化

Electron 43 起，当 defaultPath 省略时，dialog.showOpenDialog / showSaveDialog 默认打开 Downloads 文件夹（此前行为因平台而异，常为用户上次访问的目录）。若需要保留“记住上次目录”的体验，需手动维护 lastUsedPath：

typescript

import { dialog } from 'electron'
import Store from 'electron-store'

const store = new Store<{ lastPath: string }>()

export async function showOpenDialogWithMemory(options: Electron.OpenDialogOptions = {}) {
  const lastPath = store.get('lastPath', '')
  const { canceled, filePaths } = await dialog.showOpenDialog({
    ...options,
    defaultPath: lastPath || undefined
  })

  if (!canceled && filePaths.length > 0) {
    // 记录父目录，供下次使用
    store.set('lastPath', path.dirname(filePaths[0]))
  }

  return { canceled, filePaths }
}

Offscreen Rendering 默认 Device Scale Factor

Electron 43 中，offscreen 窗口的默认 deviceScaleFactor 改为 1.0。若你的 RPA 或截图逻辑依赖物理像素分辨率，必须显式设置：

typescript

const win = new BrowserWindow({
  width: 1920,
  height: 1080,
  show: false,
  webPreferences: {
    offscreen: true,
    // 显式指定 scale factor，避免不同平台截图尺寸不一致
    deviceScaleFactor: 1.5
  }
})

macOS 通知需要代码签名

Electron 43 在 macOS 上使用 UNNotification API 显示通知。未签名的应用在调用 Notification 时会静默失败（failed 事件）。发布到 macOS 的生产版本必须配置有效的代码签名与公证。

typescript

import { Notification } from 'electron'

const notification = new Notification({
  title: 'RPA 任务完成',
  body: '点击打开主窗口'
})

notification.on('failed', (event, error) => {
  console.error('通知显示失败（macOS 通常与代码签名有关）:', error)
})

notification.show()

Linux Frameless 窗口默认圆角

Electron 43 在 Linux 上为 frameless 窗口启用默认圆角。若你的应用需要硬朗直角外观，显式设置：

typescript

new BrowserWindow({
  frame: false,
  roundedCorners: false // Electron 43+，Linux 默认 true
})

nativeImage.toBitmap() 颜色空间归一化

Electron 43 中 nativeImage.toBitmap() 返回的像素数据统一归一化为 sRGB。若你的视觉定位/OCR 逻辑之前依赖原始设备颜色空间，需检查阈值与模板匹配结果。

F.3 新增 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 坐标）
`roundedCorners`	43+	Linux frameless 窗口圆角开关

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.4 已移除/弃用 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+
`electron-rebuild` 包	已弃用	`@electron/rebuild`	—

迁移检查脚本

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

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/
grep -rn "electron-rebuild" package.json

F.5 从 Electron 28 迁移到 43 的步骤

步骤 1：更新依赖

json

{
  "devDependencies": {
    "electron": "^43.1.0"
  }
}

bash

pnpm install

步骤 2：更新 Node.js

Electron 43 内置 Node.js 24.17.0。建议开发环境使用 Node.js v22 LTS 或更高版本：

bash

node --version  # 建议 v22.x.x 或 v24.x.x

步骤 3：处理 Breaking Changes

检查项	操作
`protocol.registerFileProtocol` 等	替换为 `protocol.handle`
CJS → ESM	electron-vite 已内置支持，确认 `"type": "module"`
native 模块重编译	运行 `pnpm exec @electron/rebuild -v 43.1.0`
macOS 公证	使用 `@electron/notarize` + `notarytool`，弃用 `altool`
`electron-store`	升级至 v11+，使用 `import` 语法
对话框默认路径	如需记住上次目录，手动维护 `lastUsedPath`
offscreen 截图	显式设置 `webPreferences.offscreen.deviceScaleFactor`
Linux frameless	如需直角，设置 `roundedCorners: false`

步骤 4：利用新特性

机会	实现
文件拖放路径获取	使用 `webUtils.getPathForFile()`
敏感数据存储	使用 `safeStorage` 替代明文存储
新窗口选项	探索 `trafficLightPosition`、`roundedCorners` 等新配置
启动优化	确保 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.6 常见问题

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

bash

# 重新编译所有原生模块
pnpm exec @electron/rebuild -v 43.1.0

# 或添加到 postinstall
"postinstall": "@electron/rebuild -v 43.1.0"

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

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

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

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

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

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

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

F.1 版本变化时间线 ​

F.2 Electron 43 新特性 ​

对话框默认路径变化 ​

Offscreen Rendering 默认 Device Scale Factor ​

macOS 通知需要代码签名 ​

Linux Frameless 窗口默认圆角 ​

nativeImage.toBitmap() 颜色空间归一化 ​

F.3 新增 API 速查表 ​

webUtils（Electron 31+） ​

safeStorage 增强（Electron 34+） ​

BrowserWindow 新选项 ​

protocol.handle 全面替代 registerFileProtocol ​

app.getGPUInfo（Electron 31+） ​

其他新特性 ​

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

迁移检查脚本 ​

F.5 从 Electron 28 迁移到 43 的步骤 ​

步骤 1：更新依赖 ​

步骤 2：更新 Node.js ​

步骤 3：处理 Breaking Changes ​

步骤 4：利用新特性 ​

步骤 5：测试与验证 ​

F.6 常见问题 ​

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

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

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

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

F.7 推荐阅读 ​

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

F.1 版本变化时间线

F.2 Electron 43 新特性

对话框默认路径变化

Offscreen Rendering 默认 Device Scale Factor

macOS 通知需要代码签名

Linux Frameless 窗口默认圆角

nativeImage.toBitmap() 颜色空间归一化

F.3 新增 API 速查表

webUtils（Electron 31+）

safeStorage 增强（Electron 34+）

BrowserWindow 新选项

protocol.handle 全面替代 registerFileProtocol

app.getGPUInfo（Electron 31+）

其他新特性

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

迁移检查脚本

F.5 从 Electron 28 迁移到 43 的步骤

步骤 1：更新依赖

步骤 2：更新 Node.js

步骤 3：处理 Breaking Changes

步骤 4：利用新特性

步骤 5：测试与验证

F.6 常见问题

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

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

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

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

F.7 推荐阅读