跳到主要内容

Electron 中的 ES 模块 (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 加载器预加载中的 ESM 加载器适用要求
主进程Node.js不适用
渲染进程(沙盒化)Chromium不支持
渲染进程(非沙盒化 & 上下文隔离)ChromiumNode.js
渲染进程(非沙盒化 & 非上下文隔离)ChromiumNode.js

主进程

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

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

有关更多详细信息,请参阅 Node.js 的“Determining Module System”文档。

注意事项

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

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

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

鉴于 Node.js ESM 中提供了顶层 await,请确保 awaitready 事件之前需要执行的每个 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')
})
转译器转换

在 Node.js 支持 ESM 导入之前,JavaScript 转译器(例如 Babel、TypeScript)在历史上就已支持 ES 模块语法,方法是将这些调用转换为 CommonJS require 调用。

示例:@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 的可用性将取决于其渲染进程的 sandboxcontextIsolation 首选项的值,并且由于 ESM 加载的异步性质,还存在一些其他注意事项。

注意事项

ESM 预加载脚本必须具有 .mjs 扩展名

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

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

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

有关沙盒化的更多信息,请参阅“Process Sandboxing”文档。

非沙盒化的 ESM 预加载脚本将在页面加载后在无内容的页面上运行

如果渲染进程加载页面的响应正文完全为空(即 Content-Length: 0),则其预加载脚本将不会阻止页面加载,这可能会导致竞争条件。

如果这影响到你,请更改你的响应正文,使其包含一些内容(例如,一个空的 html 标签 (<html></html>))或换回使用 CommonJS 预加载脚本(.js.cjs),这将阻止页面加载。

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

如果你的非沙盒化渲染进程未启用 contextIsolation 标志,则无法通过 Node.js 的 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 模块加载器。