CommonJS 模块系统详解#

CommonJS 是 Node.js 采用的模块系统，它定义了模块的加载、导出和依赖管理机制。本文将从 require() 函数开始，深入解析 CommonJS 的工作原理。

什么是 CommonJS#

CommonJS 是一个项目，旨在为 JavaScript 定义通用的模块和包规范。它最初是为服务器端 JavaScript 环境设计的，Node.js 是其最著名的实现。

核心特点#

同步加载：模块在运行时同步加载
单例模式：模块只会被加载一次，后续 require 返回缓存
动态加载：可以在运行时根据条件加载模块
文件作用域：每个文件都是一个独立的模块作用域

基本语法#

导出模块#

CommonJS 提供了多种导出方式：

1
// 1. module.exports 导出单个值
2
module.exports = function add(a, b) {
3
  return a + b;
4
};
5

6
// 2. module.exports 导出对象
7
module.exports = {
8
  add: function(a, b) { return a + b; },
9
  subtract: function(a, b) { return a - b; }
10
};
11

12
// 3. exports 快捷方式（注意：不能重新赋值）
13
exports.multiply = function(a, b) {
14
  return a * b;
15
};
16

17
exports.divide = function(a, b) {
18
  return a / b;
19
};

导入模块#

1
// 1. 导入整个模块
2
const math = require('./math');
3
const add = math.add;
4

5
// 2. 解构导入
6
const { add, subtract } = require('./math');
7

8
// 3. 导入核心模块
9
const fs = require('fs');
10
const path = require('path');
11

12
// 4. 导入第三方模块
13
const lodash = require('lodash');
14
const express = require('express');

require() 函数详解#

模块解析规则#

require() 函数按照以下顺序解析模块：

核心模块：如 fs、path、http 等
文件模块：以 ./ 或 ../ 开头的相对路径
node_modules：在当前目录及父目录的 node_modules 中查找

1
// 核心模块
2
require('fs')
3

4
// 文件模块
5
require('./utils')        // 当前目录
6
require('../config')      // 父目录
7
require('/absolute/path') // 绝对路径
8

9
// node_modules 模块
10
require('express')        // 第三方包

文件扩展名解析#

require() 会按顺序尝试以下扩展名：

1
require('./module')
2
// 依次尝试：
3
// 1. ./module.js
4
// 2. ./module.json
5
// 3. ./module.node
6
// 4. ./module/index.js
7
// 5. ./module/package.json 中的 main 字段

模块缓存机制#

1
console.log('模块 A 被加载');
2
module.exports = { name: 'Module A' };
3

4
// main.js
5
const moduleA1 = require('./moduleA'); // 输出: 模块 A 被加载
6
const moduleA2 = require('./moduleA'); // 不会再次输出
7

8
console.log(moduleA1 === moduleA2); // true - 同一个对象引用

深入理解模块包装#

Node.js 会将每个模块包装在一个函数中：

1
// 你写的代码
2
const math = require('./math');
3
exports.calculate = function() {
4
  return math.add(1, 2);
5
};
6

7
// Node.js 实际执行的代码
8
(function(exports, require, module, __filename, __dirname) {
9
  const math = require('./math');
10
  exports.calculate = function() {
11
    return math.add(1, 2);
12
  };
13
});

模块作用域变量#

每个模块都可以访问这些变量：

1
console.log(__filename);  // 当前文件的绝对路径
2
console.log(__dirname);   // 当前文件所在目录的绝对路径
3
console.log(module);      // 当前模块对象
4
console.log(exports);     // module.exports 的引用
5
console.log(require);     // require 函数

exports vs module.exports#

这是 CommonJS 中容易混淆的概念：

1
// 正确使用 exports
2
exports.foo = 'bar';
3
exports.method = function() {};
4

5
// 错误！这会断开 exports 与 module.exports 的链接
6
exports = { foo: 'bar' }; // ❌
7

8
// 正确的做法
9
module.exports = { foo: 'bar' }; // ✅
10

11
// 理解原理
12
// exports 只是 module.exports 的引用
13
// exports = module.exports = {}

module.exports、exports 与 this 的关系#

在 CommonJS 模块系统中，这三者之间存在紧密的关系：

基本关系#

module.exports - 真正的导出对象
exports - module.exports的引用别名
this - 在模块顶层指向exports

1
// 在模块顶层
2
console.log(this === exports);        // true
3
console.log(this === module.exports); // true
4
console.log(exports === module.exports); // true

工作原理#

CommonJS实际上是这样包装模块的：

1
function(exports, require, module, __filename, __dirname) {
2
    // 你的模块代码在这里
3
    // this = exports = module.exports (初始状态)
4
}

使用区别#

正确用法：

1
// 方式1：使用 module.exports
2
module.exports = {
3
    name: 'test',
4
    fn: function() {}
5
};
6

7
// 方式2：向 exports 添加属性
8
exports.name = 'test';
9
exports.fn = function() {};
10

11
// 方式3：使用 this（不推荐）
12
this.name = 'test';

错误用法：

1
// ❌ 错误：重新赋值 exports 会断开引用
2
exports = {
3
    name: 'test'
4
}; // 这不会导出任何东西
5

6
// ✅ 正确：应该使用 module.exports
7
module.exports = {
8
    name: 'test'
9
};

关键点#

exports只是module.exports的引用，重新赋值会断开引用
最终导出的总是module.exports的值
this在模块顶层等同于exports，但在函数内部可能指向其他对象

循环依赖处理#

CommonJS 可以处理循环依赖，但需要注意执行顺序：

