跳转到主要内容

Electron 中的 ES 模块 (ESM)

简介​

ECMAScript 模块 (ESM) 格式是 加载 JavaScript 包的标准方式。

Chromium 和 Node.js 都有各自的 ESM 规范实现，Electron 会根据上下文选择使用哪个模块加载器。

本文档旨在概述 Electron 中 ESM 的限制，以及 Electron、Node.js 和 Chromium 中 ESM 之间的差异。

信息

此功能是在 electron@28.0.0 中添加的。

ESM 支持矩阵概述​

下表概述了 ESM 的支持情况以及使用的 ESM 加载器。

进程ESM 加载器预加载脚本中的 ESM 加载器适用要求
主进程Node.jsN/A
渲染器 (沙盒)Chromium不支持
渲染器 (非沙盒 & 上下文隔离)ChromiumNode.js
渲染器 (非沙盒 & 非上下文隔离)ChromiumNode.js

主进程​

Electron 的主进程在 Node.js 上下文中运行，并使用其 ESM 加载器。使用应遵循 Node 的 ESM 文档。要在主进程中的文件中启用 ESM，必须满足以下条件之一

  • 该文件以 .mjs 扩展名结尾
  • 最近的父 package.json 中设置了 "type": "module"

有关更多详细信息，请参阅 Node 的 确定模块系统 文档。

注意事项​

您必须在应用程序的 ready 事件之前大量使用 await​

ES 模块是异步加载的。这意味着只有主进程入口点的导入才会影响 ready 事件之前的副作用。

这一点很重要，因为某些 Electron API（例如 app.setPath）需要在发出应用程序的 ready 事件之前调用。

由于 Node.js ESM 中提供了顶级 await，请确保 await 您需要在 ready 事件之前执行的每个 Promise。否则，您的应用程序可能在您的代码执行之前就已 ready。

对于动态 ESM 导入语句（静态导入不受影响），这一点尤其重要。例如，如果 index.mjs 在顶部调用 import('./set-up-paths.mjs')，则应用程序很可能在动态导入解析之前就已经 ready 了。

index.mjs (主进程)
// add an await call here to guarantee that path setup will finish before `ready`
import('./set-up-paths.mjs')

app.whenReady().then(() => {
  console.log('This code may execute before the above import')
})
转译器转换

JavaScript 转译器（例如 Babel、TypeScript）在 Node.js 支持 ESM 导入之前，就已经通过将这些调用转换为 CommonJS require 调用来支持 ES 模块语法。

示例：@babel/plugin-transform-modules-commonjs

@babel/plugin-transform-modules-commonjs 插件会将 ESM 导入转换为 require 调用。确切的语法取决于 importInterop 设置。

@babel/plugin-transform-modules-commonjs
import foo from "foo";
import { bar } from "bar";
foo;
bar;

// with "importInterop: node", compiles to ...

"use strict";

var _foo = require("foo");
var _bar = require("bar");

_foo;
_bar.bar;

这些 CommonJS 调用会同步加载模块代码。如果您正在将转译的 CJS 代码迁移到原生 ESM，请注意 CJS 和 ESM 之间的时序差异。

渲染器进程​

Electron 的渲染器进程在 Chromium 上下文中运行，并将使用 Chromium 的 ESM 加载器。实际上，这意味着 import 语句

  • 无法访问 Node.js 内置模块
  • 无法加载 node_modules 中的 npm 包
<script type="module">
    import { exists } from 'node:fs' // ❌ will not work!
</script>

如果您希望通过 npm 直接将 JavaScript 包加载到渲染器进程中，我们建议使用 webpack 或 Vite 等打包器来为客户端使用编译您的代码。

预加载脚本​

渲染器的预加载脚本将在可用时使用 Node.js ESM 加载器。ESM 的可用性取决于其渲染器的 sandbox 和 contextIsolation 首选项的值，并且由于 ESM 加载的异步性质，还存在一些其他注意事项。

注意事项​

ESM 预加载脚本必须使用 .mjs 扩展名​

预加载脚本将忽略 "type": "module" 字段，因此您必须在 ESM 预加载脚本中使用 .mjs 文件扩展名。

沙盒预加载脚本无法使用 ESM 导入​

沙盒预加载脚本作为纯 JavaScript 运行，没有 ESM 上下文。如果您需要使用外部模块，我们建议为您的预加载代码使用打包器。加载 electron API 仍然通过 require('electron') 完成。

有关沙盒的更多信息，请参阅 进程沙盒 文档。

非沙盒 ESM 预加载脚本将在没有内容的页面的页面加载后运行​

如果渲染器加载页面的响应体完全为空（即 Content-Length: 0），则其预加载脚本不会阻止页面加载，这可能会导致竞争条件。

如果这影响到您，请更改您的响应体以包含某些内容（例如一个空的 html 标签 (<html></html>))，或者切换回使用 CommonJS 预加载脚本 (.js 或 .cjs)，它将阻止页面加载。

ESM 预加载脚本必须进行上下文隔离才能使用动态 Node.js ESM 导入​

如果您的非沙盒渲染器进程未启用 contextIsolation 标志，则无法通过 Node 的 ESM 加载器动态 import() 文件。

preload.mjs
// ❌ these won't work without context isolation
const fs = await import('node:fs')
await import('./foo')

这是因为 Chromium 的动态 ESM import() 函数通常在渲染器进程中优先，并且如果没有上下文隔离，则无法知道 Node.js 是否在动态导入语句中可用。如果您启用上下文隔离，则来自渲染器的隔离预加载上下文的 import() 语句可以路由到 Node.js 模块加载器。