Node 模块加载与 ESM 边界,从 require 到 import 的深层差异
CommonJS 与 ESM 的差异常被简化成"语法不同",但真实的差异在模块加载机制深处:解析时机、循环依赖行为、顶层 await、JSON/WASM 导入、包导出映射。理解这些机制差异,才能解释"为什么这段代码在 CJS 能跑、ESM 报错"与"为什么动态 import 能救场"。本文按加载机制逐层拆解,给出混合工程的迁移判断。
一、加载机制的四点核心差异
| 维度 | CommonJS | ESM |
|---|---|---|
| 解析时机 | 运行时(require 到哪解析到哪) | 解析期静态分析(import 必须在顶层、可静态提取依赖图) |
| 绑定方式 | 值拷贝(module.exports 的快照) | 活绑定(live binding:导出方更新,导入方可见) |
| 循环依赖 | 部分初始化,拿到未完成的 exports | 同样支持但有 TDZ 风险(const 提升前访问报错) |
| 顶层 await | 不支持 | 支持(模块成为异步加载单元) |
// 活绑定示例:CJS 拿到的是值快照,ESM 拿到的是"引用"
// counter.cjs
let count = 0;
setTimeout(() => { count = 42; }, 100);
module.exports = { count };
// main.cjs
const { count } = require("./counter.cjs");
setTimeout(() => console.log(count), 200); // 0 —— 值拷贝,看不到更新
// counter.mjs
export let count = 0;
setTimeout(() => { count = 42; }, 100);
// main.mjs
import { count } from "./counter.mjs";
setTimeout(() => console.log(count), 200); // 42 —— 活绑定
活绑定解释了大量"迁移后行为不一致"的谜团:任何依赖"导出值快照"的代码(缓存模式、配置快照)在 ESM 下会变成"跟随更新"——有时是修好了 bug,有时是引入了新 bug。
二、包导出映射:package.json 的 exports 是新版契约
现代包治理的核心在 exports 字段——它同时定义入口、子路径与条件导入:
{
"name": "my-lib",
"type": "module",
"main": "./dist/index.cjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"default": "./dist/index.mjs"
},
"./utils": {
"types": "./dist/utils.d.ts",
"import": "./dist/utils.mjs"
},
"./package.json": "./package.json"
}
}
三条治理含义:
- exports 之外不可导入:没在 exports 里列出的子路径(
my-lib/internal/xxx)在 ESM 解析下直接报错——这是"把内部实现锁起来"的机制,比老式"约定不进"强得多; - 条件导出顺序敏感:types → import → require → default,TypeScript 与打包器按顺序匹配第一个命中条件;default 放最后兜底;
- 双格式包的分发:同一逻辑编译出 .mjs 与 .cjs,由条件导出分发——迁移期包的标准形态,但两份产物要保持行为一致(测试矩阵双跑)。
三、动态导入:唯一的"运行时加载"出口
ESM 的静态性换来了 tree-shaking 与确定性依赖图,但也失去了运行时按需加载——import() 动态导入补回这个口子:
// 按需加载重型依赖(按需初始化,冷启动加速)
let sharp = null;
async function ensureSharp() {
if (!sharp) sharp = (await import("sharp")).default;
return sharp;
}
// 条件分支加载平台特定实现
const storage = process.env.STORAGE === "s3"
? await import("./storage/s3.js")
: await import("./storage/local.js");
// 动态路径拼接(谨慎:会破坏打包器静态分析,需排除规则)
const plugin = await import(`./plugins/${name}.js`);
动态导入的三个纪律:失败要兜底(import() 返回 promise,网络/解析失败会 reject,try-catch 包住);路径拼接破坏静态分析(webpack/esbuild 需要显式声明 chunk 范围);热路径预加载(首次调用带加载延迟,服务启动时预热重型模块)。
四、迁移判断:哪些工程该留在 CJS
迁移不是单行道,按工程特征做判断:
| 工程特征 | 建议 | 理由 |
|---|---|---|
| 新项目、现代工具链(Vite/esbuild) | 直接 ESM | 生态默认方向,顶层 await/活绑定受益 |
| 服务端 + 大量 CommonJS 老依赖 | 混合模式(type: module + cjs 互操作) | ESM 可以 import CJS;反向 require(ESM) 长期受限 |
| CLI 工具依赖动态 require 插件体系 | 谨慎迁移 | 插件加载的动态路径在 ESM 下要重构为 import() |
| 老大型单体,迁移收益低 | 留 CJS,等待依赖生态齐备 | 迁移成本 > 收益时不折腾 |
混合模式的关键规则:ESM 侧 import CJS 是一等公民(default 导出为 module.exports),反向 require ESM 只能 await import()——所以入口文件选型时,"谁引谁"决定谁该是 ESM。
五、坑与边界
| 坑 | 现象 | 应对 |
|---|---|---|
| __dirname/__filename 消失 | ESM 里未定义 | import.meta.dirname(Node 21+)/ fileURLToPath(import.meta.url) |
| require 突然不存在 | ESM 无 require | await import();或 .cjs 后缀单文件保留 CJS |
| 循环依赖 TDZ | ReferenceError: Cannot access before init | 重构提取共享模块;或延迟函数调用而非顶层执行 |
| exports 未列子路径 | ERR_PACKAGE_PATH_NOT_EXPORTED | 补 exports 映射或用 ./ 子路径声明 |
| JSON 导入失败 | ESM 需 with { type: "json" } | import data from "./x.json" with { type: "json" } |
| 双格式包行为不一致 | ESM/CJS 产物输出不同 | 双产物测试矩阵;活绑定语义差异重点核对 |
第二坑是迁移期的头号雷区:循环依赖在 CJS 静默通过、在 ESM 变 TDZ 崩溃——因为静态分析按依赖图顶层先执行。修复顺序:先重构(共享逻辑抽第三方模块),实在不能动的用函数内延迟引用(调用时才访问,绕开顶层 TDZ 窗口)。
小结
CJS 与 ESM 的深层差异在机制:静态解析 vs 运行时解析、活绑定 vs 值拷贝、顶层 await 与 TDZ 循环依赖行为。 exports 映射是现代包的访问契约(未列出即不可导入),动态 import() 是唯一运行时加载出口(纪律:兜底、预热、慎拼路径)。迁移按工程特征判断:新工程 ESM、混合模式"ESM 引 CJS"为顺方向、重动态插件体系谨慎。迁移期的最大雷区是循环依赖从静默变崩溃——先重构再迁移。
评论(0)
登录 后参与评论。