CJS与ESM混用完全指南：从原理到实践，彻底搞懂Node.js模块系统

早几年我还在用 RequireJS 和 SeaJS 折腾异步模块加载的时候，真没想到前端模块化能走到今天这一步。现在打开任意一个 Node.js 项目，require 和 import 混着写是常态；跑到 Vite 或 Next.js 里，纯 ESM 又成了默认。但正因为这套体系演进得太快，很多人对 CJS 和 ESM 的理解停留在“一个用 require、一个用 import”的层面，结果一遇到混用就各种报错。

我见过不少团队在迁移到 ESM 时被 ERR_REQUIRE_ESM 卡住，也见过有人因为循环依赖导致初始化顺序错乱，排查到深夜。这篇文章我不打算做枯燥的规格复述，而是想从一个实际写过大量 Node 服务和前端项目的角度，把 CJS 与 ESM 的区别、混用方式、底层原因和踩坑经验一次性讲透。无论你是在维护老项目，还是在从零搭建新工程，这篇应该都能帮你省下不少查文档的时间。

1. 为什么前端会有两套模块体系：一段历史演进与现状

要说清楚 CJS 和 ESM 的区别，先得知道它们是怎么来的。这不是考古，而是理解很多“诡异行为”的基础。

1.1 CJS 的诞生：一场“被迫”的浏览器侧改革

Node.js 在 2009 年刚出来的时候，JavaScript 语言本身还没有模块概念。浏览器里想复用代码，要么靠全局变量，要么靠 IIFE（立即执行函数）包裹。后果就是命名冲突、依赖顺序难维护，一个稍微大点的项目，光 script 标签的排列顺序就能让人崩溃。

CommonJS 规范就是在这种情况下出现的。它用 require 同步加载模块，用 module.exports 导出内容。这在服务器端没问题，因为 Node 读取的是本地磁盘文件，同步读取的速度可以接受。但浏览器端不行——同步加载意味着页面要卡住等文件下载完，这在网络环境下是不能接受的，所以浏览器端后来走了 AMD/CMD 那条异步路线。

CJS 的关键特性有三个，后面很多坑都源于它们：

• 运行时加载：require 是在代码执行到那一行时才去加载模块，所以它可以在 if 语句里、函数里、甚至任意条件分支里调用。
• 拷贝导出：module.exports 导出的值，在模块加载完成后就已经确定了。如果导出一个对象，外部拿到的是对象引用的拷贝（严格来说是浅拷贝的引用关系），后续模块内部再修改这个对象，外部其实能看到变化；但如果模块内部把整个 module.exports 重新赋值了，外部拿到旧引用就不变了。
• 同步执行：加载到一个模块，会同步执行它的所有代码，然后才返回 exports。

1.2 ESM 的出现：语言层面的正统解决方案

ES6 在 2015 年正式推出了 import / export 语法，这才是 JavaScript 语言自带的模块系统。和 CJS 相比，它有几个本质性的改变：

• 静态解析：import 语句必须写在模块顶层，不能在 if 或函数里写。这样做的好处是引擎在代码执行前就能分析出完整的依赖关系树，可以做 tree-shaking、按需加载等优化。
• 实时绑定：ESM 导出的是活引用（live binding）。模块内部修改变量，外部导入的地方能看到最新值。
• 异步加载：ESM 的设计考虑到了浏览器环境，模块加载是异步的，可以配合 import() 动态加载。

这两套体系在语法和加载机制上的差异，导致了它们在很多场景下的行为完全不一样。举个最简单的例子：

javascript复制// CJS 中，require 可以写在这里
if (someCondition) {
  const fs = require('fs');
}

// ESM 中，import 必须提升到顶层
if (someCondition) {
  import fs from 'fs'; // 语法错误
}

这不是语法限制这么简单，而是设计哲学的根本不同。CJS 是“执行到哪就加载到哪”，ESM 是“先看清楚依赖关系，再做加载决策”。

1.3 当下的格局：双模块共存的中间态

