module.exports и exports в Node.js: разница и примеры

module.exports это значение, которое файл Node.js отдаёт любому другому файлу, загружающему его через require(). Сначала это пустой объект: добавьте ему свойства, чтобы экспортировать несколько вещей, или присвойте новое значение (функцию, класс), чтобы экспортировать одну. exports это переменная-сокращение, которая указывает на тот же объект, поэтому exports.add = ... работает, а exports = ... рвёт связь и ничего не экспортирует.

const fs = require('fs');

// setup: write a second module next to index.js
fs.writeFileSync('math.js', `
module.exports.add = (a, b) => a + b;
exports.multiply = (a, b) => a * b;
module.exports.PI = 3.14159;
`);

const math = require('./math');

console.log(math.add(2, 3), math.multiply(4, 5), math.PI);
console.log(Object.keys(math));

Программа вывела 5 20 3.14159, затем [ 'add', 'multiply', 'PI' ]. Все три строки в math.js добавили свойства одному и тому же объекту, через module.exports или через exports, и require('./math') вернул этот объект.

Экспорт функции, класса или объекта

Когда у модуля одна главная вещь, присвойте её прямо в module.exports. Тогда вызывающий код получает саму функцию, а не объект вокруг неё:

const fs = require('fs');

// setup: two modules, one exports a function, one a class
fs.writeFileSync('greet.js', `
module.exports = function greet(name) {
    return 'Hello, ' + name;
};
`);
fs.writeFileSync('user.js', `
class User {
    constructor(name) { this.name = name; }
    describe() { return this.name + ' (user)'; }
}
module.exports = User;
`);

const greet = require('./greet');
const User = require('./user');

console.log(greet('Ada'));
console.log(new User('Grace').describe());

Программа вывела Hello, Ada и Grace (user). Если видите TypeError: greet is not a function, вызывающий код ждал не ту форму: пишите const { greet } = require(...) для свойства объекта и const greet = require(...) для присвоенного значения.

module.exports и exports: ловушка с переприсваиванием

Перед запуском вашего файла Node.js выполняет exports = module.exports. Оба имени указывают на один объект, а require возвращает module.exports. Присваивание нового значения в exports меняет только локальную переменную:

const fs = require('fs');

// setup: the same export written two ways
fs.writeFileSync('broken.js', 'exports = { version: 2 };');
fs.writeFileSync('working.js', 'module.exports = { version: 2 };');

console.log('broken:', require('./broken'));
console.log('working:', require('./working'));

broken.js экспортировал {}, потому что exports теперь указывает на новый объект, который никто не возвращает. working.js экспортировал { version: 2 }.

Самое простое правило: всегда пишите module.exports. Это работает в любом случае, и по коду видно, что он делает.

require возвращает тот же объект из кэша

Node.js выполняет код модуля один раз, при первом require, и кэширует module.exports. Каждый следующий require того же файла возвращает тот же объект, поэтому состояние внутри модуля общее для всех файлов, которые его загружают:

const fs = require('fs');

// setup: a module that counts and logs when it loads
fs.writeFileSync('counter.js', `
console.log('counter.js is running');
let count = 0;
module.exports = { next: () => ++count };
`);

const a = require('./counter');
const b = require('./counter.js');

a.next();
a.next();
console.log('b sees', b.next());
console.log('same object:', a === b);

counter.js is running появилось один раз, b.next() вернул 3, а a === b равно true, потому что ключ кэша это полный путь к файлу, а ./counter и ./counter.js указывают на один файл. Поэтому подключение к базе данных или объект конфигурации, созданный в одном модуле, общий для всего приложения.

module.exports и ES модули

ES модули используют export и import. Формы соответствуют друг другу так:

// CommonJS                              // ES modules
module.exports = greet;                  export default greet;
module.exports.add = add;                export { add };
const greet = require('./greet');        import greet from './greet.js';
const { add } = require('./math');       import { add } from './math.js';

ES модуль может через import подключить файл CommonJS: его module.exports приходит как импорт по умолчанию. Начиная с Node.js 22.12, require() тоже может загрузить ES модуль, если в нём нет top-level await. Что когда выбирать, читайте в статье CommonJS и ES модули.

Частые ошибки

exports.x и module.exports = ... в одном файле. Присваивание заменяет объект, и все exports.x, записанные до него, пропадают. Выберите один стиль на файл.

Экспорт значения, которое потом меняется. module.exports = { count } копирует число в момент загрузки; когда модуль обновляет count, вызывающий код всё ещё видит старое значение. Экспортируйте функцию, которая его возвращает, как counter.js выше.

Пропущенный ./. require('math') ищет пакет в node_modules, а не math.js рядом с вашим файлом. Локальные файлы всегда начинаются с ./ или ../.