Синтаксис

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 см. в документации по отладчику.

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

Точка входа программы — это строка, похожая на спецификатор. Если строка не является абсолютным путём, она разрешается как относительный путь от текущего рабочего каталога. Затем этот путь разрешается загрузчиком модулей CommonJS или загрузчиком ES-модулей, если передан параметр --experimental-default-type=module. Если соответствующий файл не найден, возникает ошибка.

Если файл найден, его путь будет передан загрузчику ES-модулей при любом из следующих условий:

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

В противном случае файл загружается с помощью загрузчика модулей CommonJS. Дополнительные сведения см. в разделе Загрузчики модулей.

Особенность точки входа при использовании загрузчика модулей ECMAScript

При загрузке точки входа программы загрузчик ES-модулей позволяет команде node принимать в качестве входных данных только файлы с расширениями .js, .mjs или .cjs; с расширениями .wasm, если включён параметр --experimental-wasm-modules; а также файлы без расширения, если передан параметр --experimental-default-type=module.

Параметры

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

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

-

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

--

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

--abort-on-uncaught-exception

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

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

--allow-addons

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

Пример:

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

$ node --experimental-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'
} copy

--allow-child-process

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

Пример:

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

$ node --experimental-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 Object.spawn (node:child_process:723:9)
    at Object.<anonymous> (/home/index.js:3:14)
    at Module._compile (node:internal/modules/cjs/loader:1120:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1174:10)
    at Module.load (node:internal/modules/cjs/loader:998:32)
    at Module._load (node:internal/modules/cjs/loader:839:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'ChildProcess'
} copy

--allow-fs-read

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

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

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

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

Также необходимо разрешить модуль инициализации. Рассмотрим следующий пример:

$ node --experimental-permission index.js

Error: Access to this API has been restricted
    at node:internal/main/run_main_module:23:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'FileSystemRead',
  resource: '/Users/rafaelgss/repos/os/node/index.js'
} copy

Процессу необходим доступ к модулю index.js:

node --experimental-permission --allow-fs-read=/path/to/index.js index.js copy

--allow-fs-write

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

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

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

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

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

--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: {
    '/': '/',
  },
}); copy

$ node --experimental-permission --allow-fs-read=* index.js
node:wasi:99
    const wrap = new _WASI(args, env, preopens, stdio);
                 ^

Error: Access to this API has been restricted
    at new WASI (node:wasi:99:18)
    at Object.<anonymous> (/home/index.js:3:1)
    at Module._compile (node:internal/modules/cjs/loader:1476:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1555:10)
    at Module.load (node:internal/modules/cjs/loader:1288:32)
    at Module._load (node:internal/modules/cjs/loader:1104:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:191:14)
    at node:internal/main/run_main_module:30:49 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WASI',
} copy

--allow-worker

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

Пример:

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

$ node --experimental-permission --allow-fs-read=* index.js
node:internal/worker:188
    this[kHandle] = new WorkerImpl(url,
                    ^

Error: Access to this API has been restricted
    at new Worker (node:internal/worker:188:21)
    at Object.<anonymous> (/home/index.js.js:3:1)
    at Module._compile (node:internal/modules/cjs/loader:1120:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1174:10)
    at Module.load (node:internal/modules/cjs/loader:998:32)
    at Module._load (node:internal/modules/cjs/loader:839:12)
    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
    at node:internal/main/run_main_module:17:47 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'WorkerThreads'
} copy

--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 copy

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 copy

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

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

1. Пользовательские модули пока не поддерживаются в снимке, поэтому можно создать снимок только одного файла. Однако перед созданием снимка пользователи могут объединить приложения в один скрипт с помощью выбранного средства сборки.
2. В снимке работает только подмножество встроенных модулей, хотя основной набор тестов Node.js проверяет возможность создания снимков для нескольких достаточно сложных приложений. Поддержка дополнительных модулей добавляется. Если при создании снимка возникают сбои или ошибки в поведении, отправьте отчёт в систему отслеживания ошибок 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 copy

-C condition, --conditions=condition

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

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

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

