深入理解 Node.js 模块化（CommonJS）：原理、用法与避坑指南

一、为什么需要模块化

在传统 JavaScript 开发中，所有代码都写在全局作用域中，导致以下问题：

• 命名冲突： 多个脚本的变量/函数名可能重复
• 依赖混乱： 无法明确模块间的依赖关系
• 维护困难： 代码分散难以管理

CommonJS 模块化规范 正是为解决这些问题而生。Node.js 基于该规范实现了自己的模块系统，让代码可以像拼积木一样组织和管理。

二、CommonJS 核心机制

1. 模块定义：module.exports 与 exports
每个 .js 文件都是一个独立模块，拥有自己的作用域。通过 module.exports 对象暴露对外接口：

// math.js
const add = (a, b) => a + b;
const multiply = (a, b) => a * b;

// 导出方式1：直接赋值
module.exports = { add, multiply };

// 导出方式2：逐个挂载（不推荐！容易踩坑）
// exports.add = add;
// exports.multiply = multiply;

2. 模块引入：require()
通过 require() 函数导入其他模块：

// app.js
const math = require('./math.js'); // 引入自定义模块
const fs = require('fs');          // 引入核心模块

console.log(math.add(2, 3));      // 5

三、底层原理揭秘

1. 模块包装器
Node.js 在执行模块代码前，会将其包裹在一个函数中

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

• exports：指向 module.exports 的引用
• module：当前模块的元数据
• __filename：当前文件的绝对路径
• __dirname：当前文件所在目录的路径

2. 模块缓存机制
Node.js 会缓存已加载的模块。重复调用 require('./math') 时：
1.检查缓存中是否存在
2.若存在，直接返回缓存的module.exports
3.若不存在，加载并执行模块代码，然后缓存

四、高级用法与技巧

1.动态加载模块

// 根据条件加载不同模块
const isProduction = process.env.NODE_ENV === 'production';
const logger = isProduction 
  ? require('./prodLogger.js')
  : require('./devLogger.js');

2.JSON文件加载

// 直接加载 JSON 文件（自动解析为对象）
const config = require('./config.json');
console.log(config.apiUrl);

3.目录模块
当 require() 的参数是目录时，Node.js 会查找：
1.目录下的 package.json 中 main 字段指定文件
2.若未指定，则查找index.js 或 index.json

五、注意事项与常见陷阱

🚨陷阱1： exports 的误用

// math.js
exports = { add }; // 错误！这改变了 exports 的指向

// 正确做法：
module.exports = { add }; 

原理：exports 只是 module.exports 的引用，重新赋值会断开连接

🚨陷阱2： 循环依赖

假设 a.js 和 b.js 互相引用：

// a.js
const b = require('./b');
console.log('a 加载 b:', b);
module.exports = { value: 'A' };

// b.js
const a = require('./a');
console.log('b 加载 a:', a);
module.exports = { value: 'B' };

// 输出结果
b 加载 a: {}  // a 尚未完成初始化
a 加载 b: { value: 'B' }

详细分析与解决方案后续会单独写一篇博客

🚨陷阱3： 同步加载

// 这会阻塞事件循环！
const hugeModule = require('./huge-module.js'); 

详细分析与解决方案后续会单独写一篇博客

六、与 ES Modules 的区别

七、最佳实践

1.统一导出风格：

• 优先使用 module.exports = {}
• 避免混用 exports.xxx 和 module.exports

2.路径规范：

// 明确相对路径
const utils = require('./utils');    // ✅ 明确
const lodash = require('lodash');    // ✅ 核心模块或 node_modules

3.模块拆分原则：

• 单一职责：一个模块只做一件事
• 控制体积：单个模块代码不超过300行

4.缓存利用：

// 需要热更新时清除缓存
delete require.cache[require.resolve('./config.js')];
const newConfig = require('./config.js');

八、总结

虽然现在 Node.js 也支持 ES Modules，但是掌握 CommonJS 仍然是 Node.js 开发者的必备技能！