Импорт модулей в Node.js

Когда вы начинаете писать проект на Node.js, одна из первых проблем, с которыми вы сталкиваетесь, — это как импортировать модули.

В Node.js модули — это переиспользуемые файлы JavaScript, которые взаимодействуют друг с другом через импорт и экспорт.

Экосистема Node.js в основном поддерживает две системы модулей:CommonJSи ES Modules (ESM)。

Модульная система Спецификация Расширение файла Метод импорта Метод экспорта
CommonJS Раннее использование Node.js .js require() module.exports / exports
ES-модуль (ESM) Стандарт ECMAScript .mjsили"type": "module" import export / export default

Система модулей CommonJS

CommonJS — самая ранняя и наиболее широко используемая система модулей в Node.js. Она использует синхронную загрузку; это означает, что при загрузке модуля выполнение программы блокируется до завершения загрузки.

Импорт и экспорт

В CommonJS вы используетеrequire()функцию для импорта модулей и используетеmodule.exportsилиexportsобъект для экспорта модулей.

Способы экспорта:

код файла math.js:

// math.js
function add(a, b) {
  return a + b;
}

module.exports = { add };
// Или: exports.add = add;

Методы импорта:

Пример

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

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

Чтобы модуль мог предоставлять внешний доступ к своему содержимому, ему нужно использовать module.exports или exports для его экспорта:

Пример

// user.js
const name = 'Alice';
const age = 30;

// Способ 1: используйте module.exports для экспорта одного объекта или значения
module.exports = {
  name: name,
  age: age,
  sayHello: () => {
    console.log(`Hello, my name is ${name}.`);
  }
};

// Способ 2: используйте exports для экспорта нескольких именованных переменных
// exports — это ссылка на module.exports
exports.name = name;
exports.age = age;
exports.sayHello = () => {
  console.log(`Hello, my name is ${name}.`);
};

Методы импорта:

Пример

// main.js
const user = require('./user.js');

console.log(user.name); // Вывод: Alice
user.sayHello(); // Вывод: Hello, my name is Alice.

// Также можно деструктурировать напрямую
const { name, age } = require('./user.js');
console.log(name); // Вывод: Alice

Возможности CommonJS:

  • Синхронная загрузка: Подходит для серверных сред, поскольку модули обычно находятся в локальной файловой системе и загружаются быстро.
  • Загрузка во время выполнения:require()Его можно вызвать в любом месте кода, что позволяет динамически загружать модули в зависимости от условий.
  • Механизм кэширования:require()Загруженные модули кэшируются. При повторном импорте они читаются напрямую из кэша, что позволяет избежать повторной загрузки.

Спецификация ES Module (ESM)

ESM — официальный стандарт модулей JavaScript. Он использует асинхронную загрузку и является первым выбором для браузеров и современных приложений Node.js.

В ESM вы используете инструкциюimportдля импорта модулей и инструкциюexportдля экспорта модулей.

Включение ESM:Чтобы использовать ESM в Node.js, нужно добавить"type": "module", или изменить расширение файла на.mjs。

// package.json
{
  "type": "module"
}

Экспорт модулей:

Пример

// math.mjs
export function add(a, b) {
  return a + b;
}

export default function multiply(a, b) {
  return a * b;
}

Импорт модулей:

Пример

// app.mjs
import multiply, { add } from './math.mjs';

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

Как включить:

  • Используйте расширение файла.mjs

  • Или добавьте это в package.json:

    {
      "type": "module"
    }

ESM поддерживает два метода экспорта: именованные экспорты и экспорт по умолчанию.

Пример

// user.mjs

// Именованный экспорт
export const name = 'Bob';
export const age = 25;

// Экспорт по умолчанию
const sayHello = () => {
  console.log(`Hello, my name is ${name}.`);
};
export default sayHello;

Методы импорта:

Пример

// main.mjs

// Импорт именованного экспорта
import { name, age } from './user.mjs';
console.log(name); // Вывод: Bob

// Импорт экспорта по умолчанию
import sayHello from './user.mjs';
sayHello(); // Вывод: Hello, my name is Bob.

// Импорт именованных и экспортов по умолчанию вместе
import sayHello, { name } from './user.mjs';
console.log(name);
sayHello();

// Импорт всех именованных экспортов как свойств объекта
import * as user from './user.mjs';
console.log(user.name);
user.default(); // Экспорт по умолчанию будет свойством default

Возможности ESM:

  • Асинхронная загрузка: по умолчанию она асинхронна и не блокирует основной поток, что делает её более подходящей для браузерных окружений, но в Node.js обычно ведёт себя как синхронная загрузка.
  • Статический анализ:importиexportинструкции могут определять зависимости модуля до выполнения кода, позволяя инструментам (таким как Webpack, Vite) проводить более эффективные оптимизации (например,Tree Shaking)。
  • Строгий режим: модули ESM по умолчанию выполняются в строгом режиме.

Различия между CommonJS и ESM

Item CommonJS ESM
Синтаксис require / module.exports import / export
Механизм загрузки Синхронная загрузка во время выполнения Статическая загрузка во время компиляции
Поддержка по умолчанию Поддерживается по умолчанию в Node.js Нужно.mjsили"type": "module"
Подходящие сценарии Серверные скрипты, устаревшие проекты Современные фронтенд- и бэкенд-проекты, Tree-shaking
Можно ли их смешивать? Нельзя смешивать напрямую (требуется дополнительная настройка) Нельзя смешивать напрямую (требуется дополнительная настройка)

Смешанное использование

Node.js поддерживает сосуществование обеих модульных систем в новых версиях. Вы можете использовать CommonJS и ESM вместе в одном проекте, но нужно учитывать следующее:

  • ESM не может напрямую использоватьrequire()иmodule.exports。
  • CommonJS не может напрямую использоватьimportиexport。
  • Если вы хотите импортировать модуль CommonJS в ESM, вы можете напрямую использоватьimportинструкцию, и ESM будет рассматривать его как экспорт по умолчанию.

    // commonjs_module.js
    module.exports = { data: 'hello' };
    
    // esm_module.mjs
    import commonModule from './commonjs_module.js';
    console.log(commonModule.data); // 输出: hello
    
  • Если вы хотите импортировать модуль ESM в CommonJS, вам нужно использовать динамическийimport()функцию.

    // esm_module.mjs
    export const name = 'Bob';
    
    // commonjs_module.js
    async function loadESM() {
      const { name } = await import('./esm_module.mjs');
      console.log(name);
    }
    loadESM();
    

Рекомендации по лучшим практикам

Для новых проектов,настоятельно рекомендуется использовать ES Modules (ESM). Это не только официальный стандарт JavaScript, но и обладает лучшей совместимостью с современными фронтенд-инструментами (такими как Vite, Next.js), и может в полной мере использовать такие методы оптимизации, как Tree Shaking, чтобы уменьшить размер собранного кода.

Если вы поддерживаете старый проект на CommonJS и не нуждаетесь в возможностях ESM, вы можете продолжать использовать CommonJS. Однако, если вам нужно добавить новые зависимости или воспользоваться новыми возможностями ESM, вы можете рассмотреть постепенную миграцию или использование смешанного режима в качестве переходного этапа.

Другие расширения