Node.js 模块格式:ESM 与 CommonJS

为 Node.js 文件选择正确的模块格式,并排查导入语法与运行配置不匹配的问题。

🎯 引言

学完这篇文章,你能为 Node.js 文件选择正确的模块格式,并排查导入语法与运行配置不匹配的问题。


🛠 在 Node.js 中运行 ESM

import、export 的语法沿用 ES6 模块课程。直接用 Node.js 运行时,需要额外确认文件被当作 ES Modules(ESM) 还是 CommonJS(CJS) 加载:格式不匹配,原本正确的模块代码也可能无法运行。

依赖安装、项目脚本和锁文件统一见 NPM 课程,这里仅使用 package.json 中决定 Node.js 模块格式的配置。

先创建 greet.mjs,.mjs 明确告诉 Node.js 使用 ESM:

greet.mjs
export const greet = name => `你好,${name}`

同目录创建入口文件:

main.mjs
import { greet } from './greet.mjs'
console.log(greet('小明'))

运行 node main.mjs,输出 你好,小明。这里的 ./greet.mjs 相对于入口文件;不要照搬前端构建工具允许的省略扩展名写法。

已有 Node.js 项目还经常使用 CommonJS。它用 require 和 module.exports 组织模块,下面用同一个任务说明这套写法。


⚖️ CommonJS:提供一个值,再取得这个值

用 module.exports 导出

另存 greet.cjs,.cjs 明确表示 CJS:

greet.cjs
module.exports = name => `你好,${name}`

module.exports 是这个文件交给其他模块的值,这里交出去的是函数;需要提供多个功能时,也可以交出去一个对象。

用 require 导入

同目录保存 main.cjs,运行 node main.cjs:

main.cjs
const greet = require('./greet.cjs')
console.log(greet('小明'))

结果仍为 你好,小明。require() 返回目标文件的 module.exports,所以 greet 是可调用的函数。

已有代码还可能使用 exports.greet = ... 添加导出属性。exports 起初指向同一个导出对象;但直接写 exports = ... 只是改了这个局部变量,不会替换真正的导出。需要整体替换时使用本文的 module.exports = ...。


🧰 使用 .js 时,明确 type 配置

.mjs、.cjs 可以直接表明格式。如果团队统一使用 .js,则用 package.json,项目配置文件中的 type 声明:

package.json
{
    "type": "module"
}

module 表示该包范围内的 .js 使用 ESM,commonjs 表示使用 CJS。配置通常由距离文件更近的 package.json 决定。

验证时,把前面的 ESM 文件改名为 greet.js、main.js,并将导入路径也改为 ./greet.js。在同目录保留以上配置,运行 node main.js,仍会输出问候语。

全课程运行示例统一使用 ESM 和 .mjs;本篇为解释模块差异,单独保留 CommonJS 对比,以及 .js 的 type 配置示例。

❓ 知识问答

Q1:Vue 项目能省略扩展名,为什么这里报错?

前端构建工具可能替你补全路径;直接运行 Node.js ESM 时,本地导入要指向完整文件路径。

Q2:把 .cjs 改成 .mjs 就行了吗?

不行,还要把 require、module.exports 等写法改成对应的 ESM 语法。

Q3:ESM 能直接写 require 吗?

默认没有这个变量。本课程保持每组示例格式一致,使用第三方包时按它提供的导入说明操作。


🧪 小练习

把 ESM 示例的两个文件改为 .js,配置 package.json 并更新导入路径,确认 node main.js 仍能输出问候语。再把配置改为 "type": "commonjs",观察模块格式与代码不匹配时的报错。

// 请在这里编写代码

🎉 现在可以用自己的例子验证这些用法啦!