模块

是什么，为什么存在

JavaScript 模块把实现放进独立的顶层作用域，并以明确的导入、导出形成依赖边界。ES 模块（ECMAScript module，ESM）是语言标准定义的模块格式；CommonJS（CJS）则是 Node 生态中仍需维护的另一种格式。新代码通常以 ESM 为主，但依赖包、构建配置或旧服务仍可能位于两种格式的边界上。

模块解决了普通脚本共享全局命名空间和依赖顺序隐含的问题。读取一个文件时，你能从静态 import 看出它依赖哪些模块，并从 export 看出它提供哪些绑定。运行时也能为每个解析后的模块维护独立实例，而不是每次引用都重新执行文件。

一个模块不是任意对象的同义词。export 暴露的是具名绑定，export default 暴露名为 default 的特殊导出；导入整个模块得到的则是 模块命名空间对象（module namespace object） 。它反映模块的导出集合，但不是可随意增删属性的普通配置对象。

你会在浏览器的 <script type="module">、Node 应用、npm 包和打包工具入口中遇到模块。浏览器从 URL 解析依赖，Node 还结合文件扩展名、最近的 package.json 及其 type、exports 和 imports 字段。打包工具可以额外提供别名或省略扩展名等便利，但这些并不会自动成为浏览器或 Node 的原生规则。

静态导入适合启动前已知的依赖，它让工具可以提前建立依赖图。import() 适合确实由功能、语言或路由决定的按需加载，并返回一个 Promise。两者最终都得到同一类模块命名空间语义；动态导入不是 CommonJS require() 的异步拼写。

工作原理

ESM 的处理可以分成解析、实例化和求值。宿主先把每个 模块说明符（module specifier） 解析成模块标识，取得源码并建立依赖图；然后为导出和导入连接绑定；最后按依赖关系执行模块顶层代码。实现可以交错获取工作，但不能破坏这些可观察语义。

静态 import 与 export 只能出现在模块顶层，因此解析器无需运行分支就能发现它们。这个静态结构有利于语法检查、依赖分析和构建优化，但「可静态分析」不等于「一定会被树摇删除」。副作用、再导出方式和具体构建器配置仍会影响产物。

import() 是表达式，可以位于条件、函数或事件处理器中。它先解析说明符，再异步取得并求值目标，最终以模块命名空间对象兑现 Promise。说明符解析或求值失败都会拒绝 Promise，所以错误边界必须覆盖 await import(...) 本身，而不只是导入后的函数调用。

导出与导入形状

命名导出保持原名称，导入方必须使用匹配的名称，也可以用 as 在本地改名。默认导出在每个模块中最多一个，导入方可为它选择任意本地名称。import * as catalog 收集所有导出为命名空间，其中默认导出位于 catalog.default。

export { name } from "./source.js" 会 再导出（re-export） 另一个模块的绑定，但不会在当前模块创建可直接使用的局部变量。export * 不会转发目标模块的 default，而且多个星号来源提供同名导出时会产生歧义。公共入口应明确列出容易冲突或属于稳定 API 的名称。

ESM 导入是只读的 实时绑定（live binding） 。导出模块重新绑定变量后，静态导入方会读到新值；导入方自己不能给该绑定赋值。相比之下，从动态导入结果执行普通对象解构会把当时的属性值赋给新的局部变量，这个局部变量不会继续更新。

标识、缓存与副作用

宿主以解析后的模块标识维护模块实例。对同一标识重复导入通常返回同一个命名空间并共享模块状态，顶层代码不会因每个导入方而重跑。浏览器通常以规范化 URL 标识模块；Node 的 ESM 也按 URL 缓存，查询参数或片段不同可以形成不同实例。

这项规则使模块级缓存和单例状态成为可能，也让顶层副作用影响所有导入方。它不是业务生命周期管理器：测试、请求或租户若需要隔离状态，应显式创建实例。给说明符不断添加时间戳会制造新模块标识，既重复执行副作用，也会让缓存持续增长。

模块说明符分为相对说明符、绝对 URL 和裸说明符等类别。浏览器原生相对导入通常需要完整文件扩展名；裸说明符需要导入映射或其他宿主配置。Node 用包解析处理裸说明符，并推荐用 node: 前缀明确表示内置模块。

Node 24 的格式边界

在 Node 24 中，.mjs 始终是 ESM，.cjs 始终是 CommonJS。.js 的格式主要由最近父级 package.json 的 type 决定："module" 表示 ESM，"commonjs" 或缺省通常表示 CommonJS。应在每个包中显式写出 type，避免工具升级或嵌套包边界改变解释方式。

CommonJS 使用 require() 和 module.exports。exports 初始只是 module.exports 的别名，因此 exports.format = format 有效，而 exports = { format } 只改了局部变量，不会替换实际导出。ESM 与 CommonJS 互操作时，命名导出的推断和默认导出包装取决于方向与具体模块形状，不应只凭语法外观猜测。

Node 24 的 require() 可以同步加载满足条件的 ESM，但目标图不能包含顶层 await；否则同步调用无法完成。CommonJS 使用动态 import() 是更一致的异步边界。迁移代码时应验证真实入口、Node 版本和返回形状，而不是沿用「所有 ESM 都不能 require」或「两者完全互换」这样的旧口诀。