1
console.log('a starting');
2
exports.done = false;
3
const b = require('./b');
4
console.log('in a, b.done =', b.done);
5
exports.done = true;
6
console.log('a done');
7

8
// b.js
9
console.log('b starting');
10
exports.done = false;
11
const a = require('./a');
12
console.log('in b, a.done =', a.done);
13
exports.done = true;
14
console.log('b done');
15

16
// main.js
17
const a = require('./a');
18
const b = require('./b');
19

20
// 输出：
21
// a starting
22
// b starting
23
// in b, a.done = false
24
// b done
25
// in a, b.done = true
26
// a done

实战示例#

创建一个简单的工具库#

1
function add(a, b) {
2
  return a + b;
3
}
4

5
function multiply(a, b) {
6
  return a * b;
7
}
8

9
function factorial(n) {
10
  if (n <= 1) return 1;
11
  return n * factorial(n - 1);
12
}
13

14
module.exports = {
15
  add,
16
  multiply,
17
  factorial
18
};
19

20
// utils/string.js
21
function capitalize(str) {
22
  return str.charAt(0).toUpperCase() + str.slice(1);
23
}
24

25
function reverse(str) {
26
  return str.split('').reverse().join('');
27
}
28

29
exports.capitalize = capitalize;
30
exports.reverse = reverse;
31

32
// utils/index.js
33
const math = require('./math');
34
const string = require('./string');
35

36
module.exports = {
37
  math,
38
  string
39
};
40

41
// main.js
42
const utils = require('./utils');
43
const { math, string } = require('./utils');
44

45
console.log(utils.math.add(1, 2));        // 3
46
console.log(math.factorial(5));           // 120
47
console.log(string.capitalize('hello'));  // Hello

配置管理模块#

1
const path = require('path');
2

3
const config = {
4
  development: {
5
    port: 3000,
6
    database: {
7
      host: 'localhost',
8
      port: 5432,
9
      name: 'myapp_dev'
10
    }
11
  },
12
  production: {
13
    port: process.env.PORT || 8080,
14
    database: {
15
      host: process.env.DB_HOST,
16
      port: process.env.DB_PORT,
17
      name: process.env.DB_NAME
18
    }
19
  }
20
};
21

22
const env = process.env.NODE_ENV || 'development';
23

24
module.exports = config[env];
25

26
// app.js
27
const config = require('./config');
28
console.log(`Server running on port ${config.port}`);

CommonJS vs ES Modules#

特性	CommonJS	ES Modules
语法	require/module.exports	import/export
加载时机	运行时	编译时
加载方式	同步	异步
动态导入	支持	需要 import()
浏览器支持	需要打包	原生支持
Node.js	默认支持	需要配置

1
// CommonJS
2
const fs = require('fs');
3
if (condition) {
4
  const module = require('./conditional-module');
5
}
6

7
// ES Modules
8
import fs from 'fs';
9
// 条件导入需要使用动态 import
10
if (condition) {
11
  const module = await import('./conditional-module');
12
}

最佳实践#

1. 模块设计原则#

1
// 好的模块设计 - 单一职责
2
const fs = require('fs');
3

4
function log(message) {
5
  const timestamp = new Date().toISOString();
6
  const logMessage = `[${timestamp}] ${message}\n`;
7
  fs.appendFileSync('app.log', logMessage);
8
}
9

10
module.exports = { log };
11

12
// 避免导出过多功能
13
// bad-module.js ❌
14
module.exports = {
15
  log: () => {},
16
  parseXML: () => {},
17
  sendEmail: () => {},
18
  validatePassword: () => {}
19
};

2. 避免全局状态#

1
// config-manager.js ✅
2
function createConfig(options = {}) {
3
  return {
4
    port: options.port || 3000,
5
    host: options.host || 'localhost',
6
    get: function(key) {
7
      return this[key];
8
    }
9
  };
10
}
11

12
module.exports = { createConfig };
13

14
// 避免直接导出可变状态 ❌
15
let globalState = {};
16
module.exports = globalState;

3. 错误处理#

1
const fs = require('fs');
2

3
function readFileSync(filePath) {
4
  try {
5
    return fs.readFileSync(filePath, 'utf8');
6
  } catch (error) {
7
    throw new Error(`Failed to read file ${filePath}: ${error.message}`);
8
  }
9
}
10

11
function writeFileSync(filePath, data) {
12
  try {
13
    fs.writeFileSync(filePath, data, 'utf8');
14
  } catch (error) {
15
    throw new Error(`Failed to write file ${filePath}: ${error.message}`);
16
  }
17
}
18

19
module.exports = {
20
  readFileSync,
21
  writeFileSync
22
};

调试技巧#

1. 查看模块缓存#

1
// 查看已加载的模块
2
console.log(Object.keys(require.cache));
3

4
// 清除模块缓存（开发环境）
5
delete require.cache[require.resolve('./my-module')];

2. 模块解析调试#

1
// 查看模块解析路径
2
console.log(require.resolve('./my-module'));
3
console.log(require.resolve.paths('my-module'));

总结#

CommonJS 是 Node.js 生态系统的基础，理解其工作原理对于 Node.js 开发至关重要。虽然 ES Modules 正在逐渐普及，但 CommonJS 在很长一段时间内仍将是 Node.js 的重要组成部分。

掌握 CommonJS 的关键点：

理解 require() 的模块解析机制
区分 exports 和 module.exports
了解模块缓存和循环依赖处理
遵循模块设计最佳实践

通过深入理解这些概念，你将能够更好地构建和维护 Node.js 应用程序。