旧版 Electron 应用如何迁移到新的 contextIsolation 安全策略

迁移到新的 contextIsolation 策略是旧版 Electron 应用升级到 v12 及以上版本的必经之路，核心在于放弃渲染进程直接调用 Node.js 能力，改为通过 preload 脚本配合 contextBridge 进行受控暴露。

先说结论：必须启用 contextIsolation 并禁用 nodeIntegration，通过 preload 脚本桥接必要功能，优先使用 invoke/handle 模式处理异步通信

先判断：检查现有代码是否在渲染进程直接使用了 require 或 node 核心模块
优先做：编写 preload.js 并使用 contextBridge.exposeInMainWorld 暴露 API，主进程配合 ipcMain.handle
再验证：在渲染进程控制台确认 process.versions.node 为 undefined 但能调用暴露接口

快速处理思路

不需要复杂命令，主要是修改 Electron 启动配置和增加 preload 文件。关键配置变更如下：

// main.js 创建窗口时
const win = new BrowserWindow({
  webPreferences: {
    nodeIntegration: false, // 必须关闭
    contextIsolation: true, // 必须开启
    preload: path.join(__dirname, 'preload.js') // 指定预加载脚本
  }
})

为什么会这样

旧版 Electron 允许渲染进程（网页代码）直接访问 Node.js 接口，这意味着一旦网页被注入恶意脚本，攻击者就能直接操作本地文件系统或执行系统命令。开启 contextIsolation 后，渲染进程运行在独立的 JavaScript 上下文中，无法直接触碰 Node 环境，必须通过 preload 脚本这个“中间人”来传递有限的能力。

分步处理

1. 修改主进程配置
在创建 BrowserWindow 时明确设置 webPreferences，确保 nodeIntegration 为 false。同时需要注册 ipcMain.handle 来处理渲染进程的 invoke 请求。

// main.js
const { ipcMain } = require('electron')

// 处理异步请求，避免使用同步 IPC
ipcMain.handle('save-file', async (event, filePath) => {
  try {
    // 执行文件操作逻辑
    return { success: true, path: filePath }
  } catch (error) {
    return { success: false, error: error.message }
  }
})

2. 编写 preload 脚本
新建 preload.js，使用 contextBridge 暴露方法。注意不要直接暴露整个 ipcRenderer 对象，且需处理监听器清理以防内存泄漏。

// preload.js
const { contextBridge, ipcRenderer } = require('electron')

contextBridge.exposeInMainWorld('electronAPI', {
  // 推荐用于请求 - 响应模式
  invoke: (channel, data) => ipcRenderer.invoke(channel, data),
  // 用于订阅事件，必须返回移除监听器的函数
  on: (channel, func) => {
    const subscription = (event, ...args) => func(...args)
    ipcRenderer.on(channel, subscription)
    // 返回清理函数，组件卸载时调用
    return () => ipcRenderer.removeListener(channel, subscription)
  }
})

3. 修改渲染进程调用
原有直接 require 的代码需要改为调用 window.electronAPI。对于文件保存等操作，使用 invoke 获取结果。

// renderer.js
async function saveFile(filePath) {
  const result = await window.electronAPI.invoke('save-file', filePath)
  if (result.success) {
    console.log('保存成功:', result.path)
  } else {
    console.error('保存失败:', result.error)
  }
}

// 事件监听示例（注意清理）
const unsubscribe = window.electronAPI.on('update-ready', () => {
  console.log('更新就绪')
})
// 在组件销毁或页面卸载时调用 unsubscribe()

怎么验证是否生效

打开应用开发者工具（DevTools），在 Console 面板执行以下检查：

旧版 Electron 应用如何迁移到新的 contextIsolation 安全策略

1. 检查 Node 集成是否关闭
输入 process.versions.node。如果返回 undefined，说明 Node 环境已隔离。若直接输入 require 可能因作用域问题表现不一致，检查 process 对象更准确。

2. 检查 API 暴露情况
输入 window.electronAPI，应该能看到你暴露的对象结构，且 invoke 方法存在。

常见坑

1. 对象序列化限制：contextBridge 和 IPC 传递的数据必须是可序列化的（JSON 安全）。
错误案例：尝试传递 DOM 节点或包含循环引用的对象会报错 Could not clone argument。
解决：只传递纯数据对象，如 { id: 1, name: 'test' }。

2. 监听器内存泄漏：频繁调用 expose 的 on 方法且未移除监听器，会导致 ipcRenderer 监听器累积。
解决：如上文 preload 示例所示，暴露的 on 方法应返回移除函数，或在渲染进程组件卸载时主动清理。

3. 同步 IPC 阻塞：尽量避免在渲染进程使用 invokeSync 等同步方法，会导致界面卡顿。
解决：统一使用 async/await 配合 invoke/handle 异步模式。

4. 路径问题：preload 脚本中的 __dirname 可能指向不同位置，建议使用 path.join 确保路径正确。

参考来源

Electron 官方文档 - Context Isolation: https://www.electronjs.org/docs/latest/tutorial/context-isolation
Electron 官方文档 - Security Best Practices: https://www.electronjs.org/docs/latest/tutorial/security
Electron 官方文档 - Breaking Changes: https://www.electronjs.org/docs/latest/breaking-changes