Например, чтобы запустить модуль с разрешением зависимостей для «development»:

node -C development app.js copy

--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 copy

--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-warning=code-or-type

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

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

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

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

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

import sys from 'node:sys';

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

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

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

По умолчанию Node.js использует проверку границ WebAssembly на основе обработчика ловушек. В результате V8 не нужно встраивать проверки границ в код, скомпилированный из WebAssembly, что может значительно ускорить выполнение WebAssembly. Однако для этой оптимизации требуется выделить большую область виртуальной памяти (в настоящее время 10 ГБ). Если из-за конфигурации системы или ограничений оборудования процесс Node.js не имеет доступа к достаточно большому адресному пространству виртуальной памяти, пользователи не смогут запускать WebAssembly, выделяющий память в этой области, и увидят ошибку нехватки памяти.

$ ulimit -v 5000000
$ node -p "new WebAssembly.Memory({ initial: 10, maximum: 100 });"
[eval]:1
new WebAssembly.Memory({ initial: 10, maximum: 100 });
^

RangeError: WebAssembly.Memory(): could not allocate memory
    at [eval]:1:1
    at runScriptInThisContext (node:internal/vm:209:10)
    at node:internal/process/execution:118:14
    at [eval]-wrapper:6:24
    at runScript (node:internal/process/execution:101:62)
    at evalScript (node:internal/process/execution:136:3)
    at node:internal/main/eval_string:49:3
 copy

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

--disable-proto=mode

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

--disallow-code-generation-from-strings

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

--expose-gc

Этот флаг предоставляет расширение gc из V8.

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

--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

Включает поддержку Source Map v3 для трассировок стека.

При использовании транспилятора, например TypeScript, в трассировках стека, создаваемых приложением, указывается транспилированный код, а не исходная позиция в коде. --enable-source-maps включает кэширование 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);
}; copy

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

--env-file=config

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

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

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

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

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

PORT=3000 copy

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

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

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

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

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

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

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

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

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

-e, --eval "script"

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

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

--experimental-default-type=type

Задаёт используемую систему модулей — module или commonjs — для следующего:

• Строковый ввод, переданный через --eval или STDIN, если --input-type не задан.

• Файлы с расширением .js или без расширения, если в той же папке или любой родительской папке отсутствует файл package.json.

• Файлы с расширением .js или без расширения, если в ближайшем родительском файле package.json отсутствует поле "type", за исключением случаев, когда папка package.json или любая родительская папка находится внутри папки node_modules.

Иными словами, --experimental-default-type=module меняет все места, где Node.js сейчас по умолчанию выбирает CommonJS, на выбор модулей ECMAScript, кроме папок и вложенных папок внутри node_modules, чтобы сохранить обратную совместимость.

При использовании --experimental-default-type=module и --experimental-wasm-modules файлы без расширения будут считаться файлами WebAssembly, если начинаются с магического числа WebAssembly (\0asm); в противном случае они будут считаться файлами JavaScript-модулей ES.

--experimental-eventsource

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

--experimental-import-meta-resolve

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

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

--experimental-loader=module

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

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

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

--experimental-network-imports

Включает экспериментальную поддержку протокола https: в спецификаторах import.

--experimental-network-inspection

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

--experimental-permission

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

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

--experimental-policy

Используйте указанный файл в качестве политики безопасности.

--experimental-require-module

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

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

--experimental-sea-config

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

--experimental-shadow-realm

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

--experimental-test-coverage

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

--experimental-test-module-mocks

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

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

--experimental-vm-modules

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

--experimental-wasi-unstable-preview1

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

--experimental-wasm-modules

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

--experimental-websocket

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

--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 copy

--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, так и нативной памяти вне кучи V8). Чем больше куча, тем больше ресурсов требуется. Node.js корректирует размер кучи V8 с учетом дополнительных расходов памяти на кучу 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
.... copy

--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 copy

-h, --help

Выводит параметры командной строки Node.js. Вывод этой опции содержит меньше подробностей, чем данный документ.

--icu-data-dir=file

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

--import=module

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

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

