API командной строки

Node.js поставляется с различными параметрами CLI. Эти параметры предоставляют встроенные средства отладки, несколько способов запуска скриптов и другие полезные параметры среды выполнения.

Чтобы просмотреть эту документацию в виде справочной страницы в терминале, выполните man node.

Краткое описание

node [options] [V8 options] [<program-entry-point> | -e "script" | -] [--] [arguments]

node inspect [<program-entry-point> | -e "script" | <host>:<port>] …

node --v8-options

Запустите без аргументов, чтобы открыть REPL.

Дополнительные сведения о node inspect см. в документации по отладчику.

Точка входа программы

Точка входа программы — это строка, похожая на спецификатор. Если строка не является абсолютным путём, она разрешается как относительный путь от текущего рабочего каталога. Затем эта строка точки входа разрешается так же, как если бы она была запрошена с помощью require() из текущего рабочего каталога. Если соответствующий файл не найден, возникает ошибка.

По умолчанию разрешённый путь также загружается так, как если бы он был запрошен с помощью require(), если не выполняется одно из приведённых ниже условий — в этом случае он загружается так, как если бы был запрошен с помощью import():

• Программа запущена с флагом командной строки, который принудительно загружает точку входа с помощью загрузчика модулей ECMAScript, например --import.
• Файл имеет расширение .mjs, .mts или .wasm.
• Файл не имеет расширения .cjs, а ближайший родительский файл package.json содержит поле верхнего уровня "type" со значением "module".

Подробнее см. в разделе разрешение и загрузка модулей.

Параметры

Во всех параметрах, включая параметры V8, слова можно разделять дефисами (-) или подчёркиваниями (_). Например, --pending-deprecation эквивалентно --pending_deprecation.

Если параметр, принимающий одно значение (например, --max-http-header-size), передан несколько раз, используется последнее переданное значение. Параметры командной строки имеют приоритет над параметрами, переданными через переменную окружения NODE_OPTIONS.

-

Псевдоним для stdin. Аналогично использованию - в других утилитах командной строки: скрипт считывается из stdin, а остальные параметры передаются этому скрипту.

--

Указывает конец параметров Node.js. Остальные аргументы передаются скрипту. Если до этого не было указано имя файла скрипта или скрипт для eval/print, следующий аргумент используется как имя файла скрипта.

--abort-on-uncaught-exception

Прерывание вместо выхода приводит к созданию файла core для посмертного анализа с помощью отладчика (например, lldb, gdb и mdb).

Если передан этот флаг, поведение всё ещё можно настроить так, чтобы прерывание не происходило, с помощью process.setUncaughtExceptionCaptureCallback() (а также с помощью модуля node:domain, использующего этот механизм).

--allow-addons

При использовании модели разрешений процесс по умолчанию не сможет использовать нативные аддоны. Попытки сделать это вызовут исключение ERR_DLOPEN_DISABLED, если при запуске Node.js пользователь явно не передаст флаг --allow-addons.

Пример:

// Attempt to require an native addon
require('nodejs-addon-example');
cjscopy

$ node --permission --allow-fs-read=* index.js
node:internal/modules/cjs/loader:1319
  return process.dlopen(module, path.toNamespacedPath(filename));
                 ^

Error: Cannot load native addon because loading addons is disabled.
    at Module._extensions..node (node:internal/modules/cjs/loader:1319:18)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12)
    at Module.require (node:internal/modules/cjs/loader:1115:19)
    at require (node:internal/modules/helpers:130:18)
    at Object.<anonymous> (/home/index.js:1:15)
    at Module._compile (node:internal/modules/cjs/loader:1233:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)
    at Module.load (node:internal/modules/cjs/loader:1091:32)
    at Module._load (node:internal/modules/cjs/loader:938:12) {
  code: 'ERR_DLOPEN_DISABLED'
}
consolecopy

--allow-child-process

При использовании модели разрешений процесс по умолчанию не сможет создавать дочерние процессы. Попытки сделать это вызовут исключение ERR_ACCESS_DENIED, если при запуске Node.js пользователь явно не передаст флаг --allow-child-process.

Пример:

const childProcess = require('node:child_process');
// Attempt to bypass the permission
childProcess.spawn('node', ['-e', 'require("fs").writeFileSync("/new-file", "example")']);
jscopy

$ node --permission --allow-fs-read=* index.js
node:internal/child_process:388
  const err = this._handle.spawn(options);
                           ^
Error: Access to this API has been restricted
    at ChildProcess.spawn (node:internal/child_process:388:28)
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'ChildProcess'
}
consolecopy

API child_process.fork() наследует аргументы запуска родительского процесса. Это означает, что если Node.js запущен с включённой моделью разрешений и установлен флаг --allow-child-process, любой дочерний процесс, созданный с помощью child_process.fork(), автоматически получит все соответствующие флаги модели разрешений.

Это поведение также применяется к child_process.spawn(), но в этом случае флаги передаются через переменную окружения NODE_OPTIONS, а не напрямую в аргументах процесса.

--allow-ffi

При использовании модели разрешений процесс по умолчанию не сможет использовать API FFI. Попытки использовать API FFI вызовут исключение ERR_ACCESS_DENIED, если при запуске Node.js пользователь явно не передаст флаг --allow-ffi. Для модуля node:ffi также требуется флаг --experimental-ffi; он доступен только в сборках с поддержкой FFI.

Пример:

const { DynamicLibrary } = require('node:ffi');
const lib = new DynamicLibrary('mylib.so');
jscopy

$ node --permission --experimental-ffi index.js
Error: Access to this API has been restricted. Use --allow-ffi to manage permissions.
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'FFI'
}
consolecopy

--allow-fs-read

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

Допустимые аргументы флага --allow-fs-read:

• * — разрешить все операции FileSystemRead.
• Несколько путей можно разрешить, используя несколько флагов --allow-fs-read. Пример: --allow-fs-read=/folder1/ --allow-fs-read=/folder1/

Примеры приведены в документации по разрешениям файловой системы.

Модуль инициализации и пользовательские модули --require имеют неявное разрешение на чтение.

$ node --permission -r custom-require.js -r custom-require-2.js index.js
consolecopy

• custom-require.js, custom-require-2.js и index.js по умолчанию будут включены в список разрешённых для чтения.

process.permission.has('fs.read', 'index.js'); // true
process.permission.has('fs.read', 'custom-require.js'); // true
process.permission.has('fs.read', 'custom-require-2.js'); // true
jscopy

--allow-fs-write

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

Допустимые аргументы флага --allow-fs-write:

• * — разрешить все операции FileSystemWrite.
• Несколько путей можно разрешить, используя несколько флагов --allow-fs-write. Пример: --allow-fs-write=/folder1/ --allow-fs-write=/folder1/

Пути, разделённые запятой (,), больше не разрешены. При передаче одного флага с запятой будет выведено предупреждение.

Примеры приведены в документации по разрешениям файловой системы.

--allow-inspector

При использовании модели разрешений процесс не сможет подключаться через протокол инспектора.

Попытки сделать это вызовут исключение ERR_ACCESS_DENIED, если при запуске Node.js пользователь явно не передаст флаг --allow-inspector.

Пример:

const { Session } = require('node:inspector/promises');

const session = new Session();
session.connect();
jscopy

$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-inspector to manage permissions.
  code: 'ERR_ACCESS_DENIED',
}
consolecopy

--allow-net

При использовании модели разрешений процесс по умолчанию не сможет обращаться к сети. Попытки сделать это вызовут исключение ERR_ACCESS_DENIED, если при запуске Node.js пользователь явно не передаст флаг --allow-net.

Пример:

const http = require('node:http');
// Attempt to bypass the permission
const req = http.get('http://example.com', () => {});

req.on('error', (err) => {
  console.log('err', err);
});
jscopy

$ node --permission index.js
Error: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-net to manage permissions.
  code: 'ERR_ACCESS_DENIED',
}
consolecopy

--allow-wasi

При использовании модели разрешений процесс по умолчанию не сможет создавать экземпляры WASI. По соображениям безопасности вызов вызовет исключение ERR_ACCESS_DENIED, если пользователь явно не передаст флаг --allow-wasi основному процессу Node.js.

Пример:

const { WASI } = require('node:wasi');
// Attempt to bypass the permission
new WASI({
  version: 'preview1',
  // Attempt to mount the whole filesystem
  preopens: {
    '/': '/',
  },
});
jscopy

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:30:49 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WASI',
}
consolecopy

--allow-worker

При использовании модели разрешений процесс по умолчанию не сможет создавать рабочие потоки. По соображениям безопасности вызов вызовет исключение ERR_ACCESS_DENIED, если пользователь явно не передаст флаг --allow-worker основному процессу Node.js.

Пример:

const { Worker } = require('node:worker_threads');
// Attempt to bypass the permission
new Worker(__filename);
jscopy

$ node --permission --allow-fs-read=* index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WorkerThreads'
}
consolecopy

--build-sea=config

Создаёт одиночное исполняемое приложение на основе файла конфигурации JSON. Аргументом должен быть путь к файлу конфигурации. Если путь не является абсолютным, он разрешается относительно текущего рабочего каталога.

Сведения о полях конфигурации, особенностях работы на разных платформах и API ресурсов см. в документации по одиночным исполняемым приложениям.

--build-snapshot

При завершении процесса создаёт и сохраняет на диск блоб снимка, который впоследствии можно загрузить с помощью --snapshot-blob.

Если при создании снимка --snapshot-blob не задан, сгенерированный блоб по умолчанию будет записан в snapshot.blob в текущем рабочем каталоге. В противном случае он будет записан по пути, указанному в --snapshot-blob.

$ echo "globalThis.foo = 'I am from the snapshot'" > snapshot.js

# Run snapshot.js to initialize the application and snapshot the
# state of it into snapshot.blob.
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js

$ echo "console.log(globalThis.foo)" > index.js

# Load the generated snapshot and start the application from index.js.
$ node --snapshot-blob snapshot.blob index.js
I am from the snapshot
consolecopy

API v8.startupSnapshot позволяет указать точку входа во время создания снимка, благодаря чему при десериализации не потребуется дополнительный скрипт запуска:

$ echo "require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))" > snapshot.js
$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js
$ node --snapshot-blob snapshot.blob
I am from the snapshot
consolecopy

Дополнительные сведения см. в документации по API v8.startupSnapshot.

В настоящее время снимок поддерживает загрузку только одной точки входа в процессе его создания. Она может загружать встроенные модули, но не дополнительные пользовательские модули. Перед созданием снимка пользователи могут объединить свои приложения в один скрипт с помощью выбранного сборщика.

