Доступ к главному модулю

Когда файл выполняется непосредственно из Node.js, require.main устанавливается в его module. Это означает, что можно определить, был ли файл запущен напрямую, проверив require.main === module.

Для файла foo.js, это будет true при запуске через node foo.js, но false при запуске через require('./foo').

Так как module предоставляет свойство filename (обычно эквивалентное __filename), точку входа текущего приложения можно получить, проверив require.main.filename.

Дополнительные сведения: советы по менеджерам пакетов

Семантика функции Node.js require() была спроектирована достаточно универсально для поддержки разумных структур каталогов. Программы-менеджеры пакетов, такие как dpkg, rpm, и npm , надеются иметь возможность создавать нативные пакеты из модулей Node.js без модификаций.

Ниже приведена рекомендуемая структура каталогов:

Предположим, мы хотим, чтобы папка в /usr/lib/node/<some-package>/<some-version> содержала содержимое определённой версии пакета.

Пакеты могут зависеть друг от друга. Для установки пакета foo, может потребоваться установить определённую версию пакета bar. Пакет bar сам может иметь зависимости, в некоторых случаях они могут даже конфликтовать или образовывать циклические зависимости.

Поскольку Node.js ищет realpath любых загружаемых модулей (то есть он разрешает символические ссылки) и затем ищет их зависимости в папках node_modules, эту ситуацию можно решить с помощью следующей архитектуры:

