Electron 渲染进程中 require 模块引用失败的解决方案与安全考量

1. Electron 进程模型概述

在深入探讨问题之前，理解 electron 的进程架构至关重要。electron 应用主要由两种类型的进程组成：

• 主进程 (Main Process)： 主进程是 Node.js 运行时环境，负责管理应用程序的生命周期、创建和管理浏览器窗口、处理系统事件、与操作系统进行交互等。它拥有完整的 Node.js API 访问权限，可以执行文件系统操作、网络请求、子进程管理等。

• 渲染进程 (Renderer Process)： 每个 BrowserWindow 实例都运行在一个独立的渲染进程中。渲染进程本质上是一个带有 Node.js 能力的 Chromium 浏览器实例，用于显示用户界面。然而，为了安全和性能考量，渲染进程默认情况下并不会直接暴露 Node.js API（如 require、process、fs 等）给网页内容。它的上下文与普通网页环境更为接近。

2. 问题分析：渲染进程中的 require 错误

当尝试在 Electron 渲染进程中直接使用 Node.js 的 require 语句导入模块时，通常会遇到 require is not defined 的错误。例如，以下代码片段在渲染进程中执行时就会失败：

// get_screenshot.js (在 Electron 渲染进程中加载)
const util = require('util'); // 错误：'require is not defined'
const childProcess = require('child_process');

document.getElementById('test_id').innerHTML = "Require passed!";

const exec = util.promisify(childProcess.exec);

// ... 后续代码依赖于 util 和 childProcess

这个错误的原因正是因为渲染进程默认处于一个沙箱环境中，其全局作用域中不包含 Node.js 的 require 函数。尽管 get_screenshot.js 在独立的 Node.js 环境中可以正常运行，但在 Electron 的渲染进程中，它被视为普通的网页脚本，因此无法直接访问 Node.js 模块。

3. 解决方案：配置 BrowserWindow 的 webPreferences

要允许渲染进程直接访问 Node.js API，包括使用 require 语句，需要在主进程创建 BrowserWindow 实例时，通过配置 webPreferences 对象来显式启用 Node.js 集成。

核心的配置项是 nodeIntegration 和 contextIsolation：

• nodeIntegration: true: 将此选项设置为 true 是解决 require 未定义问题的关键。它指示 Electron 在渲染进程中启用 Node.js 集成，允许网页内容直接访问 Node.js API。

• contextIsolation: false: contextIsolation 旨在将渲染进程的 JavaScript 上下文与 Node.js 上下文进行隔离，以提高安全性。当 nodeIntegration 为 true 时，如果 contextIsolation 也为 true，则渲染进程的全局对象（如 window）将无法直接访问 Node.js 全局对象和模块。为了使 require 在渲染进程的全局作用域中可用，通常需要将 contextIsolation 设置为 false，这会将 Node.js 上下文与渲染进程的常规网页上下文合并。

以下是主进程中 BrowserWindow 的正确配置示例：

// main.js (Electron 主进程文件)
const { app, BrowserWindow } = require('electron');
const path = require('path');

let mainWindow;

function createWindow () {
  mainWindow = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      nodeIntegration: true,     // 启用 Node.js 集成，允许渲染进程使用 require 等 Node.js API
      contextIsolation: false,   // 禁用上下文隔离，将 Node.js 上下文暴露给渲染进程的全局作用域
      // preload: path.join(__dirname, 'preload.js') // 如果需要更安全的做法，可以考虑使用 preload 脚本
    }
  });

  // 加载应用的 index.html
  mainWindow.loadFile('index.html');

  // 可选：打开开发者工具进行调试
  // mainWindow.webContents.openDevTools();
}

// 当 Electron 应用准备就绪时创建窗口
app.whenReady().then(createWindow);

// 处理所有窗口关闭事件
app.on('window-all-closed', () => {
  // 在 macOS 上，除非用户明确使用 Cmd + Q 退出，否则通常保持应用活跃
  if (process.platform !== 'darwin') {
    app.quit();
  }
});

// 处理 macOS 上点击 Dock 图标重新激活应用的情况
app.on('activate', () => {
  if (BrowserWindow.getAllWindows().length === 0) {
    createWindow();
  }
});

通过上述配置，当 index.html 加载并执行 get_screenshot.js 时，require 语句将能够正常解析并导入 util 和 childProcess 等 Node.js 内置模块，从而解决 require is not defined 的问题。

4. 安全考量与最佳实践

虽然设置 nodeIntegration: true 和 contextIsolation: false 可以快速解决问题，但这种做法在安全性方面存在显著风险，尤其是在以下情况：

• 加载不可信内容：如果你的 Electron 应用需要加载来自外部或不可信源的网页内容（例如通过 mainWindow.loadURL('https://example.com')），那么启用 nodeIntegration: true 将允许这些外部网页脚本执行任意的 Node.js 代码。这可能导致严重的安全漏洞，如远程代码执行（RCE）。
• 恶意脚本注入：即使是本地内容，如果存在跨站脚本（XSS）漏洞，恶意脚本也可能利用 nodeIntegration 访问用户文件系统、执行系统命令等。

因此，对于生产环境应用，强烈推荐以下更安全的实践：

商汤商量

商汤科技研发的AI对话工具，商量商量，都能解决。

36

查看详情

• 默认禁用 nodeIntegration 和启用 contextIsolation： 这是 Electron 推荐的默认安全设置，即 nodeIntegration: false 和 contextIsolation: true。在这种模式下，渲染进程的网页内容无法直接访问 Node.js API。

• 使用 Preload 脚本安全地暴露 API： 当 nodeIntegration 为 false 且 contextIsolation 为 true 时，如果渲染进程确实需要访问某些特定的 Node.js 功能，可以通过 Preload 脚本（预加载脚本）来安全地实现。 Preload 脚本在渲染进程加载任何网页内容之前执行，并可以访问 Node.js API。通过 Electron 的 contextBridge 模块，你可以选择性地将一部分功能从 Preload 脚本安全地暴露给渲染进程的 window 对象，而不会暴露整个 Node.js 环境。

  Preload 脚本示例 (preload.js):

  // preload.js
  const { contextBridge, shell } = require('electron');
  const util = require('util');
  const childProcess = require('child_process');
  
  // 定义一个安全的 API 对象，只暴露需要的功能
  contextBridge.exposeInMainWorld('electronAPI', {
    // 暴露一个执行 shell 命令的异步函数
    runShellCommand: async (command) => {
      try {
        const { stdout, stderr } = await util.promisify(childProcess.exec)(command);
        if (stderr) {
          console.warn(`Shell command stderr: ${stderr}`);
        }
        return stdout;
      } catch (error) {
        console.error(`Error executing shell command: ${error}`);
        throw error;
      }
    },
    // 暴露一个打开外部链接的函数
    openExternal: (url) => shell.openExternal(url)
  });

  登录后复制

  主进程配置使用 Preload 脚本：

  // main.js (部分配置)
  const { app, BrowserWindow } = require('electron');
  const path = require('path');
  
  function createWindow () {
    mainWindow = new BrowserWindow({
      width: 800,
      height: 600,
      webPreferences: {
        nodeIntegration: false,   // 默认禁用 Node.js 集成
        contextIsolation: true,   // 默认启用上下文隔离
        preload: path.join(__dirname, 'preload.js') // 指定预加载脚本路径
      }
    });
    // ...
  }

  登录后复制

  渲染进程中使用暴露的 API：

  // get_screenshot.js (在渲染进程中)
  // 注意：这里不再直接使用 require，而是通过暴露的 API
  async function takeScreenshot() {
      try {
          // 调用通过 contextBridge 暴露的函数
          const screenshotData = await window.electronAPI.runShellCommand('adb exec-out screencap -p');
          displayScreenshot(screenshotData);
      } catch (error) {
          console.error('Failed to take screenshot:', error);
      }
  }
  
  function displayScreenshot(screenshotData) {
      const imageData = `data:image/png;base64,${screenshotData}`;
      const imgElement = document.getElementById('screenshotImage');
      imgElement.src = imageData;
  }
  
  takeScreenshot();

  登录后复制

这种通过 Preload 脚本和 contextBridge 的方式，能够提供更细粒度的控制，只暴露必要的 Node.js 功能，从而大大降低安全风险。

5. 总结

在 Electron 渲染进程中遇到 require is not defined 的问题，通常是因为默认禁用了 Node.js 集成。最直接的解决方案是在主进程创建 BrowserWindow 时，将 webPreferences 中的 nodeIntegration 设置为 true，并将 contextIsolation 设置为 false。

然而，为了构建更安全、更健壮的 Electron 应用，尤其是在涉及加载外部内容或需要高度安全性的场景中，强烈推荐保持 nodeIntegration: false 和 contextIsolation: true 的默认设置，并通过 Preload 脚本结合 contextBridge 来安全地桥接渲染进程与 Node.js 功能。理解并应用这些安全实践，对于开发高质量的 Electron 应用至关重要。

以上就是Electron 渲染进程中 require 模块引用失败的解决方案与安全考量的详细内容，更多请关注php中文网其它相关文章！