接手一个老项目,第一件事是把新写的代码加上 import,运行 node src/index.js,立刻得到:

SyntaxError: Cannot use import statement outside a module

代码语法没问题,问题是 Node 把 .js 当成 CommonJS 解析,而 import 是 ES Module 的语法。两种模块系统在同一个文件里不能混着写。改扩展名为 .mjs、或者在最近的 package.json 里加 "type": "module",都能让这个文件按 ESM 解析。

这个报错只是入口。真正让人绕晕的是后面一连串问题:为什么 ESM 里没有 __dirname、为什么 require 突然未定义、为什么同一个包在有的文件里能 require 在有的文件里只能 import、为什么升级一个依赖后突然报「模块找不到」。这些都和 Node 的运行时结构与模块解析规则有关。这篇从运行时讲起,把两套模块系统和包边界说清。

Node 运行时由什么组成

Node.js 不是一门语言,是一个让 JavaScript 跑在浏览器之外的运行时。它由几块拼起来:V8 引擎负责解析和执行 JavaScript;libuv 负责事件循环、文件、网络、线程池等底层能力;一套标准库(fs、http、path 等)把底层能力包装成 JavaScript 接口;再加上模块加载器,负责找到并加载代码。

我本机跑 node -v 是 v24.21.0,process.platform 是 win32,process.arch 是 x64。这些值说明 Node 暴露了运行环境的真实信息,写跨平台代码时要靠它们判断,而不是猜。比如路径分隔符在 Windows 上是 \,在 Linux 上是 /,用 path.join 而不是手拼字符串,就是为了让运行时替你处理这个差异。

JavaScript 执行是单线程的,但 Node 不是「只有一个线程」。libuv 维护一个线程池处理文件、DNS、加密等阻塞操作,网络 I/O 走操作系统的多路复用。你在 JS 里看到的「异步」,是事件循环把回调排队,等底层操作完成后回来执行。理解这一点,后面讲事件循环、流、worker 才有基础。

我本机打印 process.versions,得到 node 24.21.0、v8 13.6.233.17-node.53、uv 1.52.1、openssl 3.5.8。这四个版本号对应四块不同的技术:JS 引擎、事件循环、底层 I/O、加密库。排查「同一个 API 在不同机器行为不一致」时,先比对这些版本,不要只看 Node 的大版本号;libuv 或 OpenSSL 的小版本差异,同样能改变网络和加密的行为。

一次 Node 进程的主要组成部分
你的代码业务模块、依赖包
标准库fs、http、path、stream
libuv事件循环、线程池、网络
操作系统文件、socket、定时器

模块加载器是运行时里最容易被忽略的一块。它决定「require("x") 到底加载哪个文件」,规则不止「去 node_modules 找」这么简单。搞不清规则,就会出现「本地能跑、服务器找不到」「两个文件引用了不同版本的同一个包」这类问题。

CommonJS:require、module.exports 与缓存

CommonJS 是 Node 最早的模块系统。每个文件是一个模块,内部有 module、exports、require、__filename、__dirname 这几个变量。module.exports 决定这个模块对外暴露什么,require 加载另一个模块并返回它的 module.exports。

// math.cjs
exports.add = (a, b) => a + b;
module.exports = { b: 2 };

上面这段是真实会踩的坑:先给 exports.add 赋值,再把 module.exports 整个替换成新对象。结果 add 消失了,外部只拿到 { b: 2 }。原因是一开始 exports 和 module.exports 指向同一个对象,重新赋值 module.exports 只是让模块属性指向新对象,exports 还指着旧的。规则很简单:要么一直用 exports.xxx,要么一直用 module.exports = ...,不要中途换。

CommonJS 的加载是同步的:require 执行时,会先把目标文件读进来、包装成函数、执行完,拿到结果再继续。第一次加载后结果会进缓存,我本机打印 require.cache 的键数量是 1,再次 require 同一个路径返回同一个对象。所以模块里的顶层变量是进程级单例,适合放配置、连接池,也意味着状态会跨请求残留,测试时要小心。

循环依赖在 CommonJS 里表现为「拿到半成品」。A 加载 B,B 又加载 A,B 拿到的 A 是执行到一半的 module.exports,某些属性可能还没赋值。这种问题不会报错,只在运行时出现 undefined is not a function。设计上尽量减少循环依赖,把共享部分抽到第三个模块,比事后调试便宜。