--input-type=type

Этот параметр указывает Node.js интерпретировать входные данные --eval или STDIN как CommonJS или как модуль ES. Допустимые значения: "commonjs" или "module". Значение по умолчанию — "commonjs", если не используется --experimental-default-type=module.

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[=[host:]port]

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

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

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

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

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

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

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

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

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

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

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

--inspect-port=[host:]port

Задает host:port, используемый при запуске инспектора. Полезно при запуске инспектора отправкой сигнала 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 для Node.js.

-i, --interactive

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

--jitless

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

--max-http-header-size=size

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

--napi-modules

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

--network-family-autoselection-attempt-timeout

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

--no-addons

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

--no-deprecation

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

--no-experimental-detect-module

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

--no-experimental-fetch

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

--no-experimental-global-customevent

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

--no-experimental-global-webcrypto

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

--no-experimental-repl-await

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

--no-experimental-require-module

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

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

--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-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, который используется по умолчанию, если этот параметр не задан.

--env-file-if-exists=config

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

--pending-deprecation

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

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

--policy-integrity=sri

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

--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 copy

Флаг командной строки --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, но выводит результат.

--experimental-print-required-tla

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

--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-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 вместе с нативным стеком и другими данными среды выполнения.

--report-exclude-network

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

-r, --require module

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

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

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

--secure-heap=n

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

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

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

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

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

Подробнее см. в CRYPTO_secure_malloc_init.

--secure-heap-min=n

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

--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 средства запуска тестов будет выполнять одновременно. Значение по умолчанию — os.availableParallelism() - 1.

--test-coverage-exclude

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

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

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

--test-coverage-include

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

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

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

--test-force-exit

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

--test-name-pattern

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

--test-only

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

--test-reporter

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

--test-reporter-destination

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

--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 copy

--test-timeout

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

--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-atomics-wait

Выводит в stderr краткую информацию о вызовах Atomics.wait(). Вывод может выглядеть так:

(node:15701) [Thread 0] Atomics.wait(<address> + 0, 1, inf) started
(node:15701) [Thread 0] Atomics.wait(<address> + 0, 1, inf) did not wait because the values mismatched
(node:15701) [Thread 0] Atomics.wait(<address> + 0, 0, 10) started
(node:15701) [Thread 0] Atomics.wait(<address> + 0, 0, 10) timed out
(node:15701) [Thread 0] Atomics.wait(<address> + 4, 0, inf) started
(node:15701) [Thread 1] Atomics.wait(<address> + 4, -1, inf) started
(node:15701) [Thread 0] Atomics.wait(<address> + 4, 0, inf) was woken up by another thread
(node:15701) [Thread 1] Atomics.wait(<address> + 4, -1, inf) was woken up by another thread copy

Эти поля соответствуют следующим значениям:

• Идентификатор потока, указанный в worker_threads.threadId
• Базовый адрес соответствующего SharedArrayBuffer, а также смещение в байтах, соответствующее индексу, переданному в Atomics.wait()
• Ожидаемое значение, переданное в Atomics.wait()
• Тайм-аут, переданный в Atomics.wait

--trace-deprecation

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

--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

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

• 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-largepages=mode

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

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

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

--v8-options

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

--v8-pool-size=num

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

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

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

-v, --version

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

--watch

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

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

node --watch index.js copy

--watch-path

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

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

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

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

--watch-preserve-output

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

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

--zero-fill-buffers

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

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

FORCE_COLOR=[1, 2, 3]

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

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

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

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

NO_COLOR=<any>

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

NODE_DEBUG=module[,…]

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

NODE_DEBUG_NATIVE=module[,…]

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

NODE_DISABLE_COLORS=1

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

NODE_EXTRA_CA_CERTS=file

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

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

Эта переменная среды игнорируется, когда node работает с правами root setuid или имеет заданные возможности файлов 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"' copy

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

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

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

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

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