package.json 的 exports 定义包使用者可访问的入口，并在存在时优先于 main。条件对象可以为 import、require、node 或 default 选择不同目标，条件顺序从具体到通用更安全。同一包若让两条路径加载彼此独立的实现，可能产生两份状态，这就是需要测试对象标识和副作用次数的双包风险。

示例

四个示例都使用 data: 模块，让单个文件能在 Node 24 和支持 ESM 的浏览器中独立运行。生产代码通常导入实际 URL 或包名；这里内联源码只为让每个示例可复制、可执行，并准确展示模块语义。

读取命名导出与默认导出

模块命名空间同时包含 default、total 和 vatRate。命名空间键按字符串顺序排列，因此输出可以稳定展示完整导出形状。

Object.keys() 看到 default，因为默认导出并不是命名空间对象以外的第二条通道。真实文件中的静态写法可以是 import catalogName, { total } from "./catalog.js"；catalogName 是本地选择的名称，total 则必须匹配导出名称。

导出对象仍可能被调用方修改内部属性。「导入绑定只读」只禁止把导入名称重新指向另一个值，不会冻结该名称指向的数组或对象。需要不可变契约时，模块 API 必须另行控制暴露的引用和更新操作。

区分实时属性与解构快照

stock.available 通过命名空间读取实时导出。解构创建的局部 available 只是数字 2，因此调用 reserve() 后保持不变。

const stockSource = `
export let available = 2;
export function reserve() {
  available -= 1;
}
`;

const stockUrl = `data:text/javascript,${encodeURIComponent(stockSource)}`;
const stock = await import(stockUrl);
const { available } = stock;

console.log(stock.available, available);
stock.reserve();
console.log(stock.available, available);

2 2
1 2

若改用静态 import { available } from "./stock.js"，available 本身就是实时绑定，会在第二次读取时得到 1。这一区别经常出现在把静态导入重构为 await import() 的代码中：直接解构看起来相似，却可能把本应实时的值冻结为当时的引用。

实时绑定传播的是重新绑定结果，不是深层变更通知。若导出的是一个对象，导入方一直持有同一对象时自然能看到属性修改；这来自共享对象标识，而不是模块系统观察了每个属性。

用允许列表约束动态导入

语言键先在固定表中解析成受信任 URL。未知键在触发模块解析前就被拒绝，调用方因此能区分不支持的语言与模块本身求值失败。

const localeSources = {
  en: `export default { checkout: "Checkout" };`,
  zh: `export default { checkout: "结算" };`,
};

const localeUrls = Object.fromEntries(
  Object.entries(localeSources).map(([key, source]) => [
    key,
    `data:text/javascript,${encodeURIComponent(source)}`,
  ]),
);

async function loadLocale(language) {
  const url = localeUrls[language];
  if (!url) throw new RangeError(`Unsupported locale: ${language}`);
  return (await import(url)).default;
}

console.log((await loadLocale("en")).checkout);
console.log((await loadLocale("zh")).checkout);

try {
  await loadLocale("ja");
} catch (error) {
  console.log(`${error.name}: ${error.message}`);
}

Checkout
结算
RangeError: Unsupported locale: ja

把请求参数直接拼入 import() 会把模块选择权交给外部输入，也让打包工具难以确定要包含哪些文件。允许列表把公开键、实际说明符和授权策略放在同一处。若列表很大，可由构建步骤生成，但运行时仍应只查表，不应接受任意路径片段。

这里的 catch 只包围预期失败的调用。业务代码还应决定模块下载失败、语法错误和初始化异常是否可以回退；不加区分地返回空对象会把部署错误伪装成「语言不存在」。

观察模块标识与缓存

同一 data: URL 的两次导入共享一个模块实例，顶层日志只出现一次。添加片段后形成不同标识，模块再次求值，并产生不同的 marker 对象。

const moduleSource = `
console.log("module evaluated");
export const marker = {};
`;

const moduleUrl = `data:text/javascript,${encodeURIComponent(moduleSource)}`;
const first = await import(moduleUrl);
const second = await import(moduleUrl);
const distinct = await import(`${moduleUrl}#copy`);

console.log(`same URL: ${first.marker === second.marker}`);
console.log(`different URL: ${first.marker === distinct.marker}`);

module evaluated
module evaluated
same URL: true
different URL: false

不要把查询参数或片段当成通用的「重载模块」API。不同宿主和工具可能对说明符做额外转换，而且每个新标识都可能保留一份状态。开发服务器的热更新有自己的生命周期协议，应用代码不应通过随机缓存破坏符来模拟它。

测试共享实例时，优先观察公开行为，例如初始化调用次数或返回对象标识。测试隔离需求则应把状态放进工厂函数，每次测试显式创建实例，而不是尝试清除 ESM 的内部缓存。

陷阱

把打包工具规则当成宿主规则

猜错默认导出和命名导出

把动态说明符交给外部输入

在循环依赖中读取未初始化绑定

忽略模块级状态的所有者

错配 Node 文件格式

延伸阅读

• MDN：JavaScript 模块指南
• MDN：静态 import 声明
• MDN：动态 import() 运算符
• Node.js 24：ECMAScript 模块
• Node.js 24：包与模块类型