CommonJS 的每个文件在加载时会被包进一个函数。require('node:module').wrapper 打印出来是 (function (exports, require, module, __filename, __dirname) { 开头、}); 结尾。这层包装解释了三件事:文件里的顶层变量是模块私有的,不会污染全局;顶层的 this 指向 module.exports;顶层可以写 return,但它只会提前结束这个包装函数。理解这层结构,「模块里的变量为什么别的文件看不见」就不再神秘。

require 函数本身还带几个有用的属性:require.resolve 只解析不加载,返回最终文件路径;require.cache 是缓存表,删掉某个键再 require 能强制重新加载,适合热更新和测试隔离;require.main 指向入口模块,判断「当前文件是不是被直接运行」可以用 require.main === module。这几个属性在 ESM 里没有完全对应的写法,迁移时要逐个替换。

ES Module:静态、异步、没有 __dirname

ES Module 是语言标准里的模块系统。它用 import 和 export,加载是静态分析的:引擎在执行前就确定依赖关系,所以 import 必须写在顶层,不能放在 if 里,也不能用变量拼路径。好处是能做静态检查和 tree shaking,坏处是动态加载要用 import() 返回 Promise。

ESM 里没有 require、module、exports,也没有 __filename 和 __dirname。我实测在 .mjs 里打印 typeof __dirname 得到 undefined,typeof require 也是 undefined,直接调用 require 会抛 ReferenceError: require is not defined。要用当前文件路径,可以拿 import.meta.url 再转成路径;要用 require,用 module.createRequire(import.meta.url)。

import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const path = require('node:path');

Node 24 的 import.meta 里除了 url,还有 filename 和 dirname。我用 node --input-type=module -e 打印,得到 url 是 file:///C:/project/docs/[eval1],filename 是 C:\project\docs\[eval1],dirname 是 C:\project\docs。所以新代码可以直接用 import.meta.dirname 拼路径,不必再手写 fileURLToPath。但这是较新的能力,跨大版本的项目要确认目标运行时支持,老版本仍然要转换。

ESM 支持顶层 await,这对初始化配置、建立连接很方便。CommonJS 不支持,只能在 async 函数里包一层。但顶层 await 会让模块加载变慢,所有依赖它的模块都要等它完成,别在入口模块里做耗时操作。

ESM 的绑定是「活绑定」:导入的值跟着导出模块的变量变化。CommonJS 是值拷贝,导入之后原模块再改变量,导入方看不到。这个差别在计数器、配置对象这类可变导出上会显形。写库时如果同时支持两种格式,要注意这个语义差异。

CommonJS

同步加载,运行时可以动态 require,有 __dirname,生态老、兼容性好。适合脚本、老项目、需要条件加载的场景。

ES Module

静态加载,支持顶层 await,没有 __dirname,标准统一。适合新项目、需要 tree shaking 的场景,和浏览器写法一致。

扩展名与 package.json 的 type 决定解析方式

Node 判断一个文件按 CJS 还是 ESM 解析,看两样东西:文件扩展名和最近的 package.json 的 type 字段。.mjs 永远是 ESM,.cjs 永远是 CJS,.js 则看 type:"module" 按 ESM,缺省或 "commonjs" 按 CJS。

「最近的 package.json」不是指项目根,而是从当前文件往上找,遇到的第一个 package.json。这就是「包边界」:一个目录里有自己的 package.json,它下面的 .js 就按这个文件的 type 解析,和上层无关。把某个子目录标记成 ESM,不需要改整个项目。

实际项目里的策略通常是:新项目直接在根 package.json 写 "type": "module",全部用 ESM;老项目保持 CJS,需要 ESM 的文件用 .mjs 或独立子包;库要同时支持两种,用构建工具产出两套,或者用 exports 字段分别指向。

改 type 是全局性的:同一个目录下所有 .js 的解析方式都会变。一个老项目里只要有一个文件依赖 require,改完之后就会集体报错。迁移要按目录分批,先让新代码用 .mjs,再逐步改旧文件。

package.json 本身写坏也会影响解析。少一个逗号、加了注释、用了单引号,Node 读的时候直接抛 ERR_INVALID_PACKAGE_CONFIG,报错里会给出文件和字符位置。这类错误发生在启动阶段,堆栈里全是 module 内部帧,和业务代码无关。看到这种形态先校验最近的 package.json,用 node -e "require('./package.json')" 能最快确认它是不是合法 JSON。