到 2025 年了，Node.js 已经支持 ESM 很多年，浏览器原生支持也非常完善，按理说应该全面切换到 ESM 了。但现实是，npm 上几十万个包仍然是 CJS 格式，很多维护良好的老项目不可能一夜之间重写。所以我们现在处于一个“双模块共存”的过渡期。

这个过渡期带来了一个很实际的问题：Node.js 和打包器需要同时支持两种模块系统，并且要处理它们之间的互操作。于是就有了 .mjs、.cjs 这些扩展名，有了 package.json 里的 type: "module" 字段，有了 exports 字段的条件导出。理解这些规则，是在现代前端工程里混用两种模块的基础。

2. CJS 与 ESM 的核心差异：不是语法不同那么简单

很多人以为 CJS 和 ESM 的区别就是 require vs import，其实语法只是表象，底层的加载机制、作用域、this 指向都有很大不同。我把它们系统的拆一下。

2.1 加载时机：运行时解析 vs 静态解析

CJS 是同步加载，模块在 require 被调用时才执行。这意味着：

javascript复制// 文件 a.cjs
console.log('a 开始加载');
const b = require('./b.cjs');
console.log('a 加载完成');

// 文件 b.cjs
console.log('b 被加载了');
module.exports = { name: 'b' };

执行 node a.cjs 的输出顺序是：

code复制a 开始加载
b 被加载了
a 加载完成

而 ESM 不同，import 语句会被提升到模块顶部。即使你把 import 写在文件中间，它也会在模块其他代码执行之前先完成依赖加载：

javascript复制// 文件 a.mjs
console.log('a 开始执行');
import { name } from './b.mjs';
console.log('a 执行完成，name =', name);

// 文件 b.mjs
console.log('b 模块被执行了');
export const name = 'b';

注意，上面这段代码在 ESM 中是合法的，import 会被自动提升。输出顺序是：

code复制b 模块被执行了
a 开始执行
a 执行完成，name = b

这种差异直接影响了模块的初始化顺序。如果你有一个模块初始化时依赖另一个模块的副作用（比如往全局对象上挂东西），在 CJS 和 ESM 下的表现可能就不一样。

2.2 导出绑定：值的拷贝 vs 活引用

这一节是最容易让人困惑的，我实际验证了很多遍才完全确定。

CJS 的 module.exports 本质上是把一个对象赋值给模块的导出。当外部模块 require 它时，拿到的是这个对象。但如果模块内部在导出之后重新赋值 module.exports = { name: 'new' }，外部已经拿到旧引用了，不会自动同步。

ESM 则不一样，export 导出的是标识符的活引用。看这个例子：

javascript复制// counter.mjs
export let count = 0;
export function increment() {
  count++;
}

// main.mjs
import { count, increment } from './counter.mjs';
console.log(count); // 0
increment();
console.log(count); // 1

在 CJS 中，如果这么写：

javascript复制// counter.cjs
let count = 0;
function increment() {
  count++;
}
module.exports = { count, increment };

// main.cjs
const { count, increment } = require('./counter.cjs');
console.log(count); // 0
increment();
console.log(count); // 0 —— 不会变！

因为 count 在 module.exports 时已经被拷贝了一个值进去了，increment 改的是模块内部的局部变量 count，外部拿到的还是旧值。但如果你通过 module.exports.count 引用的方式就能实现类似活引用的效果。

这也是为什么很多老 Node 代码会写 module.exports = { get count() { return count; } } 来做“动态导出”。ESM 把这个需求变成了语言层面的默认行为。

2.3 顶层 this：空对象 vs undefined

在 CJS 里，每个文件是一个模块，模块顶层的 this 指向 exports 对象：

javascript复制// a.cjs
console.log(this); // {}
console.log(this === module.exports); // true

但在 ESM 中，顶层 this 是 undefined：

javascript复制// a.mjs
console.log(this); // undefined