Поскольку обеспечить сериализуемость всех встроенных модулей сложно, а их число со временем растёт, только часть встроенных модулей тщательно проверена на возможность сериализации в процессе создания снимка. Набор основных тестов Node.js проверяет возможность создания снимков для нескольких достаточно сложных приложений. Поддерживаемыми считаются встроенные модули, включённые во встроенный снимок Node.js. Если при создании снимка обнаруживается встроенный модуль, который нельзя сериализовать, процесс создания снимка может аварийно завершиться. В этом случае обычно можно отложить загрузку такого модуля до времени выполнения с помощью v8.startupSnapshot.setDeserializeMainFunction() или v8.startupSnapshot.addDeserializeCallback(). Если во время создания снимка требуется сериализовать дополнительный модуль, создайте запрос в трекере проблем Node.js и добавьте ссылку на него в задачу отслеживания пользовательских снимков.

--build-snapshot-config

Указывает путь к файлу конфигурации JSON, который задаёт поведение при создании снимка.

В настоящее время поддерживаются следующие параметры:

• builder <string> Обязательный. Задаёт имя скрипта, выполняемого перед созданием снимка, как если бы флаг --build-snapshot был передан с builder в качестве имени основного скрипта.
• withoutCodeCache <boolean> Необязательный. Включение кэша кода сокращает время компиляции функций, включённых в снимок, но увеличивает его размер и может снизить переносимость снимка.

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

-c, --check

Проверяет синтаксис скрипта, не выполняя его.

--completion-bash

Выводит подключаемый скрипт автодополнения bash для Node.js.

node --completion-bash > node_bash_completion
source node_bash_completion
bashcopy

-C condition, --conditions=condition

Задаёт пользовательские условия разрешения для условного экспорта.

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

Стандартные условия Node.js "node", "default", "import" и "require" всегда применяются согласно заданным правилам.

Например, чтобы запустить модуль с разрешением "development":

node -C development app.js
bashcopy

--cpu-prof

Запускает профилировщик ЦП V8 при запуске и записывает профиль ЦП на диск перед завершением работы.

Если --cpu-prof-dir не указано, созданный профиль помещается в текущий рабочий каталог.

Если --cpu-prof-name не указано, созданный профиль называется CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile.

$ node --cpu-prof index.js
$ ls *.cpuprofile
CPU.20190409.202950.15293.0.0.cpuprofile
consolecopy

Если задано --cpu-prof-name, указанное значение используется как шаблон имени файла. Поддерживается следующий заполнитель, который заменяется во время выполнения:

• ${pid} — идентификатор текущего процесса

$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js
$ ls *.cpuprofile
CPU.15293.cpuprofile
consolecopy

--cpu-prof-dir

Задаёт каталог для размещения профилей ЦП, создаваемых с помощью --cpu-prof.

Значение по умолчанию задаётся параметром командной строки --diagnostic-dir.

--cpu-prof-interval

Задаёт интервал выборки в микросекундах для профилей ЦП, создаваемых с помощью --cpu-prof. Значение по умолчанию — 1000 микросекунд.

--cpu-prof-name

Задаёт имя файла профиля ЦП, создаваемого с помощью --cpu-prof.

--diagnostic-dir=directory

Задаёт каталог для записи всех диагностических выходных файлов. По умолчанию используется текущий рабочий каталог.

Влияет на каталог вывода по умолчанию для:

• --cpu-prof-dir
• --heap-prof-dir
• --redirect-warnings

--disable-proto=mode

Отключает свойство Object.prototype.__proto__. Если mode имеет значение delete, свойство полностью удаляется. Если mode имеет значение throw, обращение к свойству вызывает исключение с кодом ERR_PROTO_ACCESS.

--disable-sigusr1

Отключает возможность начать сеанс отладки, отправив процессу сигнал SIGUSR1.

--disable-warning=code-or-type

Отключает определённые предупреждения процесса по code или type.

Предупреждения, генерируемые с помощью process.emitWarning(), могут содержать code и type. Этот параметр подавляет предупреждения, соответствующие code или type.

Список предупреждений об устаревании.

Типы предупреждений ядра Node.js: DeprecationWarning и ExperimentalWarning

Например, следующий скрипт не будет выводить DEP0025 require('node:sys') при запуске с node --disable-warning=DEP0025:

import sys from 'node:sys';

const sys = require('node:sys');

Например, следующий скрипт выведет DEP0025 require('node:sys'), но не будет выводить предупреждения экспериментальных функций (например, ExperimentalWarning: vm.measureMemory — экспериментальная функция в версиях <=v21) при запуске с node --disable-warning=ExperimentalWarning:

import sys from 'node:sys';
import vm from 'node:vm';

vm.measureMemory();

const sys = require('node:sys');
const vm = require('node:vm');

vm.measureMemory();

--disable-wasm-trap-handler

На 64-разрядных платформах Node.js включает в V8 проверку границ WebAssembly на основе обработчика ловушек, что значительно повышает производительность WebAssembly за счёт устранения необходимости во встроенных проверках границ. Для этой оптимизации требуется выделять большую область виртуальной памяти для каждого экземпляра памяти WebAssembly (обычно 8 ГБ для 32-разрядной памяти WebAssembly и 16 ГБ для 64-разрядной памяти WebAssembly), чтобы перехватывать обращения за пределы границ. На большинстве 64-разрядных платформ адресное пространство виртуальной памяти обычно достаточно велико (около 128 ТБ) для типичного использования WebAssembly, однако при наличии на компьютере ручных ограничений виртуальной памяти (например, с помощью ulimit -v) выделение памяти WebAssembly с большей вероятностью завершится ошибкой WebAssembly.Memory(): could not allocate memory.

При запуске Node.js автоматически проверяет, достаточно ли доступно виртуальной памяти для выделения хотя бы одной области памяти; если нет, оптимизация с обработчиком ловушек автоматически отключается, чтобы WebAssembly могла продолжить работу со встроенными проверками границ (с меньшей производительностью). Но если приложению требуется создать много экземпляров памяти WebAssembly, а на компьютере по-прежнему установлен относительно высокий предел виртуальной памяти, выделение экземпляров памяти WebAssembly всё равно может завершаться неудачей раньше ожидаемого из-за увеличенного потребления виртуальной памяти.

--disable-wasm-trap-handler полностью отключает эту оптимизацию, поэтому экземпляры памяти WebAssembly всегда используют встроенные проверки границ вместо резервирования больших областей виртуальной памяти. Это позволяет создавать больше экземпляров, если доступное процессу Node.js адресное пространство виртуальной памяти ограничено.

--disallow-code-generation-from-strings

Заставляет встроенные языковые средства, такие как eval и new Function, генерирующие код из строк, вместо этого вызывать исключение. Это не влияет на модуль Node.js node:vm.

--dns-result-order=order

Задаёт значение по умолчанию для order в dns.lookup() и dnsPromises.lookup(). Допустимые значения:

• ipv4first: задаёт значение по умолчанию для order равным ipv4first.
• ipv6first: задаёт значение по умолчанию для order равным ipv6first.
• verbatim: задаёт значение по умолчанию для order равным verbatim.

По умолчанию используется verbatim, а dns.setDefaultResultOrder() имеет более высокий приоритет, чем --dns-result-order.

--enable-fips

Включает при запуске криптографию, соответствующую требованиям FIPS. (Для этого Node.js должен быть собран с OpenSSL, совместимым с FIPS.)

--enable-source-maps

Включает поддержку карт исходного кода для трассировок стека.

При использовании транспилятора, например TypeScript, трассировки стека, создаваемые приложением, ссылаются на транспилированный код, а не на исходные позиции. --enable-source-maps включает кэширование карт исходного кода и по возможности указывает в трассировках стека позиции в исходном файле.

Переопределение Error.prepareStackTrace может помешать --enable-source-maps изменить трассировку стека. Чтобы изменить трассировку стека с помощью карт исходного кода, вызовите исходную Error.prepareStackTrace в переопределяющей функции и верните результат её выполнения.

const originalPrepareStackTrace = Error.prepareStackTrace;
Error.prepareStackTrace = (error, trace) => {
  // Modify error and trace and format stack trace with
  // original Error.prepareStackTrace.
  return originalPrepareStackTrace(error, trace);
};
jscopy

Обратите внимание: включение карт исходного кода может увеличить задержку приложения при обращении к Error.stack. Если приложение часто обращается к Error.stack, учитывайте влияние --enable-source-maps на производительность.

--entry-url

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

Применяются правила разрешения модулей ECMAScript.

Любой параметр запроса или хеш в URL будет доступен через import.meta.url.

node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'
node --entry-url 'file.ts?query#hash'
node --entry-url 'data:text/javascript,console.log("Hello")'
bashcopy

--env-file-if-exists=file

Работает так же, как --env-file, но не вызывает ошибку, если файл не существует.

--env-file=file

Загружает переменные среды из файла относительно текущего каталога, делая их доступными приложениям в process.env. Разбираются и применяются переменные среды, которые настраивают Node.js, например NODE_OPTIONS. Если одна и та же переменная задана и в среде, и в файле, приоритет имеет значение из среды.

Можно передать несколько аргументов --env-file. Последующие файлы переопределяют существующие переменные, заданные в предыдущих файлах.

Если файл не существует, возникает ошибка.

node --env-file=.env --env-file=.development.env index.js
bashcopy

Файл должен содержать по одной строке на каждую пару «имя переменной среды — значение», разделённую =:

PORT=3000
textcopy

Любой текст после # считается комментарием:

# This is a comment
PORT=3000 # This is also a comment
textcopy