require 和 import 怎么找文件

路径分四类:以 node: 开头的是内置模块,比如 node:fs;以 ./、../、/ 开头的是相对或绝对路径;其余是「裸模块名」,比如 lodash,要去 node_modules 找。

裸模块名的查找会从当前目录一路往上,每层都看 node_modules/包名,直到文件系统根。找到包目录后,读它的 package.json,按 exports、main、module 等字段决定入口;没有这些字段就找 index.js。这就是为什么「本地能跑、服务器找不到」:服务器上的目录层级不同,或者依赖没装上。

相对路径也不是「找到文件就行」。CommonJS 会按 .js、.json、.node 的顺序尝试扩展名,我打印 Module._extensions 的键确实是 ['.js', '.json', '.node']。如果给的是目录,会先读目录里的 package.json 找 main,没有就试 index.js。ESM 更严格:相对导入必须写全扩展名,import './util' 直接报 ERR_MODULE_NOT_FOUND,不会替你补 .js。这条差异是 CJS 项目迁 ESM 时最常漏改的地方。

还有一个容易忽略的细节:内置模块名可以被 node_modules 里的同名包遮蔽。目录里装了叫 fs 的第三方包,require('fs') 可能拿到那个包而不是内置模块。加 node: 前缀,写成 require('node:fs'),可以强制走内置。新版标准库文档基本都用这个写法,照抄能省掉一类隐蔽问题。

exports 字段是现代包控制入口的正式方式。它可以按条件导出,比如 import 条件给 ESM,require 条件给 CJS,还能限制「哪些子路径允许被外部引用」。一旦包声明了 exports,没列在里面的子路径就不能直接引用,哪怕文件真实存在。升级依赖后报「Package subpath is not defined by exports」,就是这条规则。

同时提供 CJS 和 ESM 的包会遇到「双包危险」:同一个包被 require 和 import 各加载一次,得到两份独立的模块状态。单例、缓存、全局配置都不再共享。库作者通常用 exports 条件导出来缓解,但无法彻底消除;业务代码里混用两种加载方式时,要意识到可能有两份实例。

裸模块名的查找方向
当前目录找 node_modules/包名
逐级向上父目录、祖父目录依次查找
读 package.json按 exports 或 main 定入口
加载文件按扩展名和 type 决定解析方式

两套系统混用时的真实表现

ESM 可以导入 CommonJS,默认导入拿到的是 module.exports 整个对象。命名导入则依赖 Node 的静态分析:它能识别 exports.foo = ... 这种写法,但识别不了动态赋值。我第一次写 import def, { b } from './c1.cjs' 时,Node 直接报:

SyntaxError: Named export 'b' not found. The requested module './c1.cjs' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from './c1.cjs';
const { b } = pkg;

原因是那个 CJS 模块最后执行了 module.exports = { b: 2 },是运行时赋值,静态分析看不到。正确写法是默认导入再解构,或者把 CJS 包改成静态可分析的 exports.b = ...。看到这个报错不要怀疑语法,先看被导入的包是怎么导出值的。

反过来,CommonJS 不能 require 一个纯 ESM 模块,会报 ERR_REQUIRE_ESM。较新版本对「没有顶层 await 的 ESM」放宽了限制,但依赖版本和包的写法,不要假设一定能成。稳妥做法是在 CJS 里用动态 import(),它返回 Promise,可以在 async 函数里等待。

Node 24 的 fetch、AbortController、structuredClone 这些全局能力在两种模块里都能用,不需要导入。判断「某个东西要不要 import」,看它是语言内置、Node 全局,还是标准库模块。全局的直接用,标准库的要导入,第三方包按包文档来。

动态 import() 在 CJS 和 ESM 里都能用,返回 Promise,加载结果同样进缓存:同一个说明符第二次 import() 拿到的是同一个模块命名空间对象。它适合按需加载大依赖、按环境选实现。注意说明符按 ESM 规则解析,相对路径要基于当前模块的 URL,不是 require 的相对路径语义;拼错时会抛 ERR_MODULE_NOT_FOUND,不会像 require 那样尝试补扩展名。