这个差异在写通用代码时不注意就会踩坑。比如有些库会根据 typeof window !== 'undefined' 判断环境，这类代码在两个体系下倒是没问题；但如果写了 if (this) 来判断模块环境，ESM 下就会走到另一个分支。

2.4 严格模式：CJS 不强制，ESM 默认开启

ESM 模块默认是严格模式，这意味着你不能在 ESM 里使用 with、不能给未声明变量赋值、arguments 的行为也更严格。CJS 默认不是严格模式，除非你手写 "use strict"。

这个差异在实际开发中不太容易触发，但一旦触发了就很诡异，比如遗忘声明变量赋值在严格模式下直接抛错，非严格模式下只是给全局对象挂属性。

2.5 动态加载：require 天然动态，ESM 靠 import()

CJS 的 require 本身就是动态的，可以写在任何地方，还可以用变量拼接路径：

javascript复制const moduleName = './' + someVariable;
const mod = require(moduleName);

ESM 的静态 import 做不到这一点，但可以用 import() 动态导入：

javascript复制const moduleName = './' + someVariable;
const mod = await import(moduleName);

import() 返回的是 Promise，所以可以 await。这在做代码分割、按需加载时非常有用。不过要注意，在 ESM 中 import() 加载的是 ESM 模块时，能拿到命名导出；加载 CJS 模块时，拿到的 module.exports 作为默认导出。

2.6 顶层级 await

ESM 支持顶级 await，也就是你可以在模块顶层直接写 await，不需要包在 async 函数里：

javascript复制// config.mjs
const data = await fetch('/api/config').then(r => r.json());
export default data;

这在 CJS 里是不可能的，因为 CJS 模块是同步加载的，如果允许顶层 await，会打破同步执行的假设。这也是很多工具库在 ESM 下能做得更简洁的原因之一。

3. 混用的真实场景：Node、打包器与同构项目

理解了核心差异，再来看实际工程中怎么混用。这一部分，我会结合 Node.js 原生支持和前端打包器的行为来展开。

3.1 在 Node.js 中正确混用 CJS 和 ESM

现代 Node.js（12+）已经比较稳定地支持两种模块体系。关键规则是：

• 扩展名为 .cjs 的文件，永远按 CJS 解析。
• 扩展名为 .mjs 的文件，永远按 ESM 解析。
• 扩展名为 .js 的文件，取决于 package.json 中的 type 字段："type": "module" 按 ESM，没有该字段或 "type": "commonjs" 按 CJS。

这个规则简单直接，但实际工程中会有几个容易忽略的点。

第一个是“ESM 文件里怎么加载 CJS 模块”。答案是可以，而且很简单：

javascript复制// main.mjs
import fs from 'fs'; // fs 是 CJS 模块，但可以用默认导入
import { readFile } from 'fs'; // 有些情况下也支持命名导入

import { Component } from './legacy-cjs.cjs'; // 这是自定义 CJS 模块

Node.js 的 ESM 加载 CJS 模块时，会将 module.exports 整体作为默认导出，同时尝试做命名导出的“静态分析”。如果 CJS 模块是用 module.exports = { a: 1, b: 2 } 这种字面量方式写的，Node 的 cjs-module-lexer 能解析出 a 和 b，从而让你用命名导入。但如果是动态导出的，命名导入可能拿到 undefined 或者直接报错。

第二个是“CJS 文件里怎么加载 ESM 模块”。CJS 不能用 require 去加载 ESM，因为 ESM 是异步的，而 require 是同步的。Node 会直接抛错：ERR_REQUIRE_ESM。

解决方法是用动态 import()：

javascript复制// main.cjs
async function loadEsm() {
  const mod = await import('./esm-module.mjs');
  console.log(mod.default);
}

loadEsm();

这是官方推荐的方式。注意 import() 在 CJS 中也是可用的，返回一个 Promise。你可以在顶层调用，但要等 Promise resolve 后获取模块。

第三个是“同包双格式导出”。如果你在维护一个 npm 包，想同时支持 CJS 和 ESM 的使用者，最优雅的方式是在 package.json 的 exports 字段做条件导出：

