如何升级至Electron 14+并正确启用迁移至userland的remote模块

从Electron 14版本开始，内置的remote模块被完全移除，迁移到了独立的userland包@electron/remote，仅靠旧版本的enableRemoteModule配置无法生效，按以下步骤操作即可修复：

具体操作步骤 #

• 进入你fork的项目本地根目录，安装拆分后的remote独立依赖，执行命令：
  npm install @electron/remote --save
• 打开项目主进程入口文件（Caprine的主进程入口为source/main.ts，即代码里调用app.whenReady()、创建BrowserWindow实例的文件），在文件头部、app初始化完成前，加入remote主进程初始化代码：

  // 初始化remote主进程模块
  require('@electron/remote/main').initialize()
  

• 找到所有创建BrowserWindow实例的代码段，在每个窗口实例创建完成后，立刻为该窗口开启remote调用权限，示例：

  const mainWindow = new BrowserWindow({
    // 原有窗口配置项，比如宽高、preload路径等
    webPreferences: {
      // *注意：高版本Electron已经删除enableRemoteModule配置项，把这行从配置里删掉，留着会报配置错误
      // enableRemoteModule: true,
      // 如果启动后报`require is not defined`错误，就加下面这行，Caprine旧版本本身没有做上下文隔离适配
      contextIsolation: false
    }
  })
  // 新增这行，给当前窗口开启remote权限
  require('@electron/remote/main').enable(mainWindow.webContents)
  

• 全局搜索项目所有渲染进程代码里的remote引用，把原来从electron核心包引入remote的写法，全部替换为从独立包引入：

  // 旧写法（仅适用于Electron 13及更早版本）
  // const { dialog, getCurrentWindow, shell } = require('electron').remote
  
  // 新写法
  const { dialog, getCurrentWindow, shell } = require('@electron/remote')
  

• 修改完成后，先删除项目根目录的node_modules文件夹和package-lock.json文件，重新执行npm install安装依赖，再执行npm start测试启动即可。

版本适配注意事项 #

• 安装@electron/remote时注意和你使用的Electron大版本匹配：Electron 14~17对应@electron/remote@1.x版本，Electron 18~26对应@electron/remote@2.x版本，版本不匹配也会导致启动异常。
• 如果目标是适配Wayland环境，建议直接升级到Electron 22以上LTS版本，该版本之后Wayland适配稳定性更好，无需逐版本从14往上升级，减少重复修改API的工作量。
• 之前替换完成的shell.trashItemAPI在高版本Electron中依然可用，无需额外改动。

内容的提问来源于stack exchange，提问作者Lefteris Garyfalakis