🔍 登录 注册

Node 模块加载与 ESM 边界,从 require 到 import 的深层差异

云 云边小卖部 2026-11-21 👁 0 ⏱ 6min

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"
  }
}

三条治理含义:

  1. exports 之外不可导入:没在 exports 里列出的子路径(my-lib/internal/xxx)在 ESM 解析下直接报错——这是"把内部实现锁起来"的机制,比老式"约定不进"强得多;
  2. 条件导出顺序敏感:types → import → require → default,TypeScript 与打包器按顺序匹配第一个命中条件;default 放最后兜底;
  3. 双格式包的分发:同一逻辑编译出 .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"为顺方向、重动态插件体系谨慎。迁移期的最大雷区是循环依赖从静默变崩溃——先重构再迁移。

读完了?给作者一点支持

本文采用 CC BY 4.0 协议转载 · © 云边小卖部

评论(0)

登录 后参与评论。

  • 还没有评论,来抢沙发。

🔗 相关文章

审计人的职业规划地图:事务所、企业内审、监管与自由执业的四条路线

"做了三年审计接下来去哪"是行业论坛上的永恒问题。2026 年的就业市场给出了新的答案坐标:AI 压缩了基础核算与核对类岗位,同时抬高了风险判断、内控体系、数据审计类岗位的身价。本文把审计人的出路整理成四条主路线——事务所纵深、企业内审/风控、监管与准则机构、自由执业/专家证人——每条给进入条件、典型轨迹、5 年收入区间感与适配画像,帮你做一次结构化的自我定位。

4 天前👍 1

MySQL 9.x VECTOR 类型实战,向量检索的原生时代

MySQL 9.x Innovation 线(当前最新 9.7.4,2026-10-20 发布,release notes 里 9.7.4.1 已列为待发布状态)引入了 VECTOR 原生类型,把"向量检索"从外挂方案(应用层算相似度)变成了 SQL 原生能力。本文讲清 VECTOR 类型的语法、距离函数、与 MySQL 生态(HeatWave/应用层)的配合方式,以及它与专业向量库的选型边界。

6 小时前👍 1

Spring Cloud 2026.0.0-RC2 Paddington 发布:版本列车迁移指南

2026 年 11 月 5 日,Spring 官方宣布 Spring Cloud 2026.0.0-RC2(代号 Paddington)发布——这是继 2025.1.x(Oakwood)之后的下一个版本列车,对应 Spring Boot 4.2.x 世代。对还在 Oakwood 上的团队,这是规划迁移的最佳窗口。本文基于官方项目页与博客的权威信息(2026-11-19 抓取),给出版本列车的现状、迁移核对清单与回滚预案。

2 天前👍 1