跳至主要内容

上下文隔离

什么是上下文隔离？​

上下文隔离是一项功能，它确保您的preload脚本和 Electron 的内部逻辑在与您在webContents中加载的网站不同的上下文中运行。这对于安全目的非常重要，因为它有助于防止网站访问 Electron 内部或您的 preload 脚本可以访问的强大 API。

这意味着您的 preload 脚本可以访问的window对象实际上与网站可以访问的对象是**不同的**。例如，如果您在 preload 脚本中设置了window.hello = 'wave'并且启用了上下文隔离，则如果网站尝试访问它，window.hello将为未定义。

从 Electron 12 开始，默认情况下已启用上下文隔离，并且它是**所有应用程序**的推荐安全设置。

迁移​

在没有上下文隔离的情况下，我过去常常使用window.X = apiObject从我的 preload 脚本提供 API。现在怎么办？

之前：上下文隔离已禁用​

将 API 从您的 preload 脚本公开到渲染器进程中加载的网站是一种常见的用例。在禁用上下文隔离的情况下，您的 preload 脚本将与渲染器共享一个公共的全局window对象。然后，您可以将任意属性附加到 preload 脚本

preload.js
// preload with contextIsolation disabled
window.myAPI = {
  doAThing: () => {}
}

然后可以在渲染器进程中直接使用doAThing()函数

renderer.js
// use the exposed API in the renderer
window.myAPI.doAThing()

之后：上下文隔离已启用​

Electron 中有一个专门的模块可以帮助您以一种轻松的方式做到这一点。contextBridge模块可用于安全地将 API 从 preload 脚本的隔离上下文公开到网站运行的上下文。该 API 也将像以前一样从网站上的window.myAPI访问。

preload.js
// preload with contextIsolation enabled
const { contextBridge } = require('electron')

contextBridge.exposeInMainWorld('myAPI', {
  doAThing: () => {}
})
renderer.js
// use the exposed API in the renderer
window.myAPI.doAThing()

请阅读上面链接的contextBridge文档以充分了解其局限性。例如，您无法通过桥发送自定义原型或符号。

安全注意事项​

仅仅启用contextIsolation和使用contextBridge并不自动意味着您所做的一切都是安全的。例如，此代码是**不安全的**。

preload.js
// ❌ Bad code
contextBridge.exposeInMainWorld('myAPI', {
  send: ipcRenderer.send
})

它直接公开了一个强大的 API，没有任何参数过滤。这将允许任何网站发送任意 IPC 消息，而您不希望这种情况发生。公开基于 IPC 的 API 的正确方法是为每个 IPC 消息提供一个方法。

preload.js
// ✅ Good code
contextBridge.exposeInMainWorld('myAPI', {
  loadPreferences: () => ipcRenderer.invoke('load-prefs')
})

与 TypeScript 的用法​

如果您使用 TypeScript 构建 Electron 应用程序，则需要向通过上下文桥公开的 API 添加类型。除非您使用声明文件扩展类型，否则渲染器的window对象将没有正确的类型。

例如，给定此preload.ts脚本

preload.ts
contextBridge.exposeInMainWorld('electronAPI', {
  loadPreferences: () => ipcRenderer.invoke('load-prefs')
})

您可以创建一个interface.d.ts声明文件并全局增强Window接口

interface.d.ts
export interface IElectronAPI {
  loadPreferences: () => Promise<void>,
}

declare global {
  interface Window {
    electronAPI: IElectronAPI
  }
}

这样做将确保 TypeScript 编译器在渲染器进程中编写脚本时了解全局window对象上的electronAPI属性

renderer.ts
window.electronAPI.loadPreferences()