json复制{
  "name": "my-lib",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

这样，ESM 使用者 import myLib 时拿 index.mjs，CJS 使用者 require('myLib') 时拿 index.cjs。

3.2 在打包器（Vite / Webpack）中混用

前端打包器对模块混用的容忍度比 Node.js 高得多，但它们也有自己的规则和坑。

Webpack 是老牌打包器，对 CJS 和 ESM 都有很好的支持。Webpack 内部会把 ESM 转换成自己的运行时模块系统，所以你在源码里可以放心混写。但需要注意：

• 在 webpack.config.js 里（它本身是 Node 环境），你依然要用 CJS 语法（除非配置了 babel 或把配置文件改成 .mjs）。
• 库开发场景下，Webpack 的 output.library.type 可以设置为 'module' 或 'commonjs2'，决定产物的模块格式。

javascript复制// webpack.config.cjs
module.exports = {
  output: {
    library: {
      type: 'module',
    },
  },
  experiments: {
    outputModule: true,
  },
};

Vite 是另一个热门选择。它开发时用原生 ESM，构建时用 Rollup 打包。Vite 对 CJS 的解析依赖 @rollup/plugin-commonjs，会自动把 CJS 模块转换成 ESM 可用的形式。但转换过程有一些边界情况，尤其是依赖里用了动态 require 或 module.exports 重新赋值时，转换可能不准确。

在实际 Vite 项目中，你会发现很多插件或依赖需要在 optimizeDeps 配置里显式 include 或 exclude，这本质上就是为了处理 CJS/ESM 互操作。

javascript复制// vite.config.js
export default {
  optimizeDeps: {
    include: ['some-cjs-lib'],
    exclude: ['some-esm-only-lib'],
  },
};

3.3 同构项目（Node + 浏览器共用代码）的混用策略

同构项目（比如 Next.js、Nuxt、或者自己搭的 SSR 框架）里，一套代码既要跑在 Node 服务端，也要跑在浏览器里。这种场景下，模块格式的选择可以直接影响到了运行行为。

我个人推荐在新项目里全部用 ESM 写源码，然后让打包器处理转换。理由很简单：

• ESM 支持 tree-shaking，生产构建产物更小。
• 顶层 await 和动态 import() 让代码表达力更强。
• 未来的趋势就是 ESM，维护成本会更低。

但要注意，服务端代码如果依赖某些 CJS-only 的包，在 Node 环境直接使用这些包时，就回到了 3.1 节的情况。这时候推荐在服务端入口文件用 ESM，对 CJS 依赖通过默认导入方式引入：

javascript复制// server/index.mjs
import express from 'express'; // express 是 CJS 包，但可以默认导入

4. 混用中最容易踩的坑：我的排错实录

理论说再多，不如真实踩坑来的深刻。这一节我梳理了平时工作中遇到最多的问题，每一个都是可复现、可排查的。

4.1 ERR_REQUIRE_ESM：CJS 里 require 一个 ESM 模块

这个报错是混用场景下最常见的。表现形式是：

code复制Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/xxx.mjs not supported.

根因很简单：Node 不允许同步 require 异步 ESM。但很多人困惑的是“为什么之前还好好的，今天突然报错”？因为 npm 包升级了。很多包在某个版本切换到了纯 ESM，你的老代码用 require 去加载它就炸了。

排查思路：

1. 看报错信息里的文件路径，确认它是什么格式（.mjs 还是 package.json 中 type: "module" 的 .js）。
2. 如果是第三方包，去它的 package.json 看 exports 字段，确认是否有 require 条件。
3. 临时解决方案：把你的调用方式改成动态 import()，但要注意包本身的 API 是否适合异步加载。
4. 正规解决方案：让自己的项目也迁移到 ESM，或者用 bundler 打包这个依赖。

4.2 默认导出与命名导出的错配

这是另一个高频坑。很多包在 ESM 里提供了命名导出 { default, named }，但你在 CJS 里用 require 得到的结构可能是：

javascript复制const mod = require('some-package');
// 在 CJS 中，mod 可能长这样：
// { default: { trueExport: '...' }, named: '...' }
// 而不是你以为的 { trueExport: '...' }

如果你看到一个包在文档里说用 import pkg from 'some-package'，但你用 require 后发现 pkg.xxx 是 undefined，大概率是导出结构里多了一层 default。

排查思路：

javascript复制// 在 CJS 下先打印一下拿到的东西结构
const mod = require('some-package');
console.log(Object.keys(mod)); // 如果看到 'default'，就是这种问题

解决办法：有的包会在 CJS 构建时做兼容处理（避免 default 嵌套），但很多新包不会。最稳妥的方案是：如果你的项目是 CJS，尽量选支持 CJS 的版本或包；如果你的包是纯 ESM，使用者要是 CJS 环境，就该用 import() 动态导入。

4.3 循环依赖下的初始化顺序差异

循环依赖在大型项目里很难完全避免。CJS 因为同步执行，遇到循环依赖时，会直接返回当前模块 module.exports 的不完整状态；ESM 因为有实时绑定，理论上循环依赖也可以工作，但如果访问过早，依然会拿到 undefined。

举个 CJS 的例子：

javascript复制// a.cjs
const b = require('./b.cjs');
console.log('a 中打印 b.name:', b.name);
module.exports = { name: 'a' };

// b.cjs
const a = require('./a.cjs');
console.log('b 中打印 a.name:', a.name); // undefined
module.exports = { name: 'b' };

输出：

code复制b 中打印 a.name: undefined
a 中打印 b.name: b

因为 b.cjs 在加载时，a.cjs 的 module.exports 还没赋值完成，是一个空对象。

在 ESM 中：

javascript复制// a.mjs
import { name as bName } from './b.mjs';
console.log('a 中打印 b.name:', bName);
export const name = 'a';

// b.mjs
import { name as aName } from './a.mjs';
console.log('b 中打印 a.name:', aName); // 如果此时 a 还未初始化 name
export const name = 'b';

因为 ESM 的 live binding，aName 在 b.mjs 执行的时候还没赋值，所以同样可能打印 undefined（取决于模块执行顺序）。这跟 CJS 的行为看起来挺像，但机制不同——ESM 中等到 a.mjs 执行完，b.mjs 里拿到的 aName 会更新为 'a'；但在 b.mjs 顶层访问的话，时机还是太快了。

避坑建议：尽可能避免在模块顶层读取其他模块的导出值。如果确实需要，把读取操作放在函数/方法里延迟执行，而不是在模块作用域顶楼获取。

4.4 打包器对 CJS 的“猜”与“错”

Webpack 和 Rollup 在处理 CJS 模块时，通常会用静态分析猜测命名导出。比如：

javascript复制module.exports = {
  foo: 'foo',
  bar: 'bar',
};

打包器能识别出 foo 和 bar 命名导出。但如果改成：

javascript复制const obj = { foo: 'foo', bar: 'bar' };
module.exports = obj;

或：

javascript复制module.exports = {};
module.exports.foo = 'foo';

打包器可能就只能看到默认导出，导致你在 ESM 里写 import { foo } from 'legacy-lib' 时拿到 undefined 或报错。

排查思路：

• 打印一下打包后模块的导出结构。
• 在 Vite 里如果遇到这类依赖，可以在 optimizeDeps.include 里加上它，让 Vite 的依赖预构建去尝试兼容。
• 在 Webpack 里可以配置 resolve.mainFields，尝试不同入口。

4.5 JSON 模块导入差异

JSON 文件的导入在两种体系下也有区别。

• CJS：const data = require('./data.json') 直接得到一个对象。
• ESM：import data from './data.json' 是默认导出，如果要用命名导入（import { key } from './data.json'），需要 Node 开启 --experimental-json-modules（较老版本）或依赖打包器处理。

实际工程中，我大多通过打包器或把 JSON 改成 JS/TS 模块来规避这个坑，因为 JSON 模块如果体积大，打包器会把它内联到 JS 里，影响性能。更合理的做法是保留 JSON 文件，运行时通过 fs 读取（Node 环境）或 fetch（浏览器环境）。

4.6 测试框架和配置文件的模块格式冲突

Jest、Vitest、Mocha 这些测试框架，对 CJS/ESM 的支持程度各不相同。Jest 默认在 Node 环境里用 CJS 风格，但如果你在 jest.config.js 里写 ESM 语法，就会报错；Vitest 则是默认支持 ESM。

我自己遇到过的情况是：项目源码用了 "type": "module"，但测试配置文件还是 .js 扩展名，导致框架去加载配置时用 ESM 解析，结果配置里全是 module.exports 语法，直接报错。

解决办法：

• 把配置文件改成 .cjs 扩展名，强制按 CJS 解析。
• 或者把配置文件改成 .mjs，并改用 ESM 语法。
• 在 Jest 中，也可以在 package.json 里单独给 jest 配置段设置 testEnvironment 等参数，同时确认 transform 是否符合预期。

提示：配置文件命名规范本身就是模块解析规则的延伸。.cjs 和 .mjs 不是装饰，是模块格式的“声明”。

4.7 包发布后的“双格式”陷阱

如果你在维护一个 npm 包，想同时支持 CJS 和 ESM 使用者，最容易犯的错误是“包内一个模块文件里混写了 CJS 和 ESM 语法”。注意，这是绝对不允许的：

javascript复制// 这样会直接挂
const path = require('path');
import fs from 'fs';

一个文件要么是 CJS 要么是 ESM，不能混写。要提供双格式支持，必须生成两份构建产物（index.cjs 和 index.mjs），然后用 exports 条件导出分发。

同时要注意，如果你的包是纯 ESM，而使用者坚持用 CJS require，那么即使你配置了 exports 字段，如果他们用的 Node 版本不支持条件导出，也可能出问题。建议包发布前明确声明 "type": "module" 或 "type": "commonjs"，并且在 README 里写明支持范围。

5. 怎么选、怎么迁移：实操建议与我的经验

文章最后这一部分，给不同状态的项目的落地建议，也算是我自己处理多个项目迭代后的心得。

5.1 新项目：直接全 ESM，但注意边界

如果你从零开始一个新项目，别犹豫，直接用 ESM。Node.js 生态已经足够成熟，主流框架、工具链都优先支持 ESM。但有些边界需要提前确认：

• 你依赖的老牌 npm 包是否还是 CJS-only？如果是，确认是否支持动态导入兼容。
• 你是否需要构建一个给浏览器用的库？如果是，输出格式要在 package.json 里配好 exports。
• 你的部署环境用的 Node 版本是多少？16 以下的话，ESM 支持不够完善，建议升到 18 LTS 或更高。

我写过很多次 "type": "module" 后遇到的第一个问题：有些 CLI 工具（比如某些 eslint 插件、jest 配置等）默认读取 CJS 格式，这时需要做适配。记住：一切以扩展名和 exports 字段为准，配置文件报错了就改扩展名，千万不要在源码里混写。

5.2 老项目：渐进式迁移方案

老项目直接全量迁移 ESM 风险很大，我建议按下面这个顺序渐进式来：

1. 先确保项目里的构建工具链（webpack/vite/rollup）升级到支持 ESM 的稳定版本。
2. 把业务代码中新增的模块直接写成 ESM 语法，让打包器把它转换掉。
3. 确认所有第三方依赖的引入方式在两种模块下都正常工作。
4. 逐步将工具链配置（比如 webpack.config.js）也迁移到 ESM。
5. 最后再改 package.json 的 type 字段（这一步影响面最大，一定要放到最后）。

这里的核心逻辑是：不要一次性切换，而要让工具链和代码一层层适应。如果中途遇到 ERR_REQUIRE_ESM 这类报错，优先看是不是某个依赖升级导致的，而不是盲目回滚。

5.3 库作者：双格式发布的最佳实践

如果你开发的库要发布到 npm，我非常推荐做双格式发布。具体的 package.json 结构可以这样：

json复制{
  "name": "my-awesome-lib",
  "type": "module",
  "main": "./dist/index.cjs",
  "module": "./dist/index.mjs",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

这里有几点值得注意：

• main 字段是给老版本 Node 用的，优先级最低。
• module 字段是给打包器用的，很多打包器会优先读这个字段，因为它能更好地支持 tree-shaking。
• exports 字段是更现代和严格的分发方式，Node 和打包器都支持。配置了它之后，main/module 字段基本就不参与解析了。
• types 要放在 exports 里，因为 TypeScript 也需要条件解析类型。

写构建脚本时，可以分别用 Rollup 或 esbuild 生成 CJS 和 ESM 两套产物。注意 CJS 产物不要带 import 语法，ESM 产物不要带 require（除了动态 import）。我之前见过一个包，构建出的 ESM 产物里还残留 require('xxx')，结果 Node 直接报错。

5.4 识别“.cjs / .mjs 命名混乱”问题

团队协作时，很容易出现“一个人把文件命名为 .cjs，另一个人又改成 `.mjs”的情况。这种混乱会导致运行时报错。

我的建议是建立一份简单的团队约定：

• 凡是工具链、配置文件（webpack、jest、eslint 等），统一用 .cjs 或 .js（如果 type 是 commonjs）。
• 凡是业务源码，统一走 ESM（.js + "type": "module"）。
• 凡是需要同时被 Node 和浏览器引用的模块，用 .mjs 确保语义清晰。

这一条在代码审查时加入规则，能避免很多肉眼不易发现的问题。

5.5 动态 import 的使用时机

最后说说动态 import() 的使用时机。除了解决 CJS 加载 ESM 的问题，它还可以用于：

• 路由级代码分割（Vue Router / React Router 的懒加载）。
• 条件加载大型依赖（比如只有在用户触发某个功能时才加载图表库）。
• 运行时按需加载远程模块（配合 import maps 技术）。

但动态 import 也有代价：它会让模块变成异步的，如果你在模块顶层想直接用 require 那样的同步语义，就会遇到麻烦。所以在不需要按需加载的场景，别为了“高级”而滥用。

提示：在 Node 的 CJS 环境里 import() 是支持异步加载的，但不要试图 await 一个已经是同步可用的 CJS 模块再把它变成 ESM 格式——模块格式是文件层面的属性，不是运行时能转换的东西。

6. 写在最后的几点体会

从 CJS 到 ESM 的演进，本质上是 JavaScript 从“脚本语言”走向“平台语言”的必经之路。CJS 的同步模型简单直接，适合服务端；ESM 的静态分析与异步支持，让前端工程化有了更广阔的优化空间。

我在实际操作中最大的体会是：不要在单个文件里混写两种模块语法。一个文件必须是清晰的 CJS 或清晰的 ESM，然后通过工具链或条件导出去处理边界。很多看似玄学的报错，最后追根溯源，都是因为某一层模块格式的预期和实际不一致。

另外，排错时尽量先判断“这个文件让谁在什么环境下加载”。Node 原生加载？Webpack 打包？Vite 预构建？测试框架转译？加载方的不同，决定了它期望什么格式。一个报错如果直接告诉你文件路径和错误码（比如 ERR_REQUIRE_ESM），先别改代码，先去查这个文件在 package.json 里的声明，往往十分钟就能定位。

最后再分享一个小技巧：如果你有某个依赖的模块格式总是不确定，直接在命令行里跑一句：

bash复制node -e "console.log(require.resolve('some-package'))"

然后打开那个入口文件，看它的语法和 package.json 的 type 字段。这个方法我用了无数次，比任何文档都直观。模块化听起来概念很多，但只要你抓住了“文件格式由扩展名和 package.json 决定”这一条主线，再多的混用问题都能理出头绪。