• --allow-addons
• --allow-child-process
• --allow-fs-read
• --allow-fs-write
• --allow-wasi
• --allow-worker
• --conditions, -C
• --diagnostic-dir
• --disable-proto
• --disable-warning
• --disable-wasm-trap-handler
• --dns-result-order
• --enable-fips
• --enable-network-family-autoselection
• --enable-source-maps
• --experimental-abortcontroller
• --experimental-default-type
• --experimental-detect-module
• --experimental-eventsource
• --experimental-import-meta-resolve
• --experimental-json-modules
• --experimental-loader
• --experimental-modules
• --experimental-network-imports
• --experimental-permission
• --experimental-policy
• --experimental-print-required-tla
• --experimental-require-module
• --experimental-shadow-realm
• --experimental-specifier-resolution
• --experimental-top-level-await
• --experimental-vm-modules
• --experimental-wasi-unstable-preview1
• --experimental-wasm-modules
• --experimental-websocket
• --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
• --max-http-header-size
• --napi-modules
• --network-family-autoselection-attempt-timeout
• --no-addons
• --no-deprecation
• --no-experimental-fetch
• --no-experimental-global-customevent
• --no-experimental-global-webcrypto
• --no-experimental-repl-await
• --no-extra-info-on-fatal-exception
• --no-force-async-hooks-checks
• --no-global-search-paths
• --no-network-family-autoselection
• --no-warnings
• --node-memory-debug
• --openssl-config
• --openssl-legacy-provider
• --openssl-shared-config
• --pending-deprecation
• --policy-integrity
• --preserve-symlinks-main
• --preserve-symlinks
• --prof-process
• --redirect-warnings
• --report-compact
• --report-dir, --report-directory
• --report-exclude-network
• --report-filename
• --report-on-fatalerror
• --report-on-signal
• --report-signal
• --report-uncaught-exception
• --require, -r
• --secure-heap-min
• --secure-heap
• --snapshot-blob
• --test-only
• --test-reporter-destination
• --test-reporter
• --test-shard
• --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-atomics-wait
• --trace-deprecation
• --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-largepages
• --use-openssl-ca
• --v8-pool-size
• --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
• --huge-max-old-generation-size
• --interpreted-frames-native-stack
• --jitless
• --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

Задаёт количество ожидающих дескрипторов экземпляров pipe, когда сервер pipe ожидает подключений. Этот параметр применяется только в 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_V8_COVERAGE=dir

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

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

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

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

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

Кэш Source Map

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

source-map-cache — это объект, ключи которого представляют файлы, из которых были извлечены Source Map, а значения содержат исходный URL Source Map (в ключе url), разобранные данные Source Map v3 (в ключе 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
      ]
    }
  }
} copy

OPENSSL_CONF=file

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

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

SSL_CERT_DIR=dir

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

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

SSL_CERT_FILE=file

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

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

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) copy

UV_THREADPOOL_SIZE=size

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

Node.js по возможности использует асинхронные системные API, но если они недоступны, для создания асинхронных API Node.js на основе синхронных системных API используется пул потоков libuv. К 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.

UV_USE_IO_URING=value

Включает или отключает использование libuv io_uring на поддерживаемых платформах.

На поддерживаемых платформах io_uring может значительно повысить производительность различных асинхронных операций ввода-вывода.

По соображениям безопасности io_uring по умолчанию отключён. Если io_uring включён, приложения не должны менять идентификатор пользователя процесса во время выполнения. В этом случае недоступны функции JavaScript, такие как process.setuid(), а нативные дополнения не должны вызывать системные функции, такие как setuid(2).

Эта переменная среды реализована зависимостью Node.js и может быть удалена в будущих версиях Node.js. Поведение этой переменной среды не гарантирует стабильности.

Полезные параметры 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

--huge-max-old-generation-size

--jitless

--interpreted-frames-native-stack

--prof

--perf-basic-prof

--perf-basic-prof-only-functions

--perf-prof

--perf-prof-unwinding-info

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

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

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

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

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

Задаёт максимальный размер полупространства для сборщика мусора scavenge V8 в МиБ (мебибайтах). Увеличение максимального размера полупространства может повысить пропускную способность 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 copy

--security-revert

--stack-trace-limit=limit

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

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