从零到一：彻底搞懂 JavaScript 中的 CommonJS 规范-开发者社区

一杯咖啡的时间，带你穿透 Node.js 模块系统的灵魂

你是否曾面对这样的代码陷入沉思：

constfs=require('fs');module.exports=classLogger{...};

为什么 Node.js 用require而非import？exports和module.exports到底有何玄机？当两个模块互相引用时，程序为何没有崩溃？

这一切的答案，都藏在CommonJS—— 这个塑造了 Node.js 生态的模块规范之中。今天，让我们拨开迷雾，深入理解这个“古老却依然鲜活”的 JavaScript 模块基石。

一、为何而生：CommonJS 的历史使命

2009 年，JavaScript 还困于浏览器 sandbox。当 Ryan Dahl 构建 Node.js 时，他面临一个核心问题：如何让 JavaScript 在服务端优雅地组织代码？

彼时，浏览器端尚无标准模块方案（AMD/CMD 尚未普及），而服务端需要：

同步加载（文件系统 I/O 快）
简洁的导出/导入语法
模块作用域隔离

CommonJS 规范应运而生。它并非 JavaScript 语言标准，而是一套社区驱动的模块约定。Node.js 选择将其作为默认模块系统，从此改变了 JavaScript 的命运轨迹。

💡 小知识：CommonJS 最初名为 “ServerJS”，后为避免局限性更名为 CommonJS。

二、核心三剑客：require、module、exports

每个 CommonJS 模块在执行前，Node.js 会隐式包裹如下代码：

(function(exports,require,module,__filename,__dirname){// 你的模块代码});

这五大参数构成了模块的“安全结界”。

🔑 导入：require()

constpath=require('path');// 核心模块constutils=require('./utils');// 文件模块（.js/.json/.node）constlodash=require('lodash');// node_modules 模块

同步阻塞：适合服务端文件系统，不适合浏览器网络加载
路径解析有优先级：核心模块 > 绝对路径 > 相对路径 > node_modules 递归查找
返回值即 module.exports：require 本质是函数调用，返回目标模块导出的对象

📦 导出：exports 与 module.exports 的生死纠缠

// ✅ 正确：通过 exports 添加属性（修改原对象）exports.add=(a,b)=>a+b;exports.PI=3.14;// ✅ 正确：直接替换整个导出对象module.exports=classCalculator{...};// ❌ 致命错误：切断引用链！exports={name:'broken'};// 外部 require 仍得到空对象 {}

关键原理：
exports本质是module.exports的引用别名。初始时二者指向同一空对象{}。

当你exports.xxx = ...→ 修改共同指向的对象
当你exports = ...→ 仅改变局部变量exports的指向，module.exports不变

🌰 比喻：module.exports是房子，exports是钥匙。你可以用钥匙装修房子（添加属性），但若把钥匙扔掉换新钥匙（重新赋值），房子本身没变。

三、深度机制：缓存、循环依赖与执行逻辑

🔄 模块缓存：性能的隐形守护者

Node.js 会将首次加载的模块结果缓存在require.cache中：

require('./config');// 首次执行，缓存结果require('./config');// 直接返回缓存，模块代码不再执行

调试技巧：开发时需热重载？可手动清除缓存：

deleterequire.cache[require.resolve('./config')];

（生产环境慎用！）

🔄 循环依赖：Node.js 的优雅解法

当 A require B，B 又 require A 时：

// a.jsconsole.log('A 启动');exports.flag=false;constb=require('./b');console.log('A 中看到 B.flag:',b.flag);// false（B 尚未执行完）exports.flag=true;// b.jsconsole.log('B 启动');exports.flag=false;consta=require('./a');// 此时拿到 A 当前已导出的部分（flag=false）console.log('B 中看到 A.flag:',a.flag);exports.flag=true;

输出顺序：
A 启动 → B 启动 → B 中看到 A.flag: false → B.flag 设为 true → A 中看到 B.flag: true → A.flag 设为 true

Node.js 不会死锁，而是返回已执行部分的 module.exports 快照。但逻辑易错——最佳实践：重构代码避免循环依赖。

四、实战场景与避坑指南

🛠️ 典型用法：构建工具模块

// logger.jsconstfs=require('fs');constpath=require('path');classLogger{constructor(name){this.name=name;this.logPath=path.join(__dirname,'logs',`${name}.log`);}info(msg){constline=`[${newDate().toISOString()}] [INFO]${msg}\n`;fs.appendFileSync(this.logPath,line);console.log(line.trim());}}// 导出构造函数（必须用 module.exports！）module.exports=Logger;

// app.jsconstLogger=require('./logger');constappLog=newLogger('app');appLog.info('服务启动成功');

⚠️ 高频陷阱清单

陷阱	现象	正确做法
`exports = function() {}`	导出为空对象	`module.exports = function() {}`
忽略`.js`后缀	路径解析失败	显式写`require('./utils.js')`
循环依赖中访问未初始化属性	undefined	重构依赖结构，或延迟访问
修改 require.cache 未处理错误	进程崩溃	添加 try/catch 保护

五、CommonJS vs ES Modules：时代的对话

维度	CommonJS	ES Modules (ESM)
加载时机	运行时同步	编译时静态分析（支持异步）
导出本质	值的拷贝	实时绑定（live binding）
this 指向	module.exports	undefined
Node.js 支持	默认（.js 文件）	需 .mjs 或 package.json 设`"type": "module"`
浏览器原生	❌ 需打包工具	✅ 原生支持`<script type="module">`