Node.js 模块格式:ESM 与 CommonJS
🎯 引言
学完这篇文章,你能为 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:
export const greet = name => `你好,${name}`
同目录创建入口文件:
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:
module.exports = name => `你好,${name}`
module.exports 是这个文件交给其他模块的值,这里交出去的是函数;需要提供多个功能时,也可以交出去一个对象。
用 require 导入
同目录保存 main.cjs,运行 node 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 声明:
{
"type": "module"
}
module 表示该包范围内的 .js 使用 ESM,commonjs 表示使用 CJS。配置通常由距离文件更近的 package.json 决定。
验证时,把前面的 ESM 文件改名为 greet.js、main.js,并将导入路径也改为 ./greet.js。在同目录保留以上配置,运行 node main.js,仍会输出问候语。
.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",观察模块格式与代码不匹配时的报错。
// 请在这里编写代码
🎉 现在可以用自己的例子验证这些用法啦!