• /usr/lib/node/foo/1.2.3/: Содержимое пакета foo, версия 1.2.3.
• /usr/lib/node/bar/4.3.2/: Содержимое пакета bar, от которого зависит foo.
• /usr/lib/node/foo/1.2.3/node_modules/bar: Символическая ссылка на /usr/lib/node/bar/4.3.2/.
• /usr/lib/node/bar/4.3.2/node_modules/*: Символические ссылки на пакеты, от которых зависит bar.

Таким образом, даже если будет обнаружен цикл или конфликт зависимостей, каждый модуль сможет получить версию своей зависимости, которую он может использовать.

Когда код в пакете foo выполняет require('bar'), он получит версию, которая символически связана в /usr/lib/node/foo/1.2.3/node_modules/bar. Затем, когда код в пакете bar вызывает require('quux'), он получит версию, которая символически связана в /usr/lib/node/bar/4.3.2/node_modules/quux.

Кроме того, чтобы сделать процесс поиска модулей ещё более эффективным, вместо того, чтобы помещать пакеты непосредственно в /usr/lib/node, мы можем поместить их в /usr/lib/node_modules/<name>/<version>. Тогда Node.js не будет тратить время на поиск отсутствующих зависимостей в /usr/node_modules или /node_modules.

Для того, чтобы модули были доступны в Node.js REPL, может быть полезно добавить папку /usr/lib/node_modules в переменную окружения $NODE_PATH. Поскольку поиск модулей с использованием папок node_modules является относительным и основан на реальном пути файлов, вызывающих require(), сами пакеты могут находиться где угодно.

Дополнительные сведения: Расширение .mjs

Невозможно require() файлы с расширением .mjs. Попытка сделать это вызовет ошибку. Расширение .mjs зарезервировано для модулей ECMAScript, которые не могут быть загружены через require() . Подробнее см. Модули ECMAScript.

Всё вместе...

Чтобы получить точное имя файла, который будет загружен при вызове require() , используйте функцию require.resolve().

Сводя вместе всё вышесказанное, вот алгоритм высокого уровня, описывающий, что делает require():

require(X) from module at path Y
1. If X is a core module,
   a. return the core module
   b. STOP
2. If X begins with '/'
   a. set Y to be the filesystem root
3. If X begins with './' or '/' or '../'
   a. LOAD_AS_FILE(Y + X)
   b. LOAD_AS_DIRECTORY(Y + X)
   c. THROW "not found"
4. If X begins with '#'
   a. LOAD_PACKAGE_IMPORTS(X, dirname(Y))
5. LOAD_PACKAGE_SELF(X, dirname(Y))
6. LOAD_NODE_MODULES(X, dirname(Y))
7. THROW "not found"

LOAD_AS_FILE(X)
1. If X is a file, load X as its file extension format. STOP
2. If X.js is a file, load X.js as JavaScript text. STOP
3. If X.json is a file, parse X.json to a JavaScript Object. STOP
4. If X.node is a file, load X.node as binary addon. STOP

LOAD_INDEX(X)
1. If X/index.js is a file, load X/index.js as JavaScript text. STOP
2. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP
3. If X/index.node is a file, load X/index.node as binary addon. STOP

LOAD_AS_DIRECTORY(X)
1. If X/package.json is a file,
   a. Parse X/package.json, and look for "main" field.
   b. If "main" is a falsy value, GOTO 2.
   c. let M = X + (json main field)
   d. LOAD_AS_FILE(M)
   e. LOAD_INDEX(M)
   f. LOAD_INDEX(X) DEPRECATED
   g. THROW "not found"
2. LOAD_INDEX(X)

LOAD_NODE_MODULES(X, START)
1. let DIRS = NODE_MODULES_PATHS(START)
2. for each DIR in DIRS:
   a. LOAD_PACKAGE_EXPORTS(X, DIR)
   b. LOAD_AS_FILE(DIR/X)
   c. LOAD_AS_DIRECTORY(DIR/X)

NODE_MODULES_PATHS(START)
1. let PARTS = path split(START)
2. let I = count of PARTS - 1
3. let DIRS = [GLOBAL_FOLDERS]
4. while I >= 0,
   a. if PARTS[I] = "node_modules" CONTINUE
   b. DIR = path join(PARTS[0 .. I] + "node_modules")
   c. DIRS = DIRS + DIR
   d. let I = I - 1
5. return DIRS

LOAD_PACKAGE_IMPORTS(X, DIR)
1. Find the closest package scope SCOPE to DIR.
2. If no scope was found, return.
3. If the SCOPE/package.json "imports" is null or undefined, return.
4. let MATCH = PACKAGE_IMPORTS_RESOLVE(X, pathToFileURL(SCOPE),
  ["node", "require"]) defined in the ESM resolver.
5. RESOLVE_ESM_MATCH(MATCH).

LOAD_PACKAGE_EXPORTS(X, DIR)
1. Try to interpret X as a combination of NAME and SUBPATH where the name
   may have a @scope/ prefix and the subpath begins with a slash (`/`).
2. If X does not match this pattern or DIR/NAME/package.json is not a file,
   return.
3. Parse DIR/NAME/package.json, and look for "exports" field.
4. If "exports" is null or undefined, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(DIR/NAME), "." + SUBPATH,
   `package.json` "exports", ["node", "require"]) defined in the ESM resolver.
6. RESOLVE_ESM_MATCH(MATCH)

LOAD_PACKAGE_SELF(X, DIR)
1. Find the closest package scope SCOPE to DIR.
2. If no scope was found, return.
3. If the SCOPE/package.json "exports" is null or undefined, return.
4. If the SCOPE/package.json "name" is not the first segment of X, return.
5. let MATCH = PACKAGE_EXPORTS_RESOLVE(pathToFileURL(SCOPE),
   "." + X.slice("name".length), `package.json` "exports", ["node", "require"])
   defined in the ESM resolver.
6. RESOLVE_ESM_MATCH(MATCH)

RESOLVE_ESM_MATCH(MATCH)
1. let { RESOLVED, EXACT } = MATCH
2. let RESOLVED_PATH = fileURLToPath(RESOLVED)
3. If EXACT is true,
   a. If the file at RESOLVED_PATH exists, load RESOLVED_PATH as its extension
      format. STOP
4. Otherwise, if EXACT is false,
   a. LOAD_AS_FILE(RESOLVED_PATH)
   b. LOAD_AS_DIRECTORY(RESOLVED_PATH)
5. THROW "not found"

Кэширование

Модули кэшируются после первой загрузки. Это означает (среди прочего), что каждый вызов require('foo') получит ровно тот же объект, если он будет резолвиться к тому же файлу.

При условии, что require.cache не изменяется, многократные вызовы require('foo') не заставят код модуля выполняться несколько раз. Это важная функция. С ней можно возвращать "частично готовые" объекты, что позволяет загружать транзитивные зависимости даже при возникновении циклов.

Чтобы заставить модуль выполнять код несколько раз, экспортируйте функцию и вызовите её.

Ограничения кэширования модулей

Модули кэшируются на основе их резолвированного имени файла. Поскольку модули могут резолвиться к разным именам файлов в зависимости от местоположения вызывающего модуля (загрузка из папок node_modules), нет гарантии, что require('foo') всегда вернёт ровно тот же объект, если он будет резолвиться к разным файлам.

Кроме того, в системах файлов или операционных системах с регистронезависимым режимом разные резолвированные имена файлов могут указывать на один и тот же файл, но кэш всё равно будет рассматривать их как разные модули и будет загружать файл несколько раз. Например, require('./foo') и require('./FOO') возвращают два разных объекта, независимо от того, являются ли ./foo и ./FOO одним и тем же файлом.

Модули ядра

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

Модули ядра определены внутри исходного кода Node.js и находятся в папке lib/.

Модули ядра всегда предпочтительно загружаются, если их идентификатор передаётся в require(). Например, require('http') всегда вернёт встроенный модуль HTTP, даже если существует файл с таким именем.

Циклы

При циклических require() вызовах модуль может не завершить выполнение к моменту своего возвращения.

Рассмотрим эту ситуацию:

a.js:

console.log('a starting');
exports.done = false;
const b = require('./b.js');
console.log('in a, b.done = %j', b.done);
exports.done = true;
console.log('a done');

b.js:

console.log('b starting');
exports.done = false;
const a = require('./a.js');
console.log('in b, a.done = %j', a.done);
exports.done = true;
console.log('b done');

main.js:

console.log('main starting');
const a = require('./a.js');
const b = require('./b.js');
console.log('in main, a.done = %j, b.done = %j', a.done, b.done);

Когда main.js загружает a.js, а затем a.js загружает b.js . В этот момент b.js пытается загрузить a.js. Чтобы избежать бесконечного цикла, возвращается незавершенная копия объекта экспорта a.js модулю b.js . Затем b.js завершает загрузку, и его объект exports предоставляется модулю a.js.

К моменту загрузки обоих модулей main.js , они оба завершены. Выходная информация этой программы будет следующей:

$ node main.js
main starting
a starting
b starting
in b, a.done = false
b done
in a, b.done = true
a done
in main, a.done = true, b.done = true

Для корректной работы циклических зависимостей модулей требуется тщательное планирование.

Файловые модули

Если точное имя файла не найдено, Node.js попытается загрузить требуемый файл с добавленными расширениями: .js, .json, и наконец .node.

Файлы с расширением .js интерпретируются как текстовые файлы JavaScript, а файлы с расширением .json — как текстовые файлы JSON. Файлы с расширением .node интерпретируются как скомпилированные модули плагинов, загружаемые с помощью process.dlopen().

Требуемый модуль, префикс которого '/', является абсолютным путем к файлу. Например, require('/home/marco/foo.js') загрузит файл по пути /home/marco/foo.js.

Требуемый модуль, префикс которого './', является относительным к файлу, вызывающему require(). То есть, circle.js должен находиться в той же директории, что и foo.js , чтобы require('./circle') смог его найти.

Без ведущих '/', './', или '../' для указания файла, модуль должен быть модулем ядра или загружен из папки node_modules.

Если заданный путь не существует, require() выбросит Error с установленным свойством code в значение 'MODULE_NOT_FOUND'.

Папки как модули

Удобно организовывать программы и библиотеки в автономных директориях, а затем предоставлять единственную точку входа в эти директории. Существует три способа передачи папки в require() в качестве аргумента.

Первый — создать файл package.json в корне папки, который определяет модуль main. Пример файла package.json может выглядеть так:

{ "name" : "some-library",
  "main" : "./lib/some-library.js" }

Если этот файл находится в папке по адресу ./some-library, то require('./some-library') попытается загрузить ./some-library/lib/some-library.js.

Это всё, что касается осведомлённости Node.js о файлах package.json.

Если в директории отсутствует файл package.json, или запись "main" отсутствует или не может быть разрешена, то Node.js попытается загрузить файл index.js или index.node из этой директории. Например, если в предыдущем примере не было файла package.json, то require('./some-library') попытается загрузить:

• ./some-library/index.js
• ./some-library/index.node

Если эти попытки завершатся неудачей, Node.js сообщит об отсутствии всего модуля с помощью стандартной ошибки:

Error: Cannot find module 'some-library'

Загрузка из папок node_modules

Если идентификатор модуля, переданный в require(), не является модулем ядра и не начинается с '/', '../', или './', то Node.js начинает с родительской директории текущего модуля, добавляет /node_modules, и пытается загрузить модуль из этого места. Node.js не будет добавлять node_modules к пути, уже заканчивающемуся на node_modules.

Если модуль не будет найден там, он переходит к родительской директории и так далее, пока не достигнет корня файловой системы.

Например, если файл по адресу '/home/ry/projects/foo.js' называется require('bar.js'), то Node.js будет искать его в следующих местах в указанном порядке:

• /home/ry/projects/node_modules/bar.js
• /home/ry/node_modules/bar.js
• /home/node_modules/bar.js
• /node_modules/bar.js

Это позволяет программам локализовать свои зависимости, чтобы они не конфликтовали.

Возможна загрузка определённых файлов или подмодулей, поставляемых с модулем, путём добавления суффикса пути после имени модуля. Например, require('example-module/path/to/file') разрешит path/to/file относительно местоположения example-module . Путь с суффиксом следует тем же семантикам разрешения модулей.

Загрузка из глобальных папок

Если переменная среды NODE_PATH установлена в список путей, разделённых двоеточием, Node.js будет искать модули в этих путях, если они не найдены в другом месте.

В Windows, NODE_PATH разделены точкой с запятой (;) вместо двоеточия.

NODE_PATH изначально была создана для поддержки загрузки модулей из разных путей до определения текущего алгоритма разрешения модулей NODE_PATH.

NODE_PATH всё ещё поддерживается, но сейчас менее необходима, поскольку экосистема Node.js определила соглашение о местоположении зависимых модулей. Иногда развертывания, которые полагаются на NODE_PATH, демонстрируют неожиданное поведение, если люди не знают, что NODE_PATH должна быть установлена. Иногда зависимости модуля меняются, что приводит к загрузке другой версии (или даже другого модуля) при поиске NODE_PATH.

Кроме того, Node.js будет искать в следующем списке GLOBAL_FOLDERS:

• 1: $HOME/.node_modules
• 2: $HOME/.node_libraries
• 3: $PREFIX/lib/node

Где $HOME — домашний каталог пользователя, а $PREFIX — настроенный Node.js node_prefix.

В основном это по историческим причинам.

Настоятельно рекомендуется размещать зависимости в локальной папке node_modules . Это обеспечит более быструю и надёжную загрузку.

Обёртка модуля

Перед выполнением кода модуля Node.js обернёт его функцией-обёрткой, которая выглядит следующим образом:

(function(exports, require, module, __filename, __dirname) {
// Module code actually lives in here
});

Благодаря этому Node.js достигает нескольких целей:

• Переменные верхнего уровня (определённые с помощью var, const или let) остаются ограниченными модулем, а не глобальным объектом.
• Это помогает обеспечить некоторые глобальные переменные, которые на самом деле специфичны для модуля, такие как:
  • Объекты module и exports, которые разработчик может использовать для экспорта значений из модуля.
  • Удобные переменные __filename и __dirname, содержащие абсолютный путь к файлу и директории модуля.

Область видимости модуля

__dirname

• <строка>

Имя каталога текущего модуля. Это то же самое, что и path.dirname() __filename.

Пример: выполнение node example.js из /Users/mjr

console.log(__dirname);
// Prints: /Users/mjr
console.log(path.dirname(__filename));
// Prints: /Users/mjr

__filename

• <строка>

Имя файла текущего модуля. Это абсолютный путь к текущему файлу модуля с разрешенными символическими ссылками.

Для основной программы это не обязательно то же самое, что имя файла, используемое в командной строке.

См. __dirname для имени каталога текущего модуля.

Примеры:

Выполнение node example.js из /Users/mjr

console.log(__filename);
// Prints: /Users/mjr/example.js
console.log(__dirname);
// Prints: /Users/mjr

Предположим два модуля: a и b, где b является зависимостью a, и существует структура каталогов:

• /Users/mjr/app/a.js
• /Users/mjr/app/node_modules/b/b.js

Ссылки на __filename внутри b.js вернут /Users/mjr/app/node_modules/b/b.js, а ссылки на __filename внутри a.js вернут /Users/mjr/app/a.js.

exports

• <Объект>

Ссылка на module.exports, более краткая для написания. Подробности о том, когда использовать exports и когда module.exports, см. в разделе о сокращении exports.

module

• <модуль>

Ссылка на текущий модуль, см. раздел о module объекте. В частности, module.exports используется для определения того, что экспортирует модуль, и что доступно через require().

require(id)

• id <строка> имя или путь модуля
• Возвращает: <любой> содержимое экспортированного модуля

Используется для импорта модулей, JSON, и локальных файлов. Модули можно импортировать из node_modules. Локальные модули и файлы JSON можно импортировать, используя относительный путь (например, ./, ./foo, ./bar/baz, ../foo), который будет разрешен относительно каталога, указанного в __dirname (если определен) или в текущем рабочем каталоге. Относительные пути в стиле POSIX разрешаются независимо от ОС, что означает, что вышеперечисленные примеры будут работать в Windows так же, как и в системах Unix.

// Importing a local module with a path relative to the `__dirname` or current
// working directory. (On Windows, this would resolve to .\path\myLocalModule.)
const myLocalModule = require('./path/myLocalModule');

// Importing a JSON file:
const jsonData = require('./path/filename.json');

// Importing a module from node_modules or Node.js built-in module:
const crypto = require('crypto');

require.cache

• <Объект>

Модули кешируются в этом объекте при их загрузке. Удаление пары ключ-значение из этого объекта приведет к повторной загрузке модуля при следующем require. Это не относится к нативным дополнениям, для которых повторная загрузка приведет к ошибке.

Также возможно добавлять или изменять записи. Этот кэш проверяется перед нативными модулями, и если имя, соответствующее нативному модулю, добавлено в кэш, никакой вызов require больше не получит нативный модуль. Используйте с осторожностью!

require.extensions

• <Объект>

Указывает require как обрабатывать определённые расширения файлов.

Обработка файлов с расширением .sjs как .js:

require.extensions['.sjs'] = require.extensions['.js'];

Устарел. Раньше этот список использовался для загрузки не-JavaScript модулей в Node.js, компилируя их по требованию. Однако на практике существуют лучшие способы сделать это, например, загружать модули через другую программу Node.js или компилировать их в JavaScript заранее.

Избегайте использования require.extensions. Это может привести к скрытым ошибкам, и разрешение расширений замедляется с каждым зарегистрированным расширением.

require.main

• <модуль>

Объект Module представляющий загружаемый при запуске процесса Node.js скрипт входа. См. "Доступ к главному модулю".

В скрипте entry.js:

console.log(require.main);

node entry.js

Module {
  id: '.',
  path: '/absolute/path/to',
  exports: {},
  parent: null,
  filename: '/absolute/path/to/entry.js',
  loaded: false,
  children: [],
  paths:
   [ '/absolute/path/to/node_modules',
     '/absolute/path/node_modules',
     '/absolute/node_modules',
     '/node_modules' ] }

require.resolve(request[, options])

• request <строка> Путь к модулю для разрешения.
• options <Объект>
  • paths <массив строк> Пути для разрешения расположения модуля. Если присутствуют, эти пути используются вместо стандартных путей разрешения, за исключением GLOBAL_FOLDERS вроде $HOME/.node_modules, которые всегда включаются. Каждый из этих путей используется в качестве отправной точки для алгоритма разрешения модуля, то есть иерархия node_modules проверяется из этого расположения.
• Возвращает: <строка>

Использует внутренние механизмы require() для поиска расположения модуля, но вместо загрузки модуля возвращает только разрешенный имя файла.

Если модуль не найден, выбрасывается ошибка MODULE_NOT_FOUND.

require.resolve.paths(request)

• request <строка> Путь модуля, пути поиска которого извлекаются.
• Возвращает: <массив строк> | <null>

Возвращает массив, содержащий пути, проверенные во время разрешения request или null, если строка request ссылается на ядро модуля, например http или fs.

Объект module

• <Объект>

В каждом модуле свободная переменная module — ссылка на объект, представляющий текущий модуль. Для удобства, module.exports также доступен через глобальную переменную exports модуля. module на самом деле не глобален, а локален для каждого модуля.

module.children

• <массив модулей>

Объекты модулей, которые требуются этому модулю в первый раз.

module.exports

• <Объект>

Объект module.exports создаётся системой Module. Иногда это неприемлемо; многие хотят, чтобы их модуль был экземпляром какого-либо класса. Для этого назначьте желаемый объект экспорта module.exports. Назначение желаемого объекта exports просто перепривяжет локальную переменную exports, что, вероятно, не нужно.

Например, предположим, что мы создаём модуль под названием a.js:

const EventEmitter = require('events');

module.exports = new EventEmitter();

// Do some work, and after some time emit
// the 'ready' event from the module itself.
setTimeout(() => {
  module.exports.emit('ready');
}, 1000);

Затем в другом файле мы можем сделать:

const a = require('./a');
a.on('ready', () => {
  console.log('module "a" is ready');
});

Присвоение module.exports должно быть выполнено немедленно. Его нельзя выполнять в каких-либо колбэках. Это не работает:

x.js:

setTimeout(() => {
  module.exports = { a: 'hello' };
}, 0);

y.js:

const x = require('./x');
console.log(x.a);

exports ярлык

Переменная exports доступна в пределах области видимости файла модуля и получает значение module.exports до оценки модуля.

Она позволяет использовать сокращение, чтобы module.exports.f = ... можно было записать более кратко как exports.f = .... Однако следует помнить, что, как и любая переменная, если новому значению присваивается exports, оно больше не привязано к module.exports:

module.exports.hello = true; // Exported from require of module
exports = { hello: false };  // Not exported, only available in the module

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

module.exports = exports = function Constructor() {
  // ... etc.
};

Чтобы проиллюстрировать поведение, представьте себе эту гипотетическую реализацию require(), которая очень похожа на то, что фактически выполняет require():

function require(/* ... */) {
  const module = { exports: {} };
  ((module, exports) => {
    // Module code here. In this example, define a function.
    function someFunc() {}
    exports = someFunc;
    // At this point, exports is no longer a shortcut to module.exports, and
    // this module will still export an empty default object.
    module.exports = someFunc;
    // At this point, the module will now export someFunc, instead of the
    // default object.
  })(module, module.exports);
  return module.exports;
}

