Node.js / 系统课时
CommonJS 模块基础
CommonJS 模块基础
CommonJS 是 Node.js 长期支持的模块系统之一,核心接口是 require()、module.exports 和模块缓存。学会这三部分后,可以把代码拆成独立文件、明确导出内容,并理解为什么同一个模块被多次 require() 时通常只执行一次。
学习目标
- 使用
require()加载本地 CommonJS 模块,并通过module.exports暴露函数和数据。 - 理解模块首次加载、执行、缓存以及再次读取缓存的顺序。
- 分清
module.exports与exports的关系,避免导出空对象。
用 require 和 module.exports 拆分代码
CommonJS 文件通过 module.exports 指定对外值,调用方使用 require() 获取它。下面用两个完整文件建立最小示例;相对路径模块必须以 ./ 或 ../ 开头,否则 Node.js 会按包或核心模块的规则解析名称。
保存为 math.js:
function add(a, b) {
return a + b;
}
function multiply(a, b) {
return a * b;
}
module.exports = { add, multiply };保存为 app.js:
const math = require('./math');
console.log('2 + 3 =', math.add(2, 3));
console.log('4 * 5 =', math.multiply(4, 5));运行入口文件:
node app.js预期输出:
2 + 3 = 5
4 * 5 = 20这里真正对外公开的是 module.exports 指向的对象。math.js 中没有导出的局部变量和函数,其他模块无法直接通过 require('./math') 取得。
模块为什么只执行一次
第一次执行 require('./counter') 时,Node.js 会解析模块文件、创建模块对象、执行文件代码,然后把最终导出值记录到模块缓存。之后再次加载解析到同一文件的模块时,通常直接返回缓存中的 exports,而不会重新执行整个文件。

用一个可运行例子观察缓存。保存为 counter.js:
console.log('counter module executed');
module.exports = {
value: 1
};保存为 cache-demo.js:
const first = require('./counter');
const second = require('./counter');
console.log('same object:', first === second);
console.log('value:', second.value);运行:
node cache-demo.js预期输出:
counter module executed
same object: true
value: 1counter module executed 只出现一次,同时 first === second 为 true,说明两次调用取得的是缓存中的同一个导出对象。缓存以解析后的模块文件为基础管理,因此不要把 require() 理解成每调用一次就重新执行一次文件。
module.exports 和 exports 不可随意互换
Node.js 初始化 CommonJS 模块时,exports 最初只是指向 module.exports 的快捷引用。因此给 exports.name 增加属性可以生效,但直接执行 exports = {...} 只会让局部变量 exports 改为指向另一个对象,并不会替换真正导出的 module.exports。
下面是一个完整的错误示例。保存为 wrong.js:
exports = {
value: 42
};保存为 wrong-demo.js:
const result = require('./wrong');
console.log(result);运行:
node wrong-demo.js预期输出:
{}如果需要整体替换导出值,应明确写成 module.exports = { value: 42 }。如果只是向默认对象追加属性,可以写 exports.value = 42。项目中最好统一一种写法;当导出函数、类或整个对象时,直接使用 module.exports = ... 最不容易产生歧义。
缓存适合共享初始化结果,也会共享可变状态
缓存意味着模块级对象可能在多个调用方之间共享。比如导出 { count: 0 } 后,模块 A 把 count 改成 1,模块 B 再 require() 同一模块时通常会看到修改后的值,而不是新的 { count: 0 }。因此配置常量、工具函数和昂贵的一次性初始化很适合放在模块顶层,可变的请求级状态则不应依赖这种隐式共享。
调试时可以查看 require.cache,其中键通常是已解析模块文件的绝对路径。确实需要重新加载某个模块时可以删除对应缓存项,但业务代码不应把频繁清缓存当作正常控制流程;更可控的做法是导出工厂函数,让调用方显式创建新的状态实例。