Electron@22.0.0树莓派环境下captive portal子窗口无法加载虚拟键盘问题

核心问题分析 #

你的场景里，子窗口（Captive Portal）因为contextIsolation: true的安全配置，渲染进程无法直接访问Node.js的require模块；而electron-virtual-keyboard通常依赖Node环境或直接注入渲染进程，这就导致了注入失败、抛出require is undefined的问题。

解决方案步骤 #

1. 优化子窗口webPreferences配置 #

保留contextIsolation的安全配置，确认sandbox关闭（你已设置sandbox: false，无需修改），同时移除已废弃的enableRemoteModule（Electron 14+已弃用，改用IPC替代）：

// 主进程中创建子窗口的配置示例
const childWindow = new BrowserWindow({
  webPreferences: {
    devTools: true,
    nodeIntegration: false,
    webSecurity: true,
    contextIsolation: true,
    sandbox: false,
    preload: app.isPackaged 
      ? path.join(__dirname, 'captivePortalPreload.js') 
      : path.join(__dirname, '../../.erb/dll/captivePortalPreload.js'),
  }
});

2. 编写正确的Preload脚本（captivePortalPreload.js） #

通过contextBridge将虚拟键盘所需的核心API安全暴露给渲染进程，避免直接让渲染进程接触Node模块：

const { contextBridge, webFrame } = require('electron');

// 向渲染进程的window对象注入安全桥接API
contextBridge.exposeInMainWorld('captivePortalAPI', {
  // 暴露执行JavaScript的能力
  runJS: (code) => webFrame.executeJavaScript(code),
});

3. 子窗口渲染进程中调用桥接API #

不再直接使用require，而是通过window.captivePortalAPI加载虚拟键盘：

// 子窗口前端代码
window.captivePortalAPI.runJS(`
  // 加载虚拟键盘脚本（确保路径指向本地编译后的产物）
  const script = document.createElement('script');
  script.src = './vendor/electron-virtual-keyboard/dist/virtual-keyboard.js';
  document.body.appendChild(script);
  
  script.onload = () => {
    // 初始化虚拟键盘
    window.VirtualKeyboard.init({
      // 你的配置参数，比如目标输入框选择器等
      target: 'input[type="text"], input[type="password"]'
    });
  };
`).catch(err => console.error('虚拟键盘加载失败:', err));

4. 确保虚拟键盘资源可访问 #

• 将electron-virtual-keyboard的编译产物（比如dist目录下的文件）复制到子窗口HTML所在的目录，或配置正确的相对路径
• 禁止在渲染进程中直接requireNode模块，所有Node相关操作都通过preload脚本桥接完成

关键注意事项 #

• Electron 22中enableRemoteModule已完全废弃，不要依赖它实现跨进程通信
• contextIsolation开启时，渲染进程只能通过contextBridge暴露的API与Node环境交互，这是Electron的安全设计要求
• webFrame.executeJavaScript必须在preload脚本中暴露，渲染进程无法直接访问webFrame对象

内容的提问来源于stack exchange，提问作者Shay Cohen