ECMAScript 模块是 JavaScript 的标准化模块系统,由 ECMAScript 语言规范定义。它提供明确的语法,用于从一个模块导出值并将其导入另一个模块,同时规定了依赖解析、绑定连接以及相互关联的代码的求值规则。该系统于 ECMAScript 2015 中引入,为浏览器、服务器运行时和开发工具中的模块化 JavaScript 提供了共同的语言层面基础。
ECMAScript 模块的核心特性包括静态声明的依赖、模块局部作用域,以及实时绑定:导入的名称指向导出的绑定,而不只是获得其初始值的副本。这些特性有助于尽早发现错误、进行可预测的依赖分析,并支持一些在不受限制的运行时加载机制下难以实现的优化。动态导入和顶层 await 在此基础上进一步支持按条件加载和异步初始化。
语言规范并未规定查找文件、下载资源或解释包名的通用方式。这些职责主要由宿主环境承担。因此,要理解 ECMAScript 模块,就需要区分其共通的语言语义与网页浏览器、Node.js 和构建系统各自的加载及解析约定。
起源与标准化
早期的 JavaScript 程序通常由加载到共享全局环境中的脚本组成。在网页浏览器中,多个脚本元素可以引入供后续脚本使用的函数和变量,但它们之间的依赖关系是隐含的。程序能否正确运行,取决于加载顺序以及能否避免全局名称冲突。立即调用函数表达式和命名空间对象缓解了其中一些问题,但并未提供标准化的依赖机制。
随着 JavaScript 应用规模的扩大,出现了几种互不兼容的模块约定。CommonJS 广泛用于服务端 JavaScript 和 Node.js,使用 require() 等函数,以及通过 module.exports 提供的导出对象。其常规加载模型是同步的,相比网络资源,更适合本地文件。异步模块定义(通常缩写为 AMD)采用了另一种专为异步加载设计的接口,尤其适用于浏览器。有些库会提供封装代码,用于识别不同的运行环境,并选择合适的导出机制。
模块标准化是由 Ecma 第 39 技术委员会制定的 ECMAScript 2015 这一更大范围修订的一部分。该版本于 2015 年发布,也称为 ES6,在引入类、词法声明和箭头函数等特性的同时,还引入了 import 和 export 声明。模块设计将语言语义与宿主环境的加载机制分离:ECMAScript 规定导入和导出的行为,而浏览器和服务器的相关规范则提供资源发现与获取规则。浏览器原生实现晚于语言规范出现,各大浏览器引擎在 2017 年至 2018 年间陆续支持了这一标准。
后续的语言版本在不替换核心架构的前提下扩展了这一系统。ECMAScript 2020 将动态 import() 和 import.meta 纳入标准,使程序能够在执行期间请求模块,并查看宿主环境提供的模块元数据。ECMAScript 2022 将顶层 await 纳入标准,使模块的初始化可以依赖异步操作。这些新增功能弥补了仅使用静态声明的局限,同时保留了相同的底层模块图和绑定模型。
最终形成的标准并不只是 CommonJS 或 AMD 的改名版本。其中的导入是具有链接语义的语言结构,而非普通的函数调用或对象属性赋值。与此同时,这一标准的普及并未淘汰旧有系统。现有软件包、运行时兼容性要求和部署实践,使新旧系统长期共存。因此,现代 JavaScript 项目中可能既有标准的 ECMAScript 模块,也有 CommonJS 依赖、自动生成的兼容性封装代码,以及特定工具所执行的代码转换。
声明、导出与模块作用域
JavaScript 源文本既可以按脚本解析,也可以按模块解析。这一区别取决于宿主对解析和执行方式的选择,并非一概由文件扩展名决定。静态 import 声明和 export 声明属于模块语法。不过,模块不必包含这两种声明中的任何一种:例如,在浏览器中显式标记为模块的脚本,即使不导出任何内容,也仍然是模块。
具名导出将对外可见的名称与局部绑定关联起来。它们既可以与声明一同出现,也可以写在单独的导出列表中:
// arithmetic.js
export const unit = 1;
function add(a, b) {
return a + b;
}
export { add, add as sum };
使用方可以导入选定的导出项,并在本地为其重命名:
import { unit, add as combine } from "./arithmetic.js";
具名导入中的花括号用于指定模块导入列表,并不是对象解构操作。不引入绑定的导入语句,例如 import "./initialize.js";,仍然会建立依赖关系,并使被导入的模块得到求值,以执行其中具有副作用的操作。
模块也可以使用特殊名称 default 对外提供一个导出项。使用方可以自行选择该默认导入在本地使用的名称:
// formatter.js
export default function format(value) {
return String(value);
}
// consumer.js
import renderValue from "./formatter.js";
默认导出和具名导出可以共存。命名空间导入的写法为 import * as arithmetic from "./arithmetic.js";,它通过命名空间对象提供对模块导出项的访问。再导出声明可用于构建中间模块:export { add } from "./arithmetic.js"; 会转发指定的导出项,但不会创建名为 add 的局部绑定。声明 export * from "./arithmetic.js"; 会转发具名导出,但不包括默认导出。如有需要,可以通过显式声明转发默认导出。
模块作用域不同于传统脚本的全局作用域。顶层声明保留在模块内部,不会自动成为全局对象的属性。模块代码始终采用严格模式语义,顶层的 this 为 undefined。这些规则减少了意外写入全局状态的情况,也消除了非严格模式 JavaScript 中一些历史遗留的歧义,但并不妨碍模块有意修改全局可访问的对象。
静态导入和导出声明必须出现在模块顶层,不能放在函数或条件语句内部。它们在其他顶层语句之间所处的位置,并不意味着它们是按顺序执行的普通加载命令:依赖项会在模块主体执行之前得到处理。重复的导出名称以及各种相互冲突的声明都会导致语法错误。而从标准源文本模块中导入不存在的具名导出,通常是在模块依赖图的链接阶段被检测出来的。
实时绑定与模块命名空间对象
ECMAScript 模块与许多基于对象的模块约定之间,最核心的语义差异在于实时绑定。导入所引用的是由导出模块维护的绑定。如果导出模块更改了该绑定,随后通过导入读取时就会得到新值:
// counter.js
export let count = 0;
export function increment() {
count += 1;
}
// consumer.js
import { count, increment } from "./counter.js";
console.log(count); // 0
increment();
console.log(count); // 1
导入模块不能给 count 赋值。尝试赋值会在执行时抛出 TypeError。这一限制针对的是导入的绑定,而不一定是绑定所持有的值。如果模块导出一个对象,其他模块仍可修改该对象的属性,除非该对象受到其他保护。因此,不可变的导入引用并不等同于深度不可变的导出数据。
默认导出还需要进一步区分。export default expression; 会对表达式求值,并用所得的值初始化模块的默认绑定。通常,它不会与表达式中提到的任何变量建立持续关联。相比之下,export { value as default }; 导出的是名为 value 的现有局部绑定。如果之后对该绑定重新赋值,使用默认导出的模块就会读到重新赋予的值。当默认导出表示的是不断变化的状态,而非固定的函数或对象时,这一区别尤为重要。
模块命名空间对象提供了一种通过属性访问导出的方式。对于 import * as counter from "./counter.js"; 这样的命名空间导入,读取 counter.count 会取得当前导出的值。命名空间对象是 ECMAScript 定义的特殊对象,而不是普通的可变字典。使用方不能对其中以导出名称为键的属性重新赋值或将其删除;命名空间对象不可扩展,且原型为 null。导出名称按规定的字典序排列。
一些反射层面的细节说明了为什么不能简单地将命名空间对象理解为被冻结的普通对象。导出属性的描述符显示为 writable: true,但该对象专门定义的内部赋值行为会拒绝写入。这种描述符与导出值可以通过其原始绑定发生变化这一事实相容;它并未赋予导入方修改该值的权限。因此,不能用 Object.freeze() 来概括解释命名空间对象的行为。
复制命名空间对象也会丢失它的一部分语义。对象展开、解构到局部变量,或将导入的属性赋给另一个变量,读取的都是当时的值。新属性或新变量不会自动跟踪原始导出后续的重新赋值。对于共享配置、计数器、运行时注册表,以及将模块转换为普通对象的兼容层,区分实时绑定与复制的值十分重要。
依赖图、链接与循环导入
静态导入描述了一张依赖图,其中节点是模块,边表示所请求的依赖关系。模块处理通常分为三个大致阶段:加载与解析、链接、求值。规范中的具体算法和宿主接口更为细致,但这样的划分区分了获取源代码、关联名称以及执行模块体这几个环节。
在加载阶段,宿主会解析模块说明符,并使所需的模块可用。模块说明符是 import { value } from "./state.js"; 这类声明中的字符串。ECMAScript 语言并未统一规定这个字符串指向的是文件、网络资源,还是包注册表中的条目。相关模块记录就绪后,链接阶段会将导入的名称解析到导出的绑定,并构建执行所需的环境。缺失或存在歧义的导出可能导致链接失败,而此时普通的模块体副作用尚未发生。
对于无环的同步依赖图,依赖模块会先于依赖它们的模块求值。如果一个模块经由多条路径被导入,只要宿主识别出的模块身份相同,该模块通常就只会求值一次。这并不意味着相同的源文本在任何情况下都只对应一个实例:不同的解析后身份、执行上下文或宿主缓存,都可能产生不同的实例。共享依赖之所以能够共享,是因为宿主和模块机制识别出了同一个模块记录,而不是因为源文本恰好相同。
模块支持循环依赖,因为在所有模块体执行完毕之前,就可以先将绑定关联起来。假设模块 A 从 B 导入一个函数,而 B 从 A 导入一个值。这张依赖图仍然可以完成链接,但求值能否成功,取决于 B 在何时读取 A 中的值。使用 let、const 或 class 声明的词法绑定,在初始化之前不能被读取。因此,过早读取会引发 ReferenceError,而不是得到一个尚未填充完整的导出对象。
函数声明体现了循环结构与不安全的访问时机之间的区别。通过模块环境的初始化,即使某个模块的模块体尚未执行,它导出的函数也可能已经可用。不过,如果调用该函数时,它立即读取了尚未初始化的词法绑定,调用仍然可能失败。因此,存在循环既不意味着必然出错,也不意味着必然安全。
规范通过强连通分量和深度优先遍历机制来处理循环依赖图,这些机制与标准图算法有关。异步求值还会引入更多状态,包括待完成的依赖,以及表示求值完成的 Promise。在实际架构中,将一次读取操作从模块初始化阶段移到稍后调用的函数中,就可能把无效的循环交互变为有效的交互。反过来,一个看似微不足道的顶层计算,也可能暴露出此前潜藏的初始化顺序问题。
动态导入与异步初始化
动态 import() 在执行期间请求模块,并返回一个 Promise。与静态导入声明不同,它可以出现在函数、条件分支或其他表达式上下文中,而且其模块说明符可以通过计算得到:
async function openEditor() {
const { createEditor } = await import("./editor.js");
return createEditor();
}
Promise 兑现时的值通常是所请求模块的命名空间对象。只有解析、加载、链接和求值全部成功,导入操作才能成功完成。失败会通过 Promise 拒绝来报告,因此调用方可以使用常规的 Promise 机制处理资源不可用、语法无效、缺少导出或初始化期间出现异常等情况。
动态导入不仅可以用于模块源代码,也可以用于其他上下文,包括支持它的传统脚本环境。但使用动态导入并不意味着目标会被解释为传统脚本:所请求的资源会按照宿主的模块规则处理。对于被识别为同一模块的资源,多次成功导入通常会复用已有的模块实例。因此,动态导入是一种加载接口,而不是用于从头重新执行文件的通用命令。
顶层 await 解决的是另一个问题:模块在可供使用之前必须完成的异步工作。模块可以等待配置请求、初始化数据库连接,或选择动态导入的实现,然后再完成模块体的执行。在下面的示例中,依赖该配置模块的模块,必须等到配置模块执行完成后,才能完成自身的常规求值:
// configuration.js
const response = await fetch("./configuration.json");
if (!response.ok) {
throw new Error("Configuration request failed");
}
export const configuration = await response.json();
顶层 await 不会冻结整个运行时,也不会不加区分地阻塞依赖图中的所有模块。它会暂停相关模块的求值,并延迟那些必须等到该模块完成后才能执行的模块。其他满足执行条件的工作仍可通过宿主的事件循环和异步调度机制继续推进。这种行为将模块求值与异步编程直接联系起来,而不再将初始化视为必然同步的过程。
异步初始化与循环依赖之间的相互作用需要格外谨慎地处理。异步模块可能直接或间接地依赖某项工作,而该工作只有在这个模块自身执行完成后才能进行。在某些这类安排中,相关操作可能始终无法敲定,也可能以其他方式失败,具体取决于所涉及的操作;支持循环依赖并不意味着任意异步依赖都能顺利推进。初始化被拒绝时,也会将失败传播到依赖模块的求值过程和动态导入的调用方。
一个特殊的边界情况涉及名为 then 的可调用导出。由于动态导入会以命名空间对象兑现 Promise,Promise 解析过程可能将该对象视为 thenable,并调用其导出的 then 函数。静态命名空间导入不会进行这种 Promise 同化。这种不寻常的相互作用源于模块命名空间与通用 Promise 解析协议的结合,而不是某项独立的模块加载功能。
浏览器加载、URL 与导入映射
在 超文本标记语言中,带有 type="module" 的 script 元素表示按模块方式处理脚本:
<script type="module" src="/app/main.js"></script>
通常,由解析器插入的模块脚本在执行时,不会像未设置 defer 或 async 的传统脚本那样阻塞解析器。它会推迟到文档解析完毕且依赖项准备就绪后再求值。添加 async 会改变调度方式:模块图可以在准备就绪时执行,而不必等待常规的延迟执行顺序。顶层 await 还可能进一步拉开开始求值与最终完成求值之间的时间间隔。
浏览器中的模块说明符通常按照 统一资源定位符的解析规则处理。相对路径以引用该模块的模块 URL 为基准进行解析,而不是以恰好导入它的 HTML 文档为基准。浏览器通常不会搜索目录,也不会自动补上 .js。像 "utility-library" 这样的裸说明符本身并不具有指向包目录的内置含义,需要适用的映射或宿主支持的其他机制才能解析。
导入映射以声明方式提供从说明符到 URL 的映射。它通过带有 type="importmap" 的 script 元素嵌入 HTML,元素内容采用 JSON 格式。imports 对象定义通用映射,而 scopes 可以根据导入方模块的 URL 选择映射。当键和目标都采用规定的尾随斜杠形式时,前缀映射可以将整组说明符重定向到其他位置。导入映射影响的是解析过程;它不会安装包、合并源文件,也不会转换语言语法。
浏览器获取模块时,还受 Web 平台的安全与资源规则约束。跨源模块请求使用 CORS,因此,即使某个资源可以公开访问,只要服务器没有提供适当的访问控制响应头,它仍可能无法作为模块使用。JavaScript 模块响应必须具有可接受的 JavaScript 媒体类型。因此,如果服务器针对缺失的模块返回 HTML 错误页面,即使响应状态码表示成功,也会导致加载失败。本地 file: URL 的行为也不同于通过常规 HTTP 服务提供的模块应用。
由宿主定义的 import.meta 对象提供与当前模块相关的元数据。在浏览器中,import.meta.url 表示模块的 URL,因此可以编写 new URL("./image.png", import.meta.url) 这样的表达式。其底层 ECMAScript 结构已经标准化,但具体属性和附加方法取决于宿主。
模块加载也适用于支持它的 worker 环境,可以通过指定模块类型来创建 worker。浏览器还提供 modulepreload 链接,以便在按常规方式发现模块资源之前,提前开始处理这些资源。这些机制会改变资源获取方式和执行上下文,但不会改变实时绑定或导出语义。在浏览器支持相应模块格式的情况下,导入属性还可以指明预期的模块类型,例如 JSON。
Node.js、包与 CommonJS 互操作
Node.js 在实现 ECMAScript 模块的同时,也保留了较早的 CommonJS 系统。两者使用相同的 JavaScript 语法和值,但在加载方式、作用域、解析规则和导出表示形式上有所不同。显式的格式标识包括表示 ECMAScript 模块的 .mjs 和表示 CommonJS 的 .cjs。包的 package.json 可以使用 "type": "module" 或 "type": "commonjs",指定其适用范围内的 .js 文件应按哪种格式解释。其他检测行为随 Node.js 版本的演进而有所变化,因此,在描述可复现的包行为时,这些显式标识依然十分重要。
Node 的 ECMAScript 模块解析器既能识别相对引用和绝对引用,也能识别面向包的裸说明符。导入相对路径文件时,通常必须写出完整文件名,包括扩展名;Node 不会沿用 CommonJS require() 中人们熟悉的全部扩展名查找和目录索引约定。包元数据可以通过 "exports" 定义公共入口,其中包括子路径和按条件选择的入口。"imports" 字段则提供包内部的映射,按惯例使用以 # 开头的名称。
条件导出可以为使用 import 和 require 的调用方选择不同入口,也可以根据其他受支持的条件选择入口。这样既能兼容两种模块系统,也可能使看似同一个包的两套实现各自独立初始化。如果这些实现维护着内部状态,使用方就可能遇到彼此独立的注册表、不兼容的类身份,或重复的单例对象。因此,包边界和模块身份的影响并不止于表面语法。
通过互操作层,可以在 ECMAScript 模块中导入 CommonJS。默认导入提供 CommonJS 的 module.exports 值。Node 还会尝试通过静态分析常见的赋值模式来识别某些具名导出,但这些推断出的名称并不具备原生 ECMAScript 实时绑定的完整语义。对于通过任意运行时计算构造的 CommonJS 导出,并不总能将其准确表示为可静态发现的具名导出。
反向互操作的方式在 Node 的发展过程中有所变化。较新的版本在规定条件下,支持使用 require() 加载符合要求的同步 ECMAScript 模块图,而较早的版本通常需要使用动态导入。涉及顶层 await 的模块图无法通过普通的同步 require() 操作处理。对于加载或求值过程是异步的模块,动态导入仍是 CommonJS 代码访问它们的重要桥梁。
ECMAScript 模块中也没有 CommonJS 自动提供的包装器变量 require、module、exports、__filename 和 __dirname。Node 通过模块 API 和 import.meta 提供替代方式,具体可用的属性取决于运行时版本。内置功能可以通过 node: 方案显式标识,例如 import { readFile } from "node:fs/promises";。这些约定属于 Node 的宿主环境,并非对浏览器模块或所有 ECMAScript 实现的要求。
构建工具、静态分析与类型系统
导入和导出声明具有静态结构,因此 ECMAScript 模块对编译器、开发服务器和模块打包器尤其有用。工具可以解析模块,识别其声明的依赖关系,并在不执行模块常规语句的情况下构建程序依赖图的大部分。相比之下,从不受限制的调用中发现依赖关系要困难得多,因为这些调用的参数和行为可能只有在运行时才能确定。
打包器利用这张依赖图生成部署产物。它们可以将多个模块合并为一个文件,将其拆分为若干代码块,重写资源引用,或保留选定的外部导入。动态导入通常可作为代码拆分点:某项功能及其依赖可以形成单独的代码块,仅在需要时加载。因此,源码中的模块与输出文件之间究竟如何对应,由工具决定,而不是 ECMAScript 保证的特性。
摇树优化会移除构建工具能够确定为不必要的代码。显式的导出和导入使工具能够追踪哪些绑定被使用,但仅凭某个导出未被使用,并不足以移除所有与之关联的语句。顶层函数调用可能会注册事件处理程序、修改共享状态,或执行外部可观察到的操作。能否安全地消除代码,取决于副作用分析、包元数据以及构建配置中设定的假设。
例如,一个导出十个实用函数的模块,可能允许移除其中九个未使用的函数体。但如果该模块还会在导入时执行一个注册函数,那么这项初始化操作可能仍须保留。包声明中的 "sideEffects" 字段等属于构建工具的约定,有助于表达这类区别;它们不会改变语言的求值规则。错误的元数据可能导致原本合理的构建变换移除应用程序所依赖的行为。
TypeScript 通过区分运行时值与类型,引入了另一个层面。import type 声明是 TypeScript 中用于表达编译时关系的语法结构,在生成的 JavaScript 中会被移除。运行时导入仍须遵守目标宿主环境的模块规则。因此,TypeScript 的解析器和代码生成设置需要与预期环境相匹配,包括 Node 包的条件配置或打包器特有的解析方式。通过类型检查本身,并不能证明浏览器或服务器能够加载最终得到的模块说明符。
将 ECMAScript 模块转换为 CommonJS 或其他格式,也会面临语义方面的约束。转换过程可以使用 getter 模拟实时导出,但要处理循环依赖、命名空间细节、异步初始化和求值顺序,可能远非将 import 替换为 require() 那么简单。源码映射有助于在调试时将生成的输出对应到原始模块,而如果测试只针对转换后的代码运行,就可能无法发现原生模块加载时才会出现的差异。
安全边界、模块标识与性能
模块作用域是组织代码的边界,而不是安全沙箱。导入的代码通常拥有其运行环境所提供的能力。浏览器中的代码可以与对其开放的 Web API 交互,而 Node.js 依赖项则可能根据运行时的权限和配置访问文件、进程或网络功能。显式导入能更清楚地呈现依赖关系,但不会因此使依赖项变得可信,也不会自动限制其权限。
在 Web 上,安全控制分布在多个层面。CORS 根据相应的跨源规则,控制浏览器是否可以允许使用获取到的资源。内容安全策略可以限制允许执行和加载的脚本。在相关加载机制支持的情况下,子资源完整性可以将某些获取到的资源与预期的加密摘要绑定。保护入口模块并不意味着自动保证了所有传递依赖的完整性:整个加载图以及平台适用的控制措施仍然至关重要。
模块标识既影响正确性,也影响资源使用。宿主通常会在相应的加载上下文中,按解析后的标识缓存模块。在基于 URL 的系统中,即使服务器返回相同的源代码文本,更改查询字符串也可能产生不同的模块标识。这些模块可能重复执行初始化,并各自维护独立的状态。反过来,反复导入被识别为同一标识的模块,也不会将其卸载或重置。ECMAScript 没有提供用于清空宿主模块缓存的通用 API。
性能取决于依赖图的形态、传输行为、解析成本和执行工作量,而不只是 import 声明的数量。原生模块可以免去必须进行的打包步骤,并让浏览器复用资源,但发现依赖的过程可能引入额外的网络往返。超文本传输协议的多路复用减少了部分连接相关的开销,却无法消除请求延迟、服务器端工作量,以及编译大量小型资源的成本。预加载、缓存和打包分别针对这一问题的不同方面。
动态加载可以减轻初始下载和求值的负担,但会将延迟转移到首次需要某项功能的时刻。代码块划分过粗,可能会下载大量用不到的代码;划分过细,则可能产生大量请求和调度开销。顶层异步初始化又增加了一个影响因素:如果等待的操作耗时很长,即使是一个很小的模块,也可能拖延依赖它的庞大模块图。
错误出现的时机也与模块架构有关。语法错误和链接错误可能导致模块图无法开始执行,求值时抛出的异常可能中断初始化,而动态导入则会将加载和求值失败转化为 Promise 拒绝。因此,运行问题分析需要区分资源从未被获取、模块链接失败,以及模块体已开始执行但未能成功完成这几种情况。即使应用最终都将它们报告为某项功能不可用,它们仍是不同的故障模式。