Значения могут начинаться и заканчиваться следующими кавычками: `, " или '. Они удаляются из значений.

USERNAME="nodejs" # will result in `nodejs` as the value.
textcopy

Поддерживаются многострочные значения:

MULTI_LINE="THIS IS
A MULTILINE"
# will result in `THIS IS\nA MULTILINE` as the value.
textcopy

Ключевое слово Export перед ключом игнорируется:

export USERNAME="nodejs" # will result in `nodejs` as the value.
textcopy

Чтобы загрузить переменные среды из файла, который может отсутствовать, используйте флаг --env-file-if-exists.

-e, --eval "script"

Выполняет следующий аргумент как JavaScript. Модули, предопределённые в REPL, также можно использовать в script.

Если script начинается с -, передайте его с помощью = (например, node --print --eval=-42), чтобы он был разобран как значение --eval.

В Windows использование cmd.exe с одинарными кавычками работает некорректно, поскольку для заключения в кавычки распознаются только двойные ". В Powershell или Git bash можно использовать как ', так и ".

Можно запускать код со встроенными типами, если не указан флаг --no-strip-types.

--experimental-addon-modules

Включает экспериментальную поддержку импорта дополнений .node.

--experimental-config-file=path, --experimental-config-file

Если этот параметр задан, Node.js будет искать файл конфигурации по указанному пути. Если путь не указан, Node.js будет искать файл node.config.json в текущем рабочем каталоге. Чтобы указать пользовательский путь, используйте форму --experimental-config-file=path. Форма --experimental-config-file path с разделением пробелами не поддерживается. Псевдоним --experimental-default-config-file эквивалентен --experimental-config-file без аргумента. Node.js прочитает файл конфигурации и применит настройки. Файл конфигурации должен быть файлом JSON следующей структуры. vX.Y.Z в $schema необходимо заменить на версию используемого Node.js или на latest-vX.x для последней версии этой основной линейки выпусков.

{
  "$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
  "nodeOptions": {
    "import": [
      "amaro/strip"
    ],
    "watch-path": "src",
    "watch-preserve-output": true
  },
  "test": {
    "test-isolation": "process"
  },
  "watch": {
    "watch-preserve-output": true
  }
}
jsoncopy

Файл конфигурации поддерживает параметры, относящиеся к определённым пространствам имён:

• Поле nodeOptions содержит флаги CLI, допустимые в NODE_OPTIONS.

• Поля пространств имён, такие как test, watch и permission, содержат параметры конфигурации соответствующих подсистем.

Файл конфигурации может быть предназначен для определённой основной версии Node.js с помощью nodeVersion:

{
  "nodeVersion": 25,
  "nodeOptions": {
    "watch-path": "src"
  }
}
jsoncopy

Чтобы хранить конфигурации для нескольких версий в одном файле, используйте массив configs. Node.js использует первую запись, у которой nodeVersion соответствует текущей основной версии Node.js:

{
  "$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
  "configs": [
    {
      "nodeVersion": 25,
      "config": {
        "$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",
        "nodeOptions": {
          "watch-path": "src"
        }
      }
    }
  ]
}
jsoncopy

При использовании configs на верхнем уровне могут находиться только $schema и configs. Каждый элемент configs должен задавать целое число nodeVersion и объект config. Для единственной конфигурации верхнего уровня nodeVersion не требуется, но если он задан, то должен соответствовать текущей основной версии Node.js.

Если в файле конфигурации присутствует пространство имён, Node.js автоматически включает соответствующий флаг (например, --test, --watch, --permission). Это позволяет настраивать параметры конкретной подсистемы, не указывая флаг явно в командной строке.

Например:

{
  "test": {
    "test-isolation": "process"
  }
}
jsoncopy

эквивалентно:

node --test --test-isolation=process
bashcopy

Чтобы отключить автоматическое включение флага и при этом использовать параметры пространства имён, можно явно задать для флага значение false в пространстве имён:

{
  "test": {
    "test": false,
    "test-isolation": "process"
  }
}
jsoncopy

Флаги без действий не поддерживаются. В настоящее время поддерживаются не все флаги V8.

Для проверки файла конфигурации можно использовать официальную JSON-схему, которая может различаться в зависимости от версии Node.js. Каждому ключу в файле конфигурации соответствует флаг, передаваемый как аргумент командной строки. Значение ключа — это значение, которое было бы передано флагу.

Например, приведённый выше файл конфигурации эквивалентен следующим аргументам командной строки:

node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process
bashcopy

Приоритет параметров конфигурации следующий:

1. NODE_OPTIONS и параметры командной строки
2. NODE_OPTIONS из Dotenv
3. Файл конфигурации

Значения в файле конфигурации не переопределяют значения переменных среды, параметры командной строки или значения из файла NODE_OPTIONS, разобранного флагом --env-file.

Ключи не должны повторяться в одном или разных пространствах имён.

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

Node.js не очищает и не проверяет конфигурацию, предоставленную пользователем, поэтому НИКОГДА не используйте ненадёжные файлы конфигурации.

--experimental-default-config-file

Этот флаг является псевдонимом --experimental-config-file без аргумента. Если он задан, Node.js найдёт файл node.config.json в текущем рабочем каталоге и загрузит его как файл конфигурации.

--experimental-eventsource

Включает доступность веб-API EventSource в глобальной области видимости.

--experimental-ffi

Включает экспериментальный модуль node:ffi.

Этот флаг доступен только в сборках с поддержкой FFI.

--experimental-import-meta-resolve

Включает экспериментальную поддержку родительского URL import.meta.resolve(), позволяющую передавать второй аргумент parentURL для контекстного разрешения.

Ранее этот флаг управлял всей функциональностью import.meta.resolve.

--experimental-inspector-network-resource

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

--experimental-loader=module

Использование этого флага не рекомендуется; он может быть удалён в будущей версии Node.js. Вместо него используйте --import вместе с register().

Указывает module, содержащий экспортируемые асинхронные хуки настройки модулей. module может быть любой строкой, допустимой в качестве import-спецификатора.

При использовании этой функции с моделью разрешений требуется --allow-worker.

--experimental-network-inspection

Включает экспериментальную поддержку анализа сети с помощью Chrome DevTools.

--experimental-print-required-tla

Если в ES-модуле, который был require(), есть await верхнего уровня, этот флаг позволяет Node.js выполнить модуль, попытаться найти операторы await верхнего уровня и вывести их расположение, чтобы помочь пользователям обнаружить их.

--experimental-quic

Включает экспериментальную поддержку протокола QUIC.

--experimental-sea-config

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

--experimental-shadow-realm

Используйте этот флаг, чтобы включить поддержку ShadowRealm.

--experimental-storage-inspection

Включает экспериментальную поддержку анализа хранилища

--experimental-stream-iter

Включает экспериментальный модуль node:stream/iter.

--experimental-test-coverage

При использовании вместе с модулем node:test отчёт о покрытии кода формируется как часть вывода средства запуска тестов. Если тесты не запускаются, отчёт о покрытии не формируется. Подробности см. в документации о сборе данных о покрытии кода тестами.

--experimental-test-module-mocks

Включает имитацию модулей в средстве запуска тестов.

При использовании этой функции с моделью разрешений требуется --allow-worker.

--experimental-test-tag-filter=<tag>

Запускает только тесты, набор тегов которых содержит <tag>. Теги задаются параметром tags для test(), it(), suite() или describe(); теги наследуются от наборов вложенными тестами путём объединения. Фильтрация не учитывает регистр.

Флаг можно указать несколько раз; для запуска тесты должны содержать все значения фильтра. Подробные сведения о задании и наследовании тегов см. в разделе Теги тестов.

--experimental-vm-modules

Включает экспериментальную поддержку ES-модулей в модуле node:vm.

--experimental-wasi-unstable-preview1

Включает экспериментальную поддержку WebAssembly System Interface (WASI).

--experimental-worker-inspection

Включает экспериментальную поддержку анализа рабочих потоков с помощью Chrome DevTools.

--expose-gc

Этот флаг открывает расширение gc из V8.

if (globalThis.gc) {
  globalThis.gc();
}
jscopy

--force-context-aware

Отключает загрузку нативных дополнений, которые не являются контекстно-зависимыми.

--force-fips

Принудительно включает криптографию, соответствующую FIPS, при запуске. (Не может быть отключена из кода скрипта.) (Требования те же, что и для --enable-fips.)

--force-node-api-uncaught-exceptions-policy

Гарантирует вызов события uncaughtException для асинхронных обратных вызовов Node-API.

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

--frozen-intrinsics

Включает экспериментальные замороженные встроенные объекты, такие как Array и Object.

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

Чтобы разрешить добавление полифилов, --require и --import выполняются до замораживания встроенных объектов.

--heap-prof

Запускает профилировщик кучи V8 при запуске и записывает профиль кучи на диск перед завершением работы.

Если --heap-prof-dir не указан, созданный профиль сохраняется в текущем рабочем каталоге.

Если --heap-prof-name не указан, созданный профиль получает имя Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile.

$ node --heap-prof index.js
$ ls *.heapprofile
Heap.20190409.202950.15293.0.001.heapprofile
consolecopy

--heap-prof-dir

Указывает каталог, в который будут помещаться профили кучи, создаваемые с помощью --heap-prof.

Значение по умолчанию задаётся параметром командной строки --diagnostic-dir.

--heap-prof-interval

Задаёт средний интервал выборки в байтах для профилей кучи, создаваемых с помощью --heap-prof. Значение по умолчанию — 512 * 1024 байта.

--heap-prof-name

Указывает имя файла профиля кучи, создаваемого с помощью --heap-prof.

--heapsnapshot-near-heap-limit=max_count

Записывает снимок кучи V8 на диск, когда использование кучи V8 приближается к её пределу. count должно быть неотрицательным целым числом (в этом случае Node.js запишет на диск не более max_count снимков).

При создании снимков может запускаться сборка мусора, уменьшая использование кучи. Поэтому до того, как у экземпляра Node.js окончательно закончится память, на диск может быть записано несколько снимков. Эти снимки кучи можно сравнить, чтобы определить, какие объекты выделяются между последовательными снимками. Не гарантируется, что Node.js запишет на диск ровно max_count снимков, но он постарается создать хотя бы один и не более max_count снимков до того, как у экземпляра Node.js закончится память, если max_count больше 0.

Создание снимков V8 требует времени и памяти (как памяти, управляемой кучей V8, так и нативной памяти за её пределами). Чем больше куча, тем больше ресурсов требуется. Node.js скорректирует размер кучи V8, чтобы учесть дополнительные накладные расходы памяти, и постарается не израсходовать всю память, доступную процессу. Если процесс использует больше памяти, чем система считает допустимым, система может внезапно завершить его работу — это зависит от конфигурации системы.

$ node --max-old-space-size=100 --heapsnapshot-near-heap-limit=3 index.js
Wrote snapshot to Heap.20200430.100036.49580.0.001.heapsnapshot
Wrote snapshot to Heap.20200430.100037.49580.0.002.heapsnapshot
Wrote snapshot to Heap.20200430.100038.49580.0.003.heapsnapshot

<--- Last few GCs --->

[49580:0x110000000]     4826 ms: Mark-sweep 130.6 (147.8) -> 130.5 (147.8) MB, 27.4 / 0.0 ms  (average mu = 0.126, current mu = 0.034) allocation failure scavenge might not succeed
[49580:0x110000000]     4845 ms: Mark-sweep 130.6 (147.8) -> 130.6 (147.8) MB, 18.8 / 0.0 ms  (average mu = 0.088, current mu = 0.031) allocation failure scavenge might not succeed


<--- JS stacktrace --->

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
....
consolecopy

--heapsnapshot-signal=signal

Включает обработчик сигнала, который заставляет процесс Node.js записать дамп кучи при получении указанного сигнала. signal должно быть допустимым именем сигнала. По умолчанию отключено.

$ node --heapsnapshot-signal=SIGUSR2 index.js &
$ ps aux
USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
node         1  5.5  6.1 787252 247004 ?       Ssl  16:43   0:02 node --heapsnapshot-signal=SIGUSR2 index.js
$ kill -USR2 1
$ ls
Heap.20190718.133405.15554.0.001.heapsnapshot
consolecopy

-h, --help

Выводит параметры командной строки node. Вывод этого параметра менее подробный, чем данный документ.

--icu-data-dir=file

Указывает путь загрузки данных ICU. (Переопределяет NODE_ICU_DATA.)

--import=module

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

Используются правила разрешения модулей ECMAScript. Используйте --require для загрузки модуля CommonJS. Модули, предварительно загруженные с помощью --require, выполняются перед модулями, предварительно загруженными с помощью --import.

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

--input-type=type

Этот параметр задаёт, как Node.js должен интерпретировать ввод --eval или STDIN: как CommonJS или как ES-модуль. Допустимые значения: "commonjs", "module", "module-typescript" и "commonjs-typescript". Значения "-typescript" недоступны с флагом --no-strip-types. По умолчанию значение не задано; если передан --no-experimental-detect-module, используется "commonjs".

Если --input-type не задан, Node.js попытается определить синтаксис, выполнив следующие действия:

1. Выполнить ввод как CommonJS.
2. Если шаг 1 завершился с ошибкой, выполнить ввод как ES-модуль.
3. Если шаг 2 завершился с SyntaxError, удалить типы.
4. Если шаг 3 завершился с кодом ошибки ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX или ERR_INVALID_TYPESCRIPT_SYNTAX, вызвать ошибку шага 2, включив сообщение об ошибке TypeScript; в противном случае выполнить ввод как CommonJS.
5. Если шаг 4 завершился с ошибкой, выполнить ввод как ES-модуль.

Чтобы избежать задержки из-за нескольких проходов определения синтаксиса, можно использовать флаг --input-type=type, чтобы указать, как следует интерпретировать ввод --eval.

REPL не поддерживает этот параметр. Использование --input-type=module с --print приведёт к ошибке, поскольку --print не поддерживает синтаксис ES-модулей.

--insecure-http-parser

Включает режимы снисходительной обработки в анализаторе HTTP. Это может обеспечить совместимость с реализациями HTTP, не соответствующими стандартам.

В этом режиме анализатор принимает следующее:

• Недопустимые значения заголовков HTTP.
• Недопустимые версии HTTP.
• Сообщения, содержащие одновременно заголовки Transfer-Encoding и Content-Length.
• Дополнительные данные после сообщения, если присутствует Connection: close.
• Дополнительные кодировки передачи после указания chunked.
• Использование \n в качестве разделителя токенов вместо \r\n.
• Отсутствие \r\n после блока.
• Наличие пробелов после размера блока и перед \r\n.

Все перечисленные выше возможности подвергают приложение риску атак с контрабандой запросов или отравлением. Не используйте этот параметр.

--inspect-brk[=[host:]port]

Активирует инспектор на host:port и останавливает выполнение в начале пользовательского скрипта. Значение host:port по умолчанию — 127.0.0.1:9229. Если указан порт 0, будет использоваться случайный доступный порт.

Дополнительные сведения об отладчике Node.js см. в разделе Интеграция V8 Inspector с Node.js.

Предупреждение безопасности ниже относится к использованию параметра host.

--inspect-port=[host:]port

Задаёт host:port, который будет использоваться при активации инспектора. Полезно при активации инспектора отправкой сигнала SIGUSR1. Исключение — случай, когда передан --disable-sigusr1.

По умолчанию в качестве узла используется 127.0.0.1. Если указан порт 0, будет использоваться случайный доступный порт.

Предупреждение безопасности ниже относится к использованию параметра host.

--inspect-publish-uid=stderr,http

Задаёт способы публикации URL веб-сокета инспектора.

По умолчанию URL веб-сокета инспектора доступен в stderr и в конечной точке /json/list на http://host:port/json/list.

--inspect-wait[=[host:]port]

Активирует инспектор на host:port и ожидает подключения отладчика. Значение host:port по умолчанию — 127.0.0.1:9229. Если указан порт 0, будет использоваться случайный доступный порт.

Дополнительные сведения об отладчике Node.js см. в разделе Интеграция V8 Inspector с Node.js.

Предупреждение безопасности ниже относится к использованию параметра host.

--inspect[=[host:]port]

Активирует инспектор на host:port. Значение по умолчанию — 127.0.0.1:9229. Если указан порт 0, будет использоваться случайный доступный порт.

Интеграция V8 Inspector позволяет таким инструментам, как Chrome DevTools и IDE, отлаживать экземпляры Node.js и профилировать их. Инструменты подключаются к экземплярам Node.js через порт TCP и обмениваются данными с помощью протокола Chrome DevTools. Дополнительные сведения об отладчике Node.js см. в разделе Интеграция V8 Inspector с Node.js.

Предупреждение: привязка инспектора к общедоступной комбинации IP-адреса и порта небезопасна

Привязка инспектора к общедоступному IP-адресу (включая 0.0.0.0) с открытым портом небезопасна, поскольку позволяет внешним узлам подключаться к инспектору и выполнять атаку с удалённым выполнением кода.

Если указан узел, убедитесь, что выполняется одно из следующих условий:

• Узел недоступен из общедоступных сетей.
• Брандмауэр блокирует нежелательные подключения к порту.

В частности, --inspect=0.0.0.0 небезопасен, если порт (по умолчанию 9229) не защищён брандмауэром.

Дополнительные сведения см. в разделе последствия отладки для безопасности.

-i, --interactive

Открывает REPL, даже если stdin не является терминалом.

--jitless

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

--localstorage-file=file

Файл, используемый для хранения данных localStorage. Если файл не существует, он создаётся при первом обращении к localStorage. Один и тот же файл можно одновременно использовать в нескольких процессах Node.js.

--max-http-header-size=size

Задаёт максимальный размер HTTP-заголовков в байтах. По умолчанию — 16 КиБ.

--max-old-space-size-percentage=percentage

Задаёт максимальный размер старой области памяти V8 в процентах от доступной системной памяти. Если указаны оба флага, этот флаг имеет приоритет над --max-old-space-size.

Параметр percentage должен быть числом больше 0 и не превышать 100; он задаёт процент доступной системной памяти, выделяемой для кучи V8.

Примечание: Этот флаг использует --max-old-space-size, который может работать ненадёжно на 32-разрядных платформах из-за переполнения целых чисел.

# Using 50% of available system memory
node --max-old-space-size-percentage=50 index.js

# Using 75% of available system memory
node --max-old-space-size-percentage=75 index.js
bashcopy

--napi-modules

Этот параметр ничего не делает. Он сохранён для совместимости.

--network-family-autoselection-attempt-timeout

Задаёт значение по умолчанию для тайм-аута попытки автоматического выбора семейства сети. Дополнительные сведения см. в разделе net.getDefaultAutoSelectFamilyAttemptTimeout().

--no-addons

Отключает условие экспорта node-addons, а также загрузку нативных дополнений. Если указан --no-addons, вызов process.dlopen или подключение нативного дополнения на C++ завершится ошибкой с выбросом исключения.

--no-async-context-frame

Отключает использование AsyncLocalStorage, основанного на AsyncContextFrame, и использует предыдущую реализацию, которая полагалась на async_hooks. Предыдущая модель сохранена для совместимости с Electron и для случаев, когда поток контекста может отличаться. Если обнаружится различие в потоке, сообщите об этом.

--no-deprecation

Отключает предупреждения об устаревании.

--no-experimental-detect-module

Отключает использование определения синтаксиса для определения типа модуля.

--no-experimental-global-navigator

Отключает предоставление API Navigator в глобальной области видимости.

--no-experimental-repl-await

Используйте этот флаг, чтобы отключить верхнеуровневый await в REPL.

--no-experimental-require-module

Устаревший псевдоним для --no-require-module.

--no-experimental-sqlite

Отключает экспериментальный модуль node:sqlite.

--no-experimental-websocket

Отключает предоставление <WebSocket> в глобальной области видимости.

--no-experimental-webstorage

Отключает поддержку Web Storage.

--no-extra-info-on-fatal-exception

Скрывает дополнительную информацию о фатальном исключении, приводящем к завершению процесса.

--no-force-async-hooks-checks

Отключает проверки async_hooks во время выполнения. Они всё равно будут включены динамически, если включён async_hooks.

--no-global-search-paths

Не выполняет поиск модулей в глобальных путях, таких как $HOME/.node_modules и $NODE_PATH.

--no-network-family-autoselection

Отключает алгоритм автоматического выбора семейства, если только он явно не включён в параметрах подключения.

--no-require-module

Отключает поддержку загрузки синхронного графа модулей ES в require().

См. раздел Загрузка модулей ECMAScript с помощью require().

--no-strip-types

Отключает удаление типов в файлах TypeScript. Дополнительные сведения см. в документации по удалению типов TypeScript.

--no-warnings

Отключает все предупреждения процесса (в том числе об устаревании).

--node-memory-debug

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

--openssl-config=file

Загружает файл конфигурации OpenSSL при запуске. Помимо прочего, это можно использовать для включения криптографии, соответствующей требованиям FIPS, если Node.js собран с OpenSSL с поддержкой FIPS.

--openssl-legacy-provider

Включает устаревший провайдер OpenSSL 3.0. Дополнительные сведения см. в разделе OSSL_PROVIDER-legacy.

--openssl-shared-config

Включает раздел конфигурации OpenSSL по умолчанию, openssl_conf, который считывается из файла конфигурации OpenSSL. Файл конфигурации по умолчанию называется openssl.cnf, но это имя можно изменить с помощью переменной среды OPENSSL_CONF или параметра командной строки --openssl-config. Расположение файла конфигурации OpenSSL по умолчанию зависит от способа связывания OpenSSL с Node.js. Совместное использование конфигурации OpenSSL может иметь нежелательные последствия; рекомендуется использовать раздел конфигурации, предназначенный для Node.js: nodejs_conf. Он используется по умолчанию, если этот параметр не задан.

--pending-deprecation

Выводит предупреждения об ожидаемом устаревании.

Ожидаемое устаревание обычно ничем не отличается от устаревания во время выполнения, за исключением того, что по умолчанию оно отключено и предупреждения не выводятся, пока не задан флаг командной строки --pending-deprecation или переменная среды NODE_PENDING_DEPRECATION=1. Ожидаемое устаревание служит своего рода механизмом выборочного «раннего предупреждения», который разработчики могут использовать для выявления обращений к устаревшим API.

--permission

Включает модель разрешений для текущего процесса. После включения ограничиваются следующие разрешения:

• Файловая система — управление с помощью флагов --allow-fs-read и --allow-fs-write
• Сеть — управление с помощью флага --allow-net
• Дочерние процессы — управление с помощью флага --allow-child-process
• Рабочие потоки — управление с помощью флага --allow-worker
• WASI — управление с помощью флага --allow-wasi
• Дополнения — управление с помощью флага --allow-addons
• FFI — управление с помощью флага --allow-ffi

--permission-audit

Включает только аудит модели разрешений. При включении проверки разрешений выполняются, но доступ не запрещается. Вместо этого для каждого нарушения разрешений через канал диагностики выводится предупреждение.

--preserve-symlinks

Указывает загрузчику модулей сохранять символические ссылки при поиске и кэшировании модулей.

По умолчанию, когда Node.js загружает модуль по пути, символически связанному с другим расположением на диске, Node.js переходит по ссылке и использует фактический «реальный путь» модуля на диске и как идентификатор, и как корневой путь для поиска других модулей-зависимостей. В большинстве случаев такое поведение по умолчанию приемлемо. Однако при использовании символически связанных одноуровневых зависимостей, как показано в примере ниже, поведение по умолчанию приводит к выбросу исключения, если moduleA пытается подключить moduleB как одноуровневую зависимость:

{appDir}
 ├── app
 │   ├── index.js
 │   └── node_modules
 │       ├── moduleA -> {appDir}/moduleA
 │       └── moduleB
 │           ├── index.js
 │           └── package.json
 └── moduleA
     ├── index.js
     └── package.json
textcopy

Флаг командной строки --preserve-symlinks указывает Node.js использовать для модулей путь символической ссылки вместо реального пути, позволяя находить символически связанные одноуровневые зависимости.

Однако следует учитывать, что использование --preserve-symlinks может иметь и другие побочные эффекты. В частности, символически связанные нативные модули могут не загрузиться, если на них ссылаются из нескольких мест в дереве зависимостей (Node.js сочтёт их разными модулями и попытается загрузить модуль несколько раз, что приведёт к выбросу исключения).

Флаг --preserve-symlinks не применяется к главному модулю, что позволяет работать node --preserve-symlinks node_module/.bin/<foo>. Чтобы применить то же поведение к главному модулю, используйте также --preserve-symlinks-main.

--preserve-symlinks-main

Указывает загрузчику модулей сохранять символические ссылки при поиске и кэшировании главного модуля (require.main).

Этот флаг позволяет включить для главного модуля то же поведение, которое --preserve-symlinks задаёт для всех остальных импортов; однако это отдельные флаги для обеспечения обратной совместимости со старыми версиями Node.js.

--preserve-symlinks-main не подразумевает --preserve-symlinks; используйте --preserve-symlinks-main вместе с --preserve-symlinks, если нежелательно переходить по символическим ссылкам до разрешения относительных путей.

Дополнительные сведения см. в разделе --preserve-symlinks.

-p, --print "script"

То же, что и -e, но выводит результат.

--prof

Создаёт вывод профилировщика V8.

--prof-process

Обрабатывает вывод профилировщика V8, созданный с помощью параметра V8 --prof.

--redirect-warnings=file

Записывает предупреждения процесса в указанный файл вместо вывода в stderr. Если файл не существует, он будет создан; если существует — данные будут добавлены в конец. Если при попытке записи предупреждения в файл произойдёт ошибка, предупреждение будет выведено в stderr.

Имя file может быть абсолютным путём. Если это не так, каталог по умолчанию для записи задаётся параметром командной строки --diagnostic-dir.

--report-compact

Записывает отчёты в компактном формате — в виде JSON в одну строку, который удобнее обрабатывать системам обработки журналов, чем многострочный формат по умолчанию, предназначенный для чтения человеком.

--report-dir=directory, --report-directory=directory

Расположение, в котором будет создан отчёт.

--report-exclude-env

Если задан --report-exclude-env, созданный диагностический отчёт не будет содержать данные environmentVariables.

--report-exclude-network

Исключает header.networkInterfaces из диагностического отчёта. По умолчанию этот параметр не задан, и сетевые интерфейсы включаются в отчёт.

--report-filename=filename

Имя файла, в который будет записан отчёт.

Если в качестве имени файла указано 'stdout' или 'stderr', отчёт записывается соответственно в stdout или stderr процесса.

--report-on-fatalerror

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

--report-on-signal

Включает создание отчёта при получении указанного (или предопределённого) сигнала работающим процессом Node.js. Сигнал для создания отчёта задаётся с помощью --report-signal.

--report-signal=signal

Задаёт или сбрасывает сигнал для создания отчёта (не поддерживается в Windows). Сигнал по умолчанию — SIGUSR2.

--report-uncaught-exception

Включает создание отчёта при завершении процесса из-за необработанного исключения. Полезно при анализе стека JavaScript вместе с нативным стеком и другими данными среды выполнения.

-r, --require module

Загружает указанный модуль перед запуском.

Следует правилам разрешения модулей для require(). module может быть путём к файлу или именем модуля Node.

Модули, предварительно загруженные с помощью --require, запускаются до модулей, предварительно загруженных с помощью --import.

Модули предварительно загружаются как в главный поток, так и в любые рабочие потоки, порождённые процессы или кластеризованные процессы.

--run

Запускает указанную команду из объекта "scripts" файла package.json. Если параметр "command" не указан, выводится список доступных сценариев.

--run выполняет поиск вверх до корневого каталога и находит файл package.json, из которого нужно запустить команду.

Если ancestor-folder/node_modules/.bin является каталогом, --run добавляет ./node_modules/.bin для каждого родительского каталога текущего каталога к PATH, чтобы выполнять двоичные файлы из разных папок, в которых присутствует несколько каталогов node_modules.

--run выполняет команду в каталоге, содержащем соответствующий package.json.

Например, следующая команда запустит сценарий test из package.json в текущей папке:

$ node --run test
consolecopy

Команде также можно передать аргументы. Все аргументы после -- будут добавлены к сценарию:

$ node --run test -- --verbose
consolecopy

Преднамеренные ограничения

node --run не предназначен для соответствия поведению npm run или команд run других менеджеров пакетов. Реализация Node.js намеренно имеет более ограниченные возможности, чтобы обеспечить максимальную производительность в наиболее распространённых сценариях использования. Некоторые функции других реализаций run намеренно исключены:

• Запуск сценариев pre или post в дополнение к указанному сценарию.
• Определение переменных среды, специфичных для менеджера пакетов.

Переменные среды

При запуске сценария с помощью --run задаются следующие переменные среды:

• NODE_RUN_SCRIPT_NAME: имя запускаемого сценария. Например, если для запуска test используется --run, значение этой переменной будет test.
• NODE_RUN_PACKAGE_JSON_PATH: путь к обрабатываемому package.json.

--secure-heap-min=n

При использовании --secure-heap флаг --secure-heap-min задаёт минимальный размер выделения из защищённой кучи. Минимальное значение — 2. Максимальное значение — меньшее из --secure-heap и 2147483647. Указанное значение должно быть степенью двойки.

--secure-heap=n

Инициализирует защищённую кучу OpenSSL размером n байт. После инициализации защищённая куча используется для выделения памяти некоторых типов в OpenSSL при генерации ключей и выполнении других операций. Это может, например, предотвратить утечку конфиденциальной информации из-за выхода указателя за допустимые границы в любом направлении.

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

Указанный размер кучи должен быть степенью двойки. Любое значение меньше 2 отключает защищённую кучу.

По умолчанию защищённая куча отключена.

Защищённая куча недоступна в Windows.

Дополнительные сведения см. в разделе CRYPTO_secure_malloc_init.

--snapshot-blob=path

При использовании с --build-snapshot параметр --snapshot-blob задаёт путь для записи созданного двоичного файла снимка. Если параметр не задан, файл записывается как snapshot.blob в текущем рабочем каталоге.

При использовании без --build-snapshot параметр --snapshot-blob задаёт путь к двоичному файлу, который используется для восстановления состояния приложения.

При загрузке снимка Node.js проверяет следующее:

1. Версия, архитектура и платформа запущенного двоичного файла Node.js в точности совпадают с версией, архитектурой и платформой двоичного файла, создавшего снимок.
2. Флаги V8 и функции ЦП совместимы с двоичным файлом, создавшим снимок.

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

--test

Запускает средство командной строки для тестирования Node.js. Этот флаг нельзя сочетать с --watch-path, --check, --eval, --interactive или инспектором. Дополнительные сведения см. в документации по запуску тестов из командной строки.

--test-concurrency

Максимальное количество тестовых файлов, которые CLI запуска тестов выполняет одновременно. Если --test-isolation установлено в 'none', этот флаг игнорируется, а параллелизм равен единице. В противном случае по умолчанию используется значение os.availableParallelism() - 1.

--test-coverage-branches=threshold

Задает минимальный процент покрытых ветвей. Если покрытие кода не достигает указанного порога, процесс завершится с кодом 1.

--test-coverage-exclude

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

Этот параметр можно указывать несколько раз, чтобы исключить несколько шаблонов glob.

Если заданы и --test-coverage-exclude, и --test-coverage-include, файлы должны соответствовать обоим критериям, чтобы попасть в отчет о покрытии.

По умолчанию все соответствующие тестовые файлы исключаются из отчета о покрытии. Указание этого параметра переопределяет поведение по умолчанию.

--test-coverage-functions=threshold

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

--test-coverage-include

Включает определенные файлы в покрытие кода с помощью шаблона glob, который может соответствовать как абсолютным, так и относительным путям к файлам.

Этот параметр можно указывать несколько раз, чтобы включить несколько шаблонов glob.

Если заданы и --test-coverage-exclude, и --test-coverage-include, файлы должны соответствовать обоим критериям, чтобы попасть в отчет о покрытии.

--test-coverage-lines=threshold

Задает минимальный процент покрытых строк. Если покрытие кода не достигает указанного порога, процесс завершится с кодом 1.

--test-force-exit

Настраивает средство запуска тестов на завершение процесса после выполнения всех известных тестов, даже если цикл событий в противном случае оставался бы активным.

--test-global-setup=module

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

Подробнее см. в документации о глобальной настройке и очистке.

--test-isolation=mode

Настраивает тип изоляции тестов, используемый средством запуска тестов. Если mode имеет значение 'process', каждый тестовый файл запускается в отдельном дочернем процессе. Если mode имеет значение 'none', все тестовые файлы запускаются в том же процессе, что и средство запуска тестов. По умолчанию используется режим изоляции 'process'. Этот флаг игнорируется, если флаг --test отсутствует. Дополнительные сведения см. в разделе модель выполнения средства запуска тестов.

--test-name-pattern

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

Если заданы и --test-name-pattern, и --test-skip-pattern, для выполнения тесты должны соответствовать обоим требованиям.

--test-only

Настраивает средство запуска тестов так, чтобы выполнялись только тесты верхнего уровня, для которых задан параметр only. Этот флаг не требуется, если изоляция тестов отключена.

--test-random-seed

Задает начальное значение, используемое для рандомизации порядка выполнения тестов. Оно применяется как к порядку выполнения тестовых файлов, так и к тестам в очереди внутри каждого файла. Указание этого флага неявно включает рандомизацию, даже без --test-randomize.

Значение должно быть целым числом от 0 до 4294967295.

Этот флаг нельзя использовать вместе с --watch или --test-rerun-failures.

--test-randomize

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

Начальное значение, используемое для рандомизации, выводится в сводке по тестам и может быть повторно использовано с --test-random-seed.

Подробное описание поведения и примеры см. в разделе рандомизация порядка выполнения тестов.

Этот флаг нельзя использовать вместе с --watch или --test-rerun-failures.

--test-reporter

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

--test-reporter-destination

Назначение соответствующего средства формирования отчетов о тестах. Подробнее см. в документации о средствах формирования отчетов о тестах.

--test-rerun-failures

Путь к файлу, который позволяет средству запуска тестов сохранять состояние набора тестов между запусками. Средство запуска тестов использует этот файл, чтобы определить, какие тесты уже завершились успешно или с ошибкой, и повторно запускать неудачные тесты без повторного запуска всего набора. Если файл не существует, средство запуска тестов создаст его. Подробнее см. в документации о повторном запуске тестов.

--test-shard

Часть набора тестов для выполнения в формате <index>/<total>, где

• index — положительное целое число, индекс одной из частей.
• total — положительное целое число, общее количество частей.

Эта команда разделит все тестовые файлы на total равных частей и запустит только те, которые попали в часть index.

Например, чтобы разделить набор тестов на три части, используйте следующую команду:

node --test --test-shard=1/3
node --test --test-shard=2/3
node --test --test-shard=3/3
bashcopy

--test-skip-pattern

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

Если заданы и --test-name-pattern, и --test-skip-pattern, для выполнения тесты должны соответствовать обоим требованиям.

--test-timeout

Время в миллисекундах, по истечении которого выполнение теста завершается ошибкой. Если значение не задано, вложенные тесты наследуют его от родительского теста. Значение по умолчанию — Infinity.

--test-update-snapshots

Повторно создает файлы снимков, используемые средством запуска тестов для тестирования снимков.

--throw-deprecation

Выбрасывать ошибки при использовании устаревших возможностей.

--title=title

Задает process.title при запуске.

--tls-cipher-list=list

Задает альтернативный список шифров TLS по умолчанию. Требуется сборка Node.js с поддержкой криптографии (включена по умолчанию).

--tls-keylog=file

Записывает ключевой материал TLS в файл. Ключевой материал представлен в формате NSS SSLKEYLOGFILE и может использоваться программным обеспечением (например, Wireshark) для расшифровки трафика TLS.

--tls-max-v1.2

Устанавливает tls.DEFAULT_MAX_VERSION в значение 'TLSv1.2'. Используйте для отключения поддержки TLSv1.3.

--tls-max-v1.3

Устанавливает tls.DEFAULT_MAX_VERSION по умолчанию в значение 'TLSv1.3'. Используйте для включения поддержки TLSv1.3.

--tls-min-v1.0

Устанавливает tls.DEFAULT_MIN_VERSION по умолчанию в значение 'TLSv1'. Используйте для совместимости со старыми клиентами или серверами TLS.

--tls-min-v1.1

Устанавливает tls.DEFAULT_MIN_VERSION по умолчанию в значение 'TLSv1.1'. Используйте для совместимости со старыми клиентами или серверами TLS.

--tls-min-v1.2

Устанавливает tls.DEFAULT_MIN_VERSION по умолчанию в значение 'TLSv1.2'. Это значение используется по умолчанию в версиях 12.x и новее, однако параметр поддерживается для совместимости с более старыми версиями Node.js.

--tls-min-v1.3

Устанавливает tls.DEFAULT_MIN_VERSION по умолчанию в значение 'TLSv1.3'. Используйте для отключения поддержки TLSv1.2, который менее безопасен, чем TLSv1.3.

--trace-deprecation

Выводит трассировки стека для устаревших возможностей.

--trace-env

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

• Чтение переменных окружения, выполняемое самим Node.js.
• Записи в формате process.env.KEY = "SOME VALUE".
• Чтения в формате process.env.KEY.
• Определения в формате Object.defineProperty(process.env, 'KEY', {...}).
• Запросы в формате Object.hasOwn(process.env, 'KEY'), process.env.hasOwnProperty('KEY') или 'KEY' in process.env.
• Удаления в формате delete process.env.KEY.
• Перечисления в формате ...process.env или Object.keys(process.env).

Выводятся только имена переменных окружения, к которым выполняется обращение. Значения не выводятся.

Чтобы вывести трассировку стека при обращении, используйте --trace-env-js-stack и/или --trace-env-native-stack.

--trace-env-js-stack

Помимо сведений, выводимых --trace-env, выводит трассировку стека JavaScript для обращения.

--trace-env-native-stack

Помимо сведений, выводимых --trace-env, выводит трассировку стека на нативном уровне для обращения.

--trace-event-categories

Список категорий, разделенных запятыми, для которых следует вести трассировку событий при включении трассировки с помощью --trace-events-enabled.

--trace-event-file-pattern

Строка-шаблон, задающая путь к файлу данных трассировки событий; поддерживаются ${rotation} и ${pid}.

--trace-events-enabled

Включает сбор данных трассировки событий.

--trace-exit

Выводит трассировку стека при принудительном завершении среды, например при вызове process.exit().

--trace-require-module=mode

Выводит сведения об использовании загрузки модулей ECMAScript с помощью require().

Если mode имеет значение all, выводятся все случаи использования. Если mode имеет значение no-node-modules, сведения об использовании в папке node_modules не выводятся.

--trace-sigint

Выводит трассировку стека при получении SIGINT.

--trace-sync-io

Выводит трассировку стека при обнаружении синхронного ввода-вывода после первого прохода цикла событий.

--trace-tls

Выводит сведения трассировки пакетов TLS в stderr. Это можно использовать для отладки проблем с подключением TLS.

--trace-uncaught

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

Включение этого параметра может негативно повлиять на поведение сборщика мусора.

--trace-warnings

Выводит трассировки стека для предупреждений процесса (включая предупреждения об устаревших возможностях).

--track-heap-objects

Отслеживает выделение объектов в куче для создания снимков кучи.

--unhandled-rejections=mode

Этот флаг позволяет изменить поведение при возникновении необработанного отклонения промиса. Можно выбрать один из следующих режимов:

• throw: генерирует событие unhandledRejection. Если этот обработчик не задан, необработанное отклонение вызывает необработанное исключение. Это режим по умолчанию.
• strict: необработанное отклонение вызывает необработанное исключение. Если исключение обработано, генерируется событие unhandledRejection.
• warn: всегда вызывает предупреждение независимо от того, задан ли обработчик unhandledRejection, но не выводит предупреждение об устаревании.
• warn-with-error-code: генерирует событие unhandledRejection. Если этот обработчик не задан, выводит предупреждение и устанавливает код завершения процесса в 1.
• none: отключает все предупреждения.

Если отклонение происходит на этапе статической загрузки модулей ES точки входа командной строки, оно всегда вызывает необработанное исключение.

--use-bundled-ca, --use-openssl-ca

Использует встроенное хранилище CA Mozilla, поставляемое с текущей версией Node.js, либо хранилище CA OpenSSL по умолчанию. Хранилище по умолчанию можно выбрать во время сборки.

Встроенное хранилище CA, поставляемое с Node.js, представляет собой снимок хранилища CA Mozilla, зафиксированный на момент выпуска. Оно одинаково на всех поддерживаемых платформах.

Использование хранилища OpenSSL позволяет изменять его извне. В большинстве дистрибутивов Linux и BSD это хранилище поддерживается сопровождающими дистрибутива и системными администраторами. Расположение хранилища CA OpenSSL зависит от конфигурации библиотеки OpenSSL, но его можно изменить во время выполнения с помощью переменных окружения.

См. SSL_CERT_DIR и SSL_CERT_FILE.

--use-env-proxy

Если параметр включен, Node.js при запуске анализирует переменные окружения HTTP_PROXY, HTTPS_PROXY и NO_PROXY и направляет запросы через указанный прокси-сервер.

Это эквивалентно заданию переменной окружения NODE_USE_ENV_PROXY=1. Если заданы оба параметра, приоритет имеет --use-env-proxy.

--use-largepages=mode

При запуске повторно отображает статический код Node.js в большие страницы памяти. Если целевая система поддерживает эту возможность, статический код Node.js будет перемещен на страницы размером 2 МиБ вместо 4 КиБ.

Для mode допустимы следующие значения:

• off: отображение не выполняется. Это значение по умолчанию.
• on: если ОС поддерживает эту возможность, будет предпринята попытка отображения. Ошибка отображения игнорируется, а сообщение выводится в стандартный поток ошибок.
• silent: если ОС поддерживает эту возможность, будет предпринята попытка отображения. Ошибка отображения игнорируется и не сообщается.

--use-system-ca

Node.js использует доверенные сертификаты CA из системного хранилища вместе с параметром --use-bundled-ca и переменной окружения NODE_EXTRA_CA_CERTS. На платформах, отличных от Windows и macOS, сертификаты загружаются из каталога и файла, доверенных OpenSSL, аналогично --use-openssl-ca, но после первой загрузки кэшируются.

В Windows и macOS политика доверия к сертификатам похожа на политику Chromium в отношении локально доверенных сертификатов, но имеет некоторые отличия:

В macOS учитываются следующие настройки:

• Связки ключей «По умолчанию» и «Системная»
  • Доверие:
    • Любой сертификат, для которого установлен флажок «Всегда доверять» в поле «При использовании этого сертификата», либо
    • Любой сертификат, для которого флажок «Уровень защищенных сокетов (SSL)» установлен в значение «Всегда доверять».
  • Сертификат также должен быть действителен, а для «Базовой политики X.509» должно быть установлено значение «Всегда доверять».

В Windows учитываются следующие настройки:

• Локальный компьютер (доступ через certlm.msc)
  • Доверие:
    • Доверенные корневые центры сертификации
    • Доверенные лица
    • Корпоративное доверие -> Предприятие -> Доверенные корневые центры сертификации
    • Корпоративное доверие -> Предприятие -> Доверенные лица
    • Корпоративное доверие -> Групповая политика -> Доверенные корневые центры сертификации
    • Корпоративное доверие -> Групповая политика -> Доверенные лица
• Текущий пользователь (доступ через certmgr.msc)
  • Доверие:
    • Доверенные корневые центры сертификации
    • Корпоративное доверие -> Групповая политика -> Доверенные корневые центры сертификации

В Windows и macOS Node.js перед использованием проверяет, не запрещают ли пользовательские настройки доверенных сертификатов применять их для аутентификации TLS-сервера.

В настоящее время Node.js не поддерживает отзыв или запрет доверия сертификатам из другого источника на основании системных настроек.

В других системах Node.js загружает сертификаты из файла сертификатов по умолчанию (обычно /etc/ssl/cert.pem) и каталога сертификатов по умолчанию (обычно /etc/ssl/certs), используемых связанной с Node.js версией OpenSSL. Как правило, это соответствует соглашениям основных дистрибутивов Linux и других Unix-подобных систем. Если заданы переопределяющие переменные окружения OpenSSL (обычно SSL_CERT_FILE и SSL_CERT_DIR, в зависимости от конфигурации связанной с Node.js версии OpenSSL), для загрузки сертификатов будут использоваться указанные пути. Эти переменные окружения можно использовать как обходное решение, если общепринятые пути, используемые связанной с Node.js версией OpenSSL, по какой-либо причине не соответствуют конфигурации системы.

--v8-options

Выводит параметры командной строки V8.

--v8-pool-size=num

Задает размер пула потоков V8, используемого для распределения фоновых задач.

Если задано значение 0, Node.js выберет подходящий размер пула потоков на основе оценки степени параллелизма.

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

-v, --version

Выводит версию node.

--watch

Запускает Node.js в режиме наблюдения. В этом режиме изменения наблюдаемых файлов приводят к перезапуску процесса Node.js. По умолчанию режим наблюдения отслеживает точку входа и все подключенные или импортированные модули. Используйте --watch-path, чтобы указать пути для наблюдения.

Этот флаг нельзя использовать вместе с --check, --eval, --interactive или REPL.

Примечание: флаг --watch требует указать путь к файлу в качестве аргумента и несовместим с --run или вводом встроенного скрипта, поскольку --run имеет приоритет и отключает режим наблюдения. Если файл не указан, Node.js завершится с кодом состояния 9.

node --watch index.js
bashcopy

--watch-kill-signal

Настраивает сигнал, отправляемый процессу при перезапусках в режиме наблюдения.

node --watch --watch-kill-signal SIGINT test.js
bashcopy

--watch-path

Запускает Node.js в режиме наблюдения и задает пути для наблюдения. В этом режиме изменения в отслеживаемых путях приводят к перезапуску процесса Node.js. Это отключает наблюдение за подключенными или импортированными модулями, даже если используется вместе с --watch.

Этот флаг нельзя использовать вместе с --check, --eval, --interactive, --test или REPL.

Примечание: использование --watch-path неявно включает --watch, для которого требуется путь к файлу; он несовместим с --run, поскольку --run имеет приоритет и отключает режим наблюдения.

node --watch-path=./src --watch-path=./tests index.js
bashcopy

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

--watch-preserve-output

Отключает очистку консоли при перезапуске процесса в режиме наблюдения.

node --watch --watch-preserve-output test.js
bashcopy

--zero-fill-buffers

Автоматически заполняет нулями все вновь выделенные экземпляры Buffer.

Переменные окружения

FORCE_COLOR=[1, 2, 3]

Переменная окружения FORCE_COLOR используется для включения вывода с цветами ANSI. Допустимы следующие значения:

• 1, true или пустая строка '' обозначают поддержку 16 цветов;
• 2 обозначает поддержку 256 цветов;
• 3 обозначает поддержку 16 миллионов цветов.

Если используется FORCE_COLOR и ему присвоено поддерживаемое значение, переменные окружения NO_COLOR и NODE_DISABLE_COLORS игнорируются.

Любое другое значение отключает цветной вывод.

NODE_COMPILE_CACHE=dir

Включает кэш компиляции модулей для экземпляра Node.js. Подробности см. в документации по кэшу компиляции модулей.

NODE_COMPILE_CACHE_PORTABLE=1

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

NODE_DEBUG=module[,…]

Список основных модулей, разделенных ',', для которых следует выводить отладочную информацию.

NODE_DEBUG_NATIVE=module[,…]

Список основных модулей C++, разделенных ',', для которых следует выводить отладочную информацию.

NODE_DISABLE_COLORS=1

Если задано, цвета в REPL использоваться не будут.

NODE_DISABLE_COMPILE_CACHE=1

Отключает кэш компиляции модулей для экземпляра Node.js. Подробности см. в документации по кэшу компиляции модулей.

NODE_EXTRA_CA_CERTS=file

Если задано, к хорошо известным корневым центрам сертификации (например, VeriSign) будут добавлены сертификаты из файла file. Файл должен содержать один или несколько доверенных сертификатов в формате PEM. Если файл отсутствует или имеет неверный формат, будет выведено сообщение (один раз) с помощью process.emitWarning(), однако все прочие ошибки игнорируются.

Хорошо известные и дополнительные сертификаты не используются, если для клиента или сервера TLS или HTTPS явно задано свойство параметров ca.

Эта переменная среды игнорируется, если node запущен с правами setuid root или ему назначены файловые возможности Linux.

Переменная среды NODE_EXTRA_CA_CERTS считывается только при первом запуске процесса Node.js. Изменение значения во время выполнения с помощью process.env.NODE_EXTRA_CA_CERTS не влияет на текущий процесс.

NODE_ICU_DATA=file

Путь к данным ICU (объект Intl). При компиляции с поддержкой small-icu эти данные дополнят встроенные.

NODE_NO_WARNINGS=1

Если задано значение 1, предупреждения процесса подавляются.

NODE_OPTIONS=options...

Список параметров командной строки, разделенных пробелами. options... интерпретируются до параметров командной строки, поэтому параметры командной строки переопределяют значения из options... или дополняют их. Node.js завершится с ошибкой, если будет использован параметр, недопустимый в среде, например -p или файл скрипта.

Если значение параметра содержит пробел, его можно экранировать двойными кавычками:

NODE_OPTIONS='--require "./my path/file.js"'
bashcopy

Одиночный флаг, переданный как параметр командной строки, переопределяет такой же флаг, переданный в NODE_OPTIONS:

# The inspector will be available on port 5555
NODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555
bashcopy

Флаг, который можно передавать несколько раз, обрабатывается так, как если бы его экземпляры из NODE_OPTIONS были переданы первыми, а затем следовали экземпляры из командной строки:

NODE_OPTIONS='--require "./a.js"' node --require "./b.js"
# is equivalent to:
node --require "./a.js" --require "./b.js"
bashcopy

Ниже перечислены допустимые параметры Node.js. Если для параметра предусмотрены варианты --XX и --no-XX, поддерживаются оба, но в списке ниже указан только один из них.

• --allow-addons
• --allow-child-process
• --allow-ffi
• --allow-fs-read
• --allow-fs-write
• --allow-inspector
• --allow-net
• --allow-wasi
• --allow-worker
• --conditions, -C
• --cpu-prof-dir
• --cpu-prof-interval
• --cpu-prof-name
• --cpu-prof
• --diagnostic-dir
• --disable-proto
• --disable-sigusr1
• --disable-warning
• --disable-wasm-trap-handler
• --dns-result-order
• --enable-fips
• --enable-network-family-autoselection
• --enable-source-maps
• --entry-url
• --experimental-abortcontroller
• --experimental-addon-modules
• --experimental-detect-module
• --experimental-eventsource
• --experimental-ffi
• --experimental-import-meta-resolve
• --experimental-json-modules
• --experimental-loader
• --experimental-modules
• --experimental-print-required-tla
• --experimental-quic
• --experimental-require-module
• --experimental-shadow-realm
• --experimental-specifier-resolution
• --experimental-stream-iter
• --experimental-test-isolation
• --experimental-top-level-await
• --experimental-vm-modules
• --experimental-wasi-unstable-preview1
• --force-context-aware
• --force-fips
• --force-node-api-uncaught-exceptions-policy
• --frozen-intrinsics
• --heap-prof-dir
• --heap-prof-interval
• --heap-prof-name
• --heap-prof
• --heapsnapshot-near-heap-limit
• --heapsnapshot-signal
• --http-parser
• --icu-data-dir
• --import
• --input-type
• --insecure-http-parser
• --inspect-brk
• --inspect-port, --debug-port
• --inspect-publish-uid
• --inspect-wait
• --inspect
• --localstorage-file
• --max-http-header-size
• --max-old-space-size-percentage
• --napi-modules
• --network-family-autoselection-attempt-timeout
• --no-addons
• --no-async-context-frame
• --no-deprecation
• --no-experimental-global-navigator
• --no-experimental-repl-await
• --no-experimental-sqlite
• --no-experimental-strip-types
• --no-experimental-websocket
• --no-experimental-webstorage
• --no-extra-info-on-fatal-exception
• --no-force-async-hooks-checks
• --no-global-search-paths
• --no-network-family-autoselection
• --no-strip-types
• --no-warnings
• --no-webstorage
• --node-memory-debug
• --openssl-config
• --openssl-legacy-provider
• --openssl-shared-config
• --pending-deprecation
• --permission-audit
• --permission
• --preserve-symlinks-main
• --preserve-symlinks
• --prof-process
• --redirect-warnings
• --report-compact
• --report-dir, --report-directory
• --report-exclude-env
• --report-exclude-network
• --report-filename
• --report-on-fatalerror
• --report-on-signal
• --report-signal
• --report-uncaught-exception
• --require-module
• --require, -r
• --secure-heap-min
• --secure-heap
• --snapshot-blob
• --test-coverage-branches
• --test-coverage-exclude
• --test-coverage-functions
• --test-coverage-include
• --test-coverage-lines
• --test-global-setup
• --test-isolation
• --test-name-pattern
• --test-only
• --test-random-seed
• --test-randomize
• --test-reporter-destination
• --test-reporter
• --test-rerun-failures
• --test-shard
• --test-skip-pattern
• --throw-deprecation
• --title
• --tls-cipher-list
• --tls-keylog
• --tls-max-v1.2
• --tls-max-v1.3
• --tls-min-v1.0
• --tls-min-v1.1
• --tls-min-v1.2
• --tls-min-v1.3
• --trace-deprecation
• --trace-env-js-stack
• --trace-env-native-stack
• --trace-env
• --trace-event-categories
• --trace-event-file-pattern
• --trace-events-enabled
• --trace-exit
• --trace-require-module
• --trace-sigint
• --trace-sync-io
• --trace-tls
• --trace-uncaught
• --trace-warnings
• --track-heap-objects
• --unhandled-rejections
• --use-bundled-ca
• --use-env-proxy
• --use-largepages
• --use-openssl-ca
• --use-system-ca
• --v8-pool-size
• --watch-kill-signal
• --watch-path
• --watch-preserve-output
• --watch
• --zero-fill-buffers

Допустимые параметры V8:

• --abort-on-uncaught-exception
• --disallow-code-generation-from-strings
• --enable-etw-stack-walking
• --expose-gc
• --interpreted-frames-native-stack
• --jitless
• --max-heap-size
• --max-old-space-size
• --max-semi-space-size
• --perf-basic-prof-only-functions
• --perf-basic-prof
• --perf-prof-unwinding-info
• --perf-prof
• --stack-trace-limit

--perf-basic-prof-only-functions, --perf-basic-prof, --perf-prof-unwinding-info и --perf-prof доступны только в Linux.

--enable-etw-stack-walking доступен только в Windows.

NODE_PATH=path[:…]

Список каталогов, разделенных ':', которые добавляются в начало пути поиска модулей.

В Windows вместо этого используется список, разделенный ';'.

NODE_PENDING_DEPRECATION=1

Если задано значение 1, выводятся предупреждения об ожидающем устаревании.

Предупреждения об ожидающем устаревании обычно идентичны предупреждениям об устаревании во время выполнения, за исключением того, что по умолчанию они отключены и выводятся только при установленном флаге командной строки --pending-deprecation или переменной среды NODE_PENDING_DEPRECATION=1. Предупреждения об ожидающем устаревании служат своего рода механизмом выборочного «раннего оповещения», который разработчики могут использовать для обнаружения использования устаревшего API.

NODE_PENDING_PIPE_INSTANCES=instances

Задает число ожидающих дескрипторов экземпляров канала, когда сервер канала ожидает подключений. Эта настройка применяется только в Windows.

NODE_PRESERVE_SYMLINKS=1

Если задано значение 1, загрузчик модулей сохраняет символические ссылки при разрешении путей к модулям и их кэшировании.

NODE_REDIRECT_WARNINGS=file

Если задано, предупреждения процесса выводятся в указанный файл, а не в stderr. Если файл не существует, он будет создан; если существует — данные будут добавлены в конец. Если при записи предупреждения в файл произойдет ошибка, предупреждение будет выведено в stderr. Это эквивалентно использованию флага командной строки --redirect-warnings=file.

NODE_REPL_EXTERNAL_MODULE=file

Путь к модулю Node.js, который будет загружен вместо встроенного REPL. Если задать пустую строку (''), будет использоваться встроенный REPL.

NODE_REPL_HISTORY=file

Путь к файлу для хранения постоянной истории REPL. Путь по умолчанию — ~/.node_repl_history; эта переменная переопределяет его. Если задать пустую строку ('' или ' '), постоянная история REPL отключается.

NODE_SKIP_PLATFORM_CHECK=value

Если value равно '1', проверка поддержки платформы при запуске Node.js пропускается. Node.js может работать некорректно. Проблемы, возникшие на неподдерживаемых платформах, исправляться не будут.

NODE_TEST_CONTEXT=value

Если value равно 'child', параметры средства вывода результатов тестов переопределяются, а вывод тестов направляется в stdout в формате TAP. Если указано любое другое значение, Node.js не гарантирует формат средства вывода результатов тестов или его стабильность.

NODE_TLS_REJECT_UNAUTHORIZED=value

Если value равно '0', проверка сертификатов для TLS-соединений отключается. Это делает TLS и, соответственно, HTTPS небезопасными. Настоятельно не рекомендуется использовать эту переменную среды.

NODE_USE_ENV_PROXY=1

Если эта функция включена, Node.js при запуске считывает переменные среды HTTP_PROXY, HTTPS_PROXY и NO_PROXY и направляет запросы через указанный прокси-сервер.

Эту функцию также можно включить с помощью флага командной строки --use-env-proxy. Если заданы оба параметра, приоритет имеет --use-env-proxy.

NODE_USE_SYSTEM_CA=1

Node.js использует доверенные сертификаты центров сертификации из системного хранилища вместе с параметром --use-bundled-ca и переменной среды NODE_EXTRA_CA_CERTS.

Эту функцию также можно включить с помощью флага командной строки --use-system-ca. Если заданы оба параметра, приоритет имеет --use-system-ca.

NODE_V8_COVERAGE=dir

Если задано, Node.js начнет сохранять данные покрытия кода JavaScript V8 и карт исходного кода в указанный каталог (информация о покрытии записывается в файлы JSON с префиксом coverage).

NODE_V8_COVERAGE будет автоматически передаваться дочерним процессам, что упрощает инструментирование приложений, вызывающих семейство функций child_process.spawn(). Чтобы запретить передачу, для NODE_V8_COVERAGE можно задать пустую строку.

Вывод данных о покрытии

Данные о покрытии выводятся в виде массива объектов ScriptCoverage в ключе верхнего уровня result:

{
  "result": [
    {
      "scriptId": "67",
      "url": "internal/tty.js",
      "functions": []
    }
  ]
}
jsoncopy

Кэш карт исходного кода

Если данные карт исходного кода найдены, они добавляются в ключ верхнего уровня source-map-cache объекта JSON с данными о покрытии.

source-map-cache — это объект, ключи которого соответствуют файлам, из которых были извлечены карты исходного кода, а значения содержат исходный URL карты исходного кода (в ключе url), разобранные данные карты исходного кода версии 3 (в ключе data) и длины строк исходного файла (в ключе lineLengths).

{
  "result": [
    {
      "scriptId": "68",
      "url": "file:///absolute/path/to/source.js",
      "functions": []
    }
  ],
  "source-map-cache": {
    "file:///absolute/path/to/source.js": {
      "url": "./path-to-map.json",
      "data": {
        "version": 3,
        "sources": [
          "file:///absolute/path/to/original.js"
        ],
        "names": [
          "Foo",
          "console",
          "info"
        ],
        "mappings": "MAAMA,IACJC,YAAaC",
        "sourceRoot": "./"
      },
      "lineLengths": [
        13,
        62,
        38,
        27
      ]
    }
  }
}
jsoncopy

NO_COLOR=<any>

NO_COLOR — это псевдоним для NODE_DISABLE_COLORS. Значение переменной среды может быть произвольным.

OPENSSL_CONF=file

Загружает файл конфигурации OpenSSL при запуске. Помимо прочего, его можно использовать для включения криптографии, соответствующей требованиям FIPS, если Node.js собран с ./configure --openssl-fips.

Если используется параметр командной строки --openssl-config, переменная среды игнорируется.

SSL_CERT_DIR=dir

Если включен --use-openssl-ca или если --use-system-ca включен на платформах, отличных от macOS и Windows, этот параметр переопределяет каталог OpenSSL с доверенными сертификатами и задает его.

Обратите внимание: если среда дочернего процесса явно не задана, эта переменная среды будет унаследована всеми дочерними процессами. Если они используют OpenSSL, это может привести к тому, что они будут доверять тем же центрам сертификации, что и Node.js.

SSL_CERT_FILE=file

Если включен --use-openssl-ca или если --use-system-ca включен на платформах, отличных от macOS и Windows, этот параметр переопределяет файл OpenSSL с доверенными сертификатами и задает его.

Обратите внимание: если среда дочернего процесса явно не задана, эта переменная среды будет унаследована всеми дочерними процессами. Если они используют OpenSSL, это может привести к тому, что они будут доверять тем же центрам сертификации, что и Node.js.

TZ

Переменная среды TZ используется для указания конфигурации часового пояса.

Node.js поддерживает не все способы обработки TZ в других средах, описанные здесь, но поддерживает базовые идентификаторы часовых поясов (например, 'Etc/UTC', 'Europe/Paris' или 'America/New_York'). Некоторые другие сокращения или псевдонимы также могут поддерживаться, но их использование настоятельно не рекомендуется и не гарантируется.

$ TZ=Europe/Dublin node -pe "new Date().toString()"
Wed May 12 2021 20:30:48 GMT+0100 (Irish Standard Time)
consolecopy

UV_THREADPOOL_SIZE=size

Задает число потоков в пуле потоков libuv: size.

Node.js по возможности использует асинхронные системные API, но если они недоступны, пул потоков libuv применяется для создания асинхронных API Node.js на основе синхронных системных API. К API Node.js, использующим пул потоков, относятся:

• все API fs, кроме API наблюдения за файлами и API, явно обозначенных как синхронные
• асинхронные API криптографии, например crypto.pbkdf2(), crypto.scrypt(), crypto.randomBytes(), crypto.randomFill(), crypto.generateKeyPair()
• dns.lookup()
• все API zlib, кроме API, явно обозначенных как синхронные

Поскольку размер пула потоков libuv фиксирован, если по какой-либо причине один из этих API работает долго, производительность других (на первый взгляд не связанных с ним) API, выполняемых в пуле потоков libuv, снизится. Один из возможных способов смягчить эту проблему — увеличить размер пула потоков libuv, задав для переменной среды 'UV_THREADPOOL_SIZE' значение больше 4 (текущего значения по умолчанию). Однако изменение этого значения изнутри процесса с помощью process.env.UV_THREADPOOL_SIZE=size не гарантирует результата, поскольку пул потоков создается при инициализации среды выполнения — задолго до запуска пользовательского кода. Дополнительные сведения см. в документации по пулу потоков libuv.

Полезные параметры V8

V8 имеет собственный набор параметров CLI. Любой параметр CLI V8, переданный в node, будет передан V8 для обработки. Для параметров V8 не гарантируется стабильность. Сама команда V8 не считает их частью своего официального API и оставляет за собой право менять их в любое время. Кроме того, на них не распространяются гарантии стабильности Node.js. Многие параметры V8 представляют интерес только для разработчиков V8. Тем не менее небольшой набор параметров V8 широко применим в Node.js и описан здесь:

--abort-on-uncaught-exception

--disallow-code-generation-from-strings

--enable-etw-stack-walking

--expose-gc

--harmony-shadow-realm

--heap-snapshot-on-oom

--interpreted-frames-native-stack

--jitless

--max-heap-size

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

Этот параметр обычно используется для ограничения объема памяти, который процесс может использовать для кучи JavaScript.

--max-old-space-size=SIZE (в МиБ)

Задает максимальный размер памяти для старого пространства памяти V8. По мере приближения потребления памяти к пределу V8 будет тратить больше времени на сборку мусора, пытаясь освободить неиспользуемую память.

На компьютере с 2 ГиБ памяти рекомендуется задать значение 1536 (1,5 ГиБ), чтобы оставить часть памяти для других задач и избежать использования файла подкачки.

node --max-old-space-size=1536 index.js
bashcopy

--max-semi-space-size=SIZE (в МиБ)

Задает максимальный размер полупространства для сборщика мусора V8 типа scavenge в МиБ (мебибайтах). Увеличение максимального размера полупространства может повысить пропускную способность Node.js ценой увеличения потребления памяти.

Поскольку размер молодого поколения кучи V8 втрое больше размера полупространства (см. YoungGenerationSizeFromSemiSpaceSize в V8), увеличение полупространства на 1 МиБ применяется к каждому из трех отдельных полупространств и увеличивает размер кучи на 3 МиБ. Повышение пропускной способности зависит от вашей рабочей нагрузки (см. #42511).

Значение по умолчанию зависит от ограничения памяти. Например, в 64-разрядных системах с ограничением памяти 512 МиБ максимальный размер полупространства по умолчанию составляет 1 МиБ. При ограничении памяти до 2 ГиБ включительно максимальный размер полупространства по умолчанию в 64-разрядных системах будет меньше 16 МиБ.

Чтобы выбрать оптимальную конфигурацию для приложения, следует попробовать разные значения max-semi-space-size при выполнении тестов производительности приложения.

Например, выполните тесты производительности в 64-разрядной системе:

for MiB in 16 32 64 128; do
    node --max-semi-space-size=$MiB index.js
done
bashcopy

--perf-basic-prof

--perf-basic-prof-only-functions

--perf-prof

--perf-prof-unwinding-info

--prof

--security-revert

--stack-trace-limit=limit

Максимальное число кадров стека, включаемых в трассировку стека ошибки. Значение 0 отключает сбор трассировок стека. Значение по умолчанию — 10.

node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
bashcopy