module.filename

• <строка>

Полное разрешённое имя файла модуля.

module.id

• <строка>

Идентификатор модуля. Обычно это полное разрешённое имя файла.

module.isPreloading

• Тип: <логическое значение> true если модуль выполняется во время фазы предварительной загрузки Node.js.

module.loaded

• <логическое значение>

Загружен ли модуль или находится в процессе загрузки.

module.parent

• <модуль> | <null> | <undefined>

Модуль, который в первый раз потребовал текущий, или null , если текущий модуль является точкой входа текущего процесса, или undefined , если модуль был загружен чем-то, что не является модулем CommonJS (например, REPL или import).

module.path

• <строка>

Имя каталога модуля. Обычно это то же, что и path.dirname() для module.id.

module.paths

• <массив строк>

Пути поиска модуля.

module.require(id)

• id <строка>
• Возвращает: <любой> содержимое экспортируемого модуля

Метод module.require() предоставляет способ загрузки модуля так, как будто require() был вызван из исходного модуля.

Для этого необходимо получить ссылку на объект module. Поскольку require() возвращает module.exports, а module обычно только доступен в коде конкретного модуля, его необходимо явно экспортировать, чтобы его можно было использовать.

Объект Module

Этот раздел был перемещен в Модули: module основной модуль.

• module.builtinModules
• module.createRequire(filename)
• module.createRequireFromPath(filename)
• module.syncBuiltinESMExports()

Поддержка source map v3

Этот раздел был перемещен в Модули: module основной модуль.

• module.findSourceMap(path[, error])
• Класс: module.SourceMap
  • new SourceMap(payload)
  • sourceMap.payload
  • sourceMap.findEntry(lineNumber, columnNumber)