上下文隔离

上下文隔离

上下文隔离是什么？

上下文隔离功能将确保您的 预加载脚本和 Electron的内部逻辑运行在所加载的 webcontent网页之外的另一个独立的上下文环境里。这对安全性很重要，因为它有助于阻止网站访问 Electron 的内部组件和您的预加载脚本可访问的高等级权限的API 。

这意味着，实际上，您的预加载脚本访问的 window 对象并不是网站所能访问的对象。例如，如果您在预加载脚本中设置 window.hello = 'wave ' 并且启用了上下文隔离，当网站尝试访问window.hello对象时将返回未定义。

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

迁移

Without context isolation, I used to provide APIs from my preload script using window.X = apiObject. Now what?

之前：上下文隔离禁用

Exposing APIs from your preload script to a loaded website in the renderer process is a common use-case. With context isolation disabled, your preload script would share a common global window object with the renderer. You could then attach arbitrary properties to a preload script:

preload.js

// 上下文隔离禁用的情况下使用预加载
window.myAPI = {
  doAThing: () => {}
}

The doAThing() function could then be used directly in the renderer process:

renderer.js

// 在渲染器中使用开放的 API
window.myAPI.doAThing()

之后：启用上下文隔离

There is a dedicated module in Electron to help you do this in a painless way. The contextBridge module can be used to safely expose APIs from your preload script’s isolated context to the context the website is running in. API 还可以像以前一样，从 window.myAPI 网站上访问。

preload.js

// 在上下文隔离启用的情况下使用预加载
const { contextBridge } = require('electron')
contextBridge.exposeInMainWorld('myAPI', {
  doAThing: () => {}
})

renderer.js

// 在渲染器中使用开放的 API
window.myAPI.doAThing()

Please read the contextBridge documentation linked above to fully understand its limitations. For instance, you can’t send custom prototypes or symbols over the bridge.

安全事项

单单开启和使用 contextIsolation 并不直接意味着您所做的一切都是安全的。例如，此代码是 不安全的。

preload.js

// ❌ 错误使用
contextBridge.exposeInMainWorld('myAPI', {
  send: ipcRenderer.send
})

它直接暴露了一个没有任何参数过滤的高等级权限 API 。这将允许任何网站发送任意的 IPC 消息，这不会是你希望发生的。相反，暴露进程间通信相关 API 的正确方法是为每一种通信消息提供一种实现方法。

preload.js

// ✅ 正确使用
contextBridge.exposeInMainWorld('myAPI', {
  loadPreferences: () => ipcRenderer.invoke('load-prefs')
})

与Typescript一同使用

If you’re building your Electron app with TypeScript, you’ll want to add types to your APIs exposed over the context bridge. The renderer’s window object won’t have the correct typings unless you extend the types with a declaration file.

For example, given this preload.ts script:

preload.ts

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

You can create a renderer.d.ts declaration file and globally augment the Window interface:

renderer.d.ts

export interface IElectronAPI {
  loadPreferences: () => Promise<void>,
}
declare global {
  interface Window {
    electronAPI: IElectronAPI
  }
}

Doing so will ensure that the TypeScript compiler will know about the electronAPI property on your global window object when writing scripts in your renderer process:

renderer.ts

window.electronAPI.loadPreferences()

上下文隔离

上下文隔离