从 ESM 导入 CJS 时,import pkg from './x.cjs' 拿到的是整个 module.exports;如果 CJS 模块导出的是函数,默认导入就是这个函数。标准库里 import { readFile } from 'node:fs' 能成立,是因为内置模块做了静态标注。第三方包能不能命名导入,取决于它是否静态可分析,别把标准库的经验套到所有包上。

现象对照

现象真实原因第一步查什么
Cannot use import statement outside a module文件按 CJS 解析,却写了 ESM 语法看扩展名和最近 package.json 的 type
require is not defined文件按 ESM 解析,ESM 没有 require改用 import,或 createRequire
__dirname is not definedESM 没有这两个变量用 import.meta.url 转路径
exports 上的属性消失中途替换了 module.exports统一导出方式,别混用
同一个包出现两份状态CJS 和 ESM 各加载一次,形成双包统一加载方式,检查依赖的 exports 条件
Package subpath is not defined by exports包用 exports 限制了可引用子路径看包的 exports 字段,改用公开入口
Cannot find module相对路径写错、依赖没装、或目录层级不同打印 require.resolve 或 import.meta.resolve
循环依赖里拿到 undefined模块还没执行完就被引用,拿到半成品画出依赖方向,抽公共模块打破环
ERR_REQUIRE_ESM用 require 加载纯 ESM 模块改用 import(),或让包提供 CJS 入口

边界与代价

模块系统的选择会影响整个项目的形态。CJS 生态成熟、写法宽松,但静态分析弱、tree shaking 难;ESM 标准统一、依赖关系清晰,但迁移成本高,很多老库只提供 CJS。选型不是「哪个更先进」,是「生态和工具链能不能配合」。

模块解析规则带来的第一个代价是「隐式」。同样一行 require("x"),在不同目录下可能解析到不同版本,排查时必须打印解析结果。第二个代价是缓存:模块级状态是进程单例,测试之间会互相污染,需要显式清理或隔离。第三个代价是循环依赖,它不会报错,只在运行时给半个对象。

包边界还有发布层面的代价。库作者要维护 exports 映射、两套产物、类型声明,稍不注意就会出现「CJS 能导入、ESM 报命名导出不存在」。这些不是业务代码的问题,但用库的人会先撞上,所以要会看包的 package.json 和文档。

最后是运行环境差异。Node 的模块解析和浏览器不同,浏览器没有 node_modules 逐级查找,靠打包工具提前解析。同一份代码在 Node 能跑,在浏览器可能要改导入路径或加扩展名。跨端项目从第一天就统一规则,比事后修修补补省事。

代价还体现在启动时间上。模块越多、node_modules 层级越深,启动时同步读取和解析的文件就越多。我本机一个只引两个内置模块的脚本,启动在几十毫秒量级;引入几十个依赖后,启动时间明显变长。常驻服务不太在意这点,命令行工具和冷启动敏感的场景要在意,可以用延迟加载或打包来压缩这部分开销。

小结

Node 由 V8、libuv、标准库和模块加载器组成,JS 单线程但底层有线程池;CommonJS 用 require 和 module.exports,同步加载、有缓存和 __dirname;ESM 用 import/export,静态加载、支持顶层 await、没有 require 和 __dirname;文件按扩展名和最近 package.json 的 type 解析;裸模块名逐级向上找 node_modules,exports 字段控制入口和子路径;两套系统混用会出现双包和命名导出问题。

遇到模块问题,按这个顺序查:文件被当成哪种模块、路径解析到哪个文件、导出的是值还是引用、有没有两份实例。四步走完,大部分报错都能定位。

当天可以自己验证的练习:

  1. 在同一个目录放 a.js 和 a.mjs,分别写 import 和 require,运行看哪个报错,记录原文。
  2. 在 .mjs 里打印 typeof __dirname 和 typeof require,再用 createRequire 加载一个 CJS 模块。
  3. 写一个 CJS 模块,先 exports.a = 1 再 module.exports = { b: 2 },用 require 和 import 各取一次,记录结果。
  4. 在子目录放一个 package.json 写 "type": "module",观察上层 CJS 文件是否受影响。
  5. 用 require.resolve 打印一个依赖的真实路径,再删掉 node_modules 重跑,记录报错。

下一篇讲常用 API:Buffer、path、fs、process。模块系统解决「代码从哪来」,核心 API 解决「代码能做什么」:字节怎么处理、路径怎么拼、文件怎么读写、进程信息怎么拿。这些接口的默认值和边界,和 Python 那篇一样值得逐条确认。