跳到主要内容

Electron 中的 ES Modules (ESM)

引言​

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

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

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

信息

此功能在 electron@28.0.0 中添加。

总结：ESM 支持矩阵​

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

进程ESM 加载器Preload 中的 ESM 加载器适用要求
主进程Node.js不适用
渲染器进程 (沙盒化)Chromium不支持
渲染器进程 (非沙盒化 和 上下文隔离)ChromiumNode.js
渲染器进程 (非沙盒化 和 无上下文隔离)ChromiumNode.js

主进程​

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

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

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

注意事项​

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

ES Modules 是异步加载的。 这意味着只有主进程入口点的导入产生的副作用会在 ready 事件之前执行。

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

由于 Node.js ESM 中支持顶层 await，请确保对需要在 ready 事件之前执行的每个 Promise 都使用 await。 否则，您的应用可能会在您的代码执行之前就 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 Module 语法。

示例: @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 模块加载器。