安全暴露 Node.js 能力给渲染进程

在 Electron 中，渲染进程负责界面展示和用户交互，但它天然被隔离在一个类似浏览器的沙箱环境中。如果直接把 Node.js 的 fs、child_process 等模块暴露给渲染进程，一旦页面存在 XSS 漏洞，攻击者就可以任意读写用户文件或执行系统命令，后果非常严重。正因为如此，Electron 官方从安全角度出发，强烈不建议在渲染进程中直接开启 nodeIntegration，而是推荐通过一套受控的桥接机制来暴露能力。

为什么不能直接启用 `nodeIntegration`

在早期 Electron 版本中，许多教程会教你设置：

const win = new BrowserWindow({
  webPreferences: {
    nodeIntegration: true,   // 危险！
    contextIsolation: false, // 同样危险！
  }
});

这样做的结果是：渲染进程中的 JavaScript 可以毫无限制地 require('fs')、require('child_process')，甚至直接调用 Electron 的原生模块。这在开发阶段看似方便，但一旦你的应用加载了任何不受信任的内容（例如第三方广告 SDK、带有用户生成内容的页面、或者仅仅是一个被恶意篡改的远程脚本），攻击者就能获得操作系统的完整访问权限。

Electron 官方文档明确将这种配置标记为高风险，并在较新版本中默认启用了更安全的环境：nodeIntegration 默认为 false，contextIsolation 默认为 true。

安全方案：Preload + contextBridge

现代 Electron 应用的标准做法是：在渲染进程和主进程之间插入一个预加载脚本（preload script），通过 contextBridge 将主进程的能力精确、受控地暴露给渲染进程。

整体流程如下：

主进程创建一个窗口，并指定一个 preload.js 文件。
preload.js 运行在一个同时可以访问 Node.js API 和 DOM 的特殊环境中，但它不会直接污染渲染进程的全局作用域。
preload.js 使用 contextBridge.exposeInMainWorld 方法，将一些封装好的函数挂载到渲染进程的 window 对象上（例如 window.electronAPI）。
渲染进程只能通过这个事先定义好的 API 与主进程通信，无法直接触碰任何 Node.js 或 Electron 底层模块。

这种做法就像在渲染进程和系统能力之间加了一道安检门：所有的权限请求都必须经过预定义的安全通道，所有参数和返回值都是可以被验证和清理的。

具体实现示例

假设我们要让渲染进程能调用系统原生的“打开文件”对话框，并将选中的文件内容读取后返回给页面。

第一步：主进程代码（main.js）

const { app, BrowserWindow, ipcMain, dialog } = require('electron');
const fs = require('fs');
const path = require('path');

function createWindow() {
  const win = new BrowserWindow({
    width: 800,
    height: 600,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'), // 指定预加载脚本
      contextIsolation: true,   // 开启上下文隔离（默认值）
      nodeIntegration: false,   // 关闭 Node 集成（默认值）
    }
  });

  win.loadFile('index.html');
}

// 监听渲染进程发来的 “打开文件并读取” 请求
ipcMain.handle('dialog:openFile', async () => {
  const { canceled, filePaths } = await dialog.showOpenDialog({
    properties: ['openFile'],
    filters: [{ name: 'Text Files', extensions: ['txt', 'md'] }]
  });

  if (canceled || filePaths.length === 0) {
    return null;
  }

  const filePath = filePaths[0];
  const content = fs.readFileSync(filePath, 'utf-8');
  return { filePath, content };
});

app.whenReady().then(createWindow);

第二步：预加载脚本（preload.js）

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

// 向渲染进程暴露一个名为 electronAPI 的全局对象
contextBridge.exposeInMainWorld('electronAPI', {
  // 只暴露一个方法：打开文件并获取内容
  openFile: () => ipcRenderer.invoke('dialog:openFile'),
  
  // 你也可以暴露其他安全的方法，例如监听主进程消息
  onUpdateAvailable: (callback) => {
    ipcRenderer.on('update-available', (event, ...args) => callback(...args));
  }
});

这里非常关键的一点是：contextBridge 保证了渲染进程只能访问到 window.electronAPI 这个对象，而无法通过这个对象回溯到 require 或其他 Node.js 全局变量。同时，ipcRenderer.invoke 和 ipcRenderer.on 只是通信管道，它们本身并不执行任何危险操作，真正的文件读取操作发生在主进程，由主进程根据业务逻辑进行严格的权限管控。

第三步：渲染进程代码（renderer.js）

// 在页面中，通过 window.electronAPI 调用预定义的方法
document.getElementById('openBtn').addEventListener('click', async () => {
  const result = await window.electronAPI.openFile();
  if (result) {
    document.getElementById('content').textContent = result.content;
    console.log(`已打开文件: ${result.filePath}`);
  }
});

渲染进程完全没有接触到 fs 或 dialog，它只是调用了一个普通的 async 函数，而这个函数底层通过 IPC 通道请求主进程去执行实际操作。即使页面被注入恶意脚本，攻击者能调用的也仅仅是我们预先暴露的那几个方法，而无法执行任意系统命令。

设计安全 API 的实用原则

在实际项目中，设计暴露给渲染进程的 API 时，可以遵循以下几条经验准则：

最小权限原则：只暴露当前业务真正需要的方法。对于“打开文件”这种场景，只暴露一个封装的 openFile 函数，而不是直接把 dialog.showOpenDialog 抛给渲染进程。
参数验证：在主进程里，对所有从渲染进程传过来的参数进行严格的类型和范围检查，避免注入攻击。
避免暴露敏感操作：尽量将敏感操作（如删除文件、执行命令、修改系统配置）封装在主进程的高阶业务逻辑中，并通过明确的 IPC 通道触发，而不是暴露一个泛化的执行器。
区分只读与写入：如果某个 API 只应该读取配置，就不要给它写入文件的能力；如果只应该打开特定格式的文件，就在主进程端做好校验。
使用 shell.openPath 等安全封装：如果需要打开外部链接或文件，始终通过 shell.openExternal 或相关安全 API，而不是使用 child_process 执行 open 命令。

总结

安全暴露 Node.js 能力给渲染进程，核心就在于 “切断直接通路，建立受控桥梁”。通过 preload.js + contextBridge + IPC 的三层协作，我们既能保留前端开发的便利性，又能将系统权限牢牢锁在主进程的严密看守之下。这套模式经过了无数企业级应用的实战检验（VS Code、Slack、Figma 等均采用类似架构），是 Electron 开发中必须掌握的安全基线。

安全暴露 Node.js 能力给渲染进程

为什么不能直接启用 nodeIntegration

安全方案：Preload + contextBridge

具体实现示例

设计安全 API 的实用原则

总结

为什么不能直接启用 `nodeIntegration`