Дочерний процесс

Модуль node:child_process позволяет порождать подпроцессы способом, похожим, но не идентичным popen(3). Эта возможность в первую очередь предоставляется функцией child_process.spawn():

const { spawn } = require('node:child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

import { spawn } from 'node:child_process';
import { once } from 'node:events';
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

const [code] = await once(ls, 'close');
console.log(`child process exited with code ${code}`);

По умолчанию между родительским процессом Node.js и порождённым подпроцессом устанавливаются каналы для stdin, stdout и stderr. Пропускная способность этих каналов ограничена и зависит от платформы. Если подпроцесс записывает в stdout данные, превышающие этот предел, а вывод не считывается, подпроцесс блокируется в ожидании, пока буфер канала не освободит место для новых данных. Это аналогично поведению каналов в оболочке. Используйте параметр { stdio: 'ignore' }, если вывод не будет считываться.

Поиск команды выполняется с использованием переменной окружения options.env.PATH, если env находится в объекте options. В противном случае используется process.env.PATH. Если задана options.env, но не задана PATH, в Unix поиск выполняется по пути поиска по умолчанию /usr/bin:/bin (см. руководство операционной системы для execvpe/execvp), а в Windows используется переменная окружения PATH текущего процесса.

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

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

Для удобства модуль node:child_process предоставляет несколько синхронных и асинхронных альтернатив функциям child_process.spawn() и child_process.spawnSync(). Каждая из этих альтернатив реализована поверх child_process.spawn() или child_process.spawnSync().

• child_process.exec(): запускает оболочку и выполняет в ней команду, передавая stdout и stderr функции обратного вызова после завершения.
• child_process.execFile(): аналогична child_process.exec(), но по умолчанию запускает команду напрямую, не запуская предварительно оболочку.
• child_process.fork(): порождает новый процесс Node.js и вызывает указанный модуль, устанавливая канал связи IPC, который позволяет отправлять сообщения между родительским и дочерним процессами.
• child_process.execSync(): синхронная версия child_process.exec(), блокирующая цикл событий Node.js.
• child_process.execFileSync(): синхронная версия child_process.execFile(), блокирующая цикл событий Node.js.

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

Асинхронное создание процессов

Методы child_process.spawn(), child_process.fork(), child_process.exec() и child_process.execFile() следуют идиоматическому шаблону асинхронного программирования, характерному для других API Node.js.

Каждый из этих методов возвращает экземпляр ChildProcess. Эти объекты реализуют API EventEmitter Node.js, позволяя родительскому процессу регистрировать функции-обработчики, которые вызываются при наступлении определённых событий в жизненном цикле дочернего процесса.

Методы child_process.exec() и child_process.execFile() также позволяют указать необязательную функцию callback, которая вызывается при завершении дочернего процесса.

Запуск файлов .bat и .cmd в Windows

Важность различия между child_process.exec() и child_process.execFile() может зависеть от платформы. В Unix-подобных операционных системах (Unix, Linux, macOS) child_process.execFile() может быть эффективнее, поскольку по умолчанию не запускает оболочку. Однако в Windows файлы .bat и .cmd не являются исполняемыми без терминала, поэтому их нельзя запустить с помощью child_process.execFile(). В Windows файлы .bat и .cmd можно вызвать следующим образом:

• используя child_process.spawn() с установленным параметром shell (не рекомендуется, см. DEP0190), или
• используя child_process.exec(), или
• породив cmd.exe и передав файл .bat или .cmd в качестве аргумента (именно так child_process.exec() действует внутри).

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

const { exec, spawn } = require('node:child_process');

exec('my.bat', (err, stdout, stderr) => { /* ... */ });

// Or, spawning cmd.exe directly:
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

// If the script filename contains spaces, it needs to be quoted
exec('"my script.cmd" a b', (err, stdout, stderr) => { /* ... */ });

import { exec, spawn } from 'node:child_process';

exec('my.bat', (err, stdout, stderr) => { /* ... */ });

// Or, spawning cmd.exe directly:
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

// If the script filename contains spaces, it needs to be quoted
exec('"my script.cmd" a b', (err, stdout, stderr) => { /* ... */ });

child_process.exec(command[, options][, callback])

• command <string> Выполняемая команда с аргументами, разделёнными пробелами.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса. По умолчанию: process.cwd().
  • env <Object> Пары «ключ-значение» переменных окружения. По умолчанию: process.env.
  • encoding <string> По умолчанию: 'utf8'
  • shell <string> Оболочка, используемая для выполнения команды. См. разделы Требования к оболочке и Оболочка Windows по умолчанию. По умолчанию: '/bin/sh' в Unix, process.env.ComSpec в Windows.
  • signal <AbortSignal> позволяет остановить дочерний процесс с помощью AbortSignal.
  • timeout <number> По умолчанию: 0
  • maxBuffer <number> Максимальный объём данных в байтах, допустимый для stdout или stderr. При превышении этого объёма дочерний процесс завершается, а любой вывод обрезается. См. примечание в разделе maxBuffer и Unicode. По умолчанию: 1024 * 1024.
  • killSignal <string> | <integer> По умолчанию: 'SIGTERM'
  • uid <number> Задаёт идентификатор пользователя процесса (см. setuid(2)).
  • gid <number> Задаёт идентификатор группы процесса (см. setgid(2)).
  • windowsHide <boolean> Скрывает окно консоли подпроцесса, которое обычно создаётся в системах Windows. По умолчанию: false.
• callback <Function> вызывается с результатами выполнения после завершения процесса.
  • error <Error>
  • stdout <string> | <Buffer>
  • stderr <string> | <Buffer>
• Возвращает: <ChildProcess>

Запускает оболочку, а затем выполняет в ней command, буферизуя весь созданный вывод. Строка command, переданная функции exec, обрабатывается непосредственно оболочкой; специальные символы (набор которых зависит от оболочки) необходимо обрабатывать соответствующим образом:

const { exec } = require('node:child_process');

exec('"/path/to/test file/test.sh" arg1 arg2');
// Double quotes are used so that the space in the path is not interpreted as
// a delimiter of multiple arguments.

exec('echo "The \\$HOME variable is $HOME"');
// The $HOME variable is escaped in the first instance, but not in the second.

import { exec } from 'node:child_process';

exec('"/path/to/test file/test.sh" arg1 arg2');
// Double quotes are used so that the space in the path is not interpreted as
// a delimiter of multiple arguments.

exec('echo "The \\$HOME variable is $HOME"');
// The $HOME variable is escaped in the first instance, but not in the second.

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

Если указана функция callback, она вызывается с аргументами (error, stdout, stderr). В случае успеха error будет иметь значение null. В случае ошибки error будет экземпляром Error. Свойство error.code будет содержать код завершения процесса. По соглашению, любой код завершения, отличный от 0, указывает на ошибку. error.signal будет содержать сигнал, завершивший процесс.

Аргументы stdout и stderr, переданные функции обратного вызова, будут содержать вывод stdout и stderr дочернего процесса. По умолчанию Node.js декодирует вывод в UTF-8 и передаёт функции обратного вызова строки. Параметр encoding можно использовать для указания кодировки символов, применяемой при декодировании вывода stdout и stderr. Если encoding имеет значение 'buffer' или содержит неизвестную кодировку символов, вместо этого функции обратного вызова будут переданы объекты Buffer.

const { exec } = require('node:child_process');
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`);
    return;
  }
  console.log(`stdout: ${stdout}`);
  console.error(`stderr: ${stderr}`);
});

import { exec } from 'node:child_process';
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`);
    return;
  }
  console.log(`stdout: ${stdout}`);
  console.error(`stderr: ${stderr}`);
});

Если значение timeout превышает 0, родительский процесс отправит сигнал, указанный в свойстве killSignal (по умолчанию это 'SIGTERM'), если дочерний процесс будет выполняться дольше timeout миллисекунд.

В отличие от системного вызова POSIX exec(3), child_process.exec() не заменяет текущий процесс и использует оболочку для выполнения команды.

Если этот метод вызван в версии, преобразованной с помощью util.promisify(), он возвращает Promise для объекта Object со свойствами stdout и stderr. Возвращённый экземпляр ChildProcess прикрепляется к Promise как свойство child. В случае ошибки (включая любую ошибку, приводящую к коду завершения, отличному от 0) возвращается отклонённый промис с тем же объектом error, который передаётся в функции обратного вызова, но с двумя дополнительными свойствами: stdout и stderr.

const util = require('node:util');
const exec = util.promisify(require('node:child_process').exec);

async function lsExample() {
  const { stdout, stderr } = await exec('ls');
  console.log('stdout:', stdout);
  console.error('stderr:', stderr);
}
lsExample();

import { promisify } from 'node:util';
import child_process from 'node:child_process';
const exec = promisify(child_process.exec);

async function lsExample() {
  const { stdout, stderr } = await exec('ls');
  console.log('stdout:', stdout);
  console.error('stderr:', stderr);
}
lsExample();

Если параметр signal включён, вызов .abort() для соответствующего AbortController аналогичен вызову .kill() для дочернего процесса, за исключением того, что ошибка, переданная функции обратного вызова, будет иметь тип AbortError:

const { exec } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();

import { exec } from 'node:child_process';
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();

child_process.execFile(file[, args][, options][, callback])

• file <string> Имя или путь исполняемого файла.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • env <Object> Пары «ключ-значение» переменных окружения. По умолчанию: process.env.
  • encoding <string> По умолчанию: 'utf8'
  • timeout <number> По умолчанию: 0
  • maxBuffer <number> Максимальный объём данных в байтах, допустимый для stdout или stderr. При превышении этого объёма дочерний процесс завершается, а любой вывод обрезается. См. примечание в разделе maxBuffer и Unicode. По умолчанию: 1024 * 1024.
  • killSignal <string> | <integer> По умолчанию: 'SIGTERM'
  • uid <number> Задаёт идентификатор пользователя процесса (см. setuid(2)).
  • gid <number> Задаёт идентификатор группы процесса (см. setgid(2)).
  • windowsHide <boolean> Скрывает окно консоли подпроцесса, которое обычно создаётся в системах Windows. По умолчанию: false.
  • windowsVerbatimArguments <boolean> В Windows аргументы не заключаются в кавычки и не экранируются. В Unix игнорируется. По умолчанию: false.
  • shell <boolean> | <string> Если равно true, запускает command внутри оболочки. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. В качестве строки можно указать другую оболочку. См. разделы Требования к оболочке и Оболочка Windows по умолчанию. По умолчанию: false (без оболочки).
  • signal <AbortSignal> позволяет остановить дочерний процесс с помощью AbortSignal.
• callback <Function> Вызывается с результатами выполнения после завершения процесса.
  • error <Error>
  • stdout <string> | <Buffer>
  • stderr <string> | <Buffer>
• Возвращает: <ChildProcess>

Функция child_process.execFile() аналогична child_process.exec(), но по умолчанию не запускает оболочку. Вместо этого указанный исполняемый файл file запускается непосредственно как новый процесс, что делает этот способ немного эффективнее, чем child_process.exec().

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

const { execFile } = require('node:child_process');
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
  if (error) {
    throw error;
  }
  console.log(stdout);
});

import { execFile } from 'node:child_process';
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
  if (error) {
    throw error;
  }
  console.log(stdout);
});

Аргументы stdout и stderr, переданные функции обратного вызова, будут содержать вывод stdout и stderr дочернего процесса. По умолчанию Node.js декодирует вывод в UTF-8 и передаёт функции обратного вызова строки. Параметр encoding можно использовать для указания кодировки символов, применяемой при декодировании вывода stdout и stderr. Если encoding имеет значение 'buffer' или содержит неизвестную кодировку символов, вместо этого функции обратного вызова будут переданы объекты Buffer.

Если этот метод вызван в версии, преобразованной с помощью util.promisify(), он возвращает Promise для объекта Object со свойствами stdout и stderr. Возвращённый экземпляр ChildProcess прикрепляется к Promise как свойство child. В случае ошибки (включая любую ошибку, приводящую к коду завершения, отличному от 0) возвращается отклонённый промис с тем же объектом error, который передаётся в функции обратного вызова, но с двумя дополнительными свойствами: stdout и stderr.

const util = require('node:util');
const execFile = util.promisify(require('node:child_process').execFile);
async function getVersion() {
  const { stdout } = await execFile('node', ['--version']);
  console.log(stdout);
}
getVersion();

import { promisify } from 'node:util';
import child_process from 'node:child_process';
const execFile = promisify(child_process.execFile);
async function getVersion() {
  const { stdout } = await execFile('node', ['--version']);
  console.log(stdout);
}
getVersion();

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

Если параметр signal включён, вызов .abort() для соответствующего AbortController аналогичен вызову .kill() для дочернего процесса, за исключением того, что ошибка, переданная функции обратного вызова, будет иметь тип AbortError:

const { execFile } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = execFile('node', ['--version'], { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();

import { execFile } from 'node:child_process';
const controller = new AbortController();
const { signal } = controller;
const child = execFile('node', ['--version'], { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();

child_process.fork(modulePath[, args][, options])

• modulePath <string> | <URL> Модуль, который будет запущен в дочернем процессе.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • detached <boolean> Подготовить дочерний процесс к независимой от родительского процесса работе. Конкретное поведение зависит от платформы (см. options.detached).
  • env <Object> Пары «ключ — значение» переменных среды. По умолчанию: process.env.
  • execPath <string> Исполняемый файл, используемый для создания дочернего процесса.
  • execArgv <string[]> Список строковых аргументов, передаваемых исполняемому файлу. По умолчанию: process.execArgv.
  • gid <number> Задает идентификатор группы процесса (см. setgid(2)).
  • serialization <string> Задает тип сериализации, используемой для передачи сообщений между процессами. Возможные значения: 'json' и 'advanced'. Подробнее см. в разделе Расширенная сериализация. По умолчанию: 'json'.
  • signal <AbortSignal> Позволяет закрыть дочерний процесс с помощью AbortSignal.
  • killSignal <string> | <integer> Значение сигнала, которое будет использоваться при завершении порожденного процесса по тайм-ауту или сигналу отмены. По умолчанию: 'SIGTERM'.
  • silent <boolean> Если значение равно true, потоки stdin, stdout и stderr дочернего процесса будут перенаправлены в родительский процесс; в противном случае они будут унаследованы от родительского процесса. Подробнее см. параметры 'pipe' и 'inherit' для child_process.spawn() в разделе stdio. По умолчанию: false.
  • stdio <Array> | <string> См. child_process.spawn(), раздел stdio. Если задан этот параметр, он переопределяет silent. Если используется вариант с массивом, в нем должен содержаться ровно один элемент со значением 'ipc', иначе будет выброшена ошибка. Например, [0, 1, 2, 'ipc'].
  • uid <number> Задает идентификатор пользователя процесса (см. setuid(2)).
  • windowsVerbatimArguments <boolean> В Windows аргументы не заключаются в кавычки и не экранируются. В Unix игнорируется. По умолчанию: false.
  • timeout <number> Максимальное время работы процесса в миллисекундах. По умолчанию: undefined.
• Возвращает: <ChildProcess>

Метод child_process.fork() — это особый случай использования child_process.spawn(), предназначенный специально для создания новых процессов Node.js. Как и child_process.spawn(), он возвращает объект ChildProcess. Возвращенный объект ChildProcess будет содержать встроенный дополнительный канал связи, позволяющий передавать сообщения между родительским и дочерним процессами. Подробнее см. subprocess.send().

Следует учитывать, что порожденные дочерние процессы Node.js независимы от родительского, за исключением установленного между ними канала связи IPC. У каждого процесса своя память и собственные экземпляры V8. Из-за дополнительных затрат ресурсов не рекомендуется создавать большое количество дочерних процессов Node.js.

По умолчанию child_process.fork() создает новые экземпляры Node.js, используя process.execPath родительского процесса. Свойство execPath объекта options позволяет указать альтернативный путь выполнения.

Процессы Node.js, запущенные с пользовательским значением execPath, взаимодействуют с родительским процессом через файловый дескриптор (fd), определяемый переменной среды NODE_CHANNEL_FD в дочернем процессе.

В отличие от системного вызова POSIX fork(2), child_process.fork() не клонирует текущий процесс.

Параметр shell, доступный в child_process.spawn(), не поддерживается методом child_process.fork() и будет проигнорирован, если его задать.

Если включен параметр signal, вызов .abort() для соответствующего AbortController аналогичен вызову .kill() для дочернего процесса, за исключением того, что переданная обратному вызову ошибка будет иметь тип AbortError:

const { fork } = require('node:child_process');

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`);
  }, 1_000);
} else {
  const controller = new AbortController();
  const { signal } = controller;
  const child = fork(__filename, ['child'], { signal });
  child.on('error', (err) => {
    // This will be called with err being an AbortError if the controller aborts
  });
  controller.abort(); // Stops the child process
}

import { fork } from 'node:child_process';
import process from 'node:process';

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`);
  }, 1_000);
} else {
  const controller = new AbortController();
  const { signal } = controller;
  const child = fork(import.meta.url, ['child'], { signal });
  child.on('error', (err) => {
    // This will be called with err being an AbortError if the controller aborts
  });
  controller.abort(); // Stops the child process
}

child_process.spawn(command[, args][, options])

• command <string> Команда для запуска.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • env <Object> Пары «ключ — значение» переменных среды. По умолчанию: process.env.
  • argv0 <string> Явно задает значение argv[0], передаваемое дочернему процессу. Если значение не указано, будет использовано command.
  • stdio <Array> | <string> Конфигурация stdio дочернего процесса (см. options.stdio).
  • detached <boolean> Подготовить дочерний процесс к независимой от родительского процесса работе. Конкретное поведение зависит от платформы (см. options.detached).
  • uid <number> Задает идентификатор пользователя процесса (см. setuid(2)).
  • gid <number> Задает идентификатор группы процесса (см. setgid(2)).
  • serialization <string> Задает тип сериализации, используемой для передачи сообщений между процессами. Возможные значения: 'json' и 'advanced'. Подробнее см. в разделе Расширенная сериализация. По умолчанию: 'json'.
  • shell <boolean> | <string> Если значение равно true, запускает command в оболочке. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. В качестве строки можно указать другую оболочку. См. разделы Требования к оболочке и Оболочка Windows по умолчанию. По умолчанию: false (без оболочки).
  • windowsVerbatimArguments <boolean> В Windows аргументы не заключаются в кавычки и не экранируются. В Unix игнорируется. Автоматически получает значение true, если указан shell и это CMD. По умолчанию: false.
  • windowsHide <boolean> Скрывает окно консоли подпроцесса, которое обычно создается в системах Windows. По умолчанию: false.
  • signal <AbortSignal> позволяет отменить дочерний процесс с помощью AbortSignal.
  • timeout <number> Максимальное время работы процесса в миллисекундах. По умолчанию: undefined.
  • killSignal <string> | <integer> Значение сигнала, которое будет использоваться при завершении порожденного процесса по тайм-ауту или сигналу отмены. По умолчанию: 'SIGTERM'.
• Возвращает: <ChildProcess>

Метод child_process.spawn() создает новый процесс с помощью указанной command, передавая аргументы командной строки в args. Если параметр не указан, args по умолчанию равен пустому массиву.

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

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

const defaults = {
  cwd: undefined,
  env: process.env,
};
jscopy

Используйте cwd, чтобы указать рабочий каталог, из которого запускается процесс. Если он не задан, используется текущий рабочий каталог. Если каталог задан, но не существует, дочерний процесс генерирует ошибку ENOENT и немедленно завершается. Ошибка ENOENT также генерируется, если команда не существует.

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

Значения undefined в env будут проигнорированы.

Пример запуска ls -lh /usr с перехватом stdout, stderr и кода завершения:

const { spawn } = require('node:child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});

import { spawn } from 'node:child_process';
import { once } from 'node:events';
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

const [code] = await once(ls, 'close');
console.log(`child process exited with code ${code}`);

Пример: весьма сложный способ запуска ps ax | grep ssh

const { spawn } = require('node:child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

import { spawn } from 'node:child_process';
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Пример проверки на сбой spawn:

const { spawn } = require('node:child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

import { spawn } from 'node:child_process';
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});

В некоторых системах (macOS, Linux) для заголовка процесса используется значение argv[0], а в других (Windows, SunOS) — command.

При запуске Node.js перезаписывает argv[0] значением process.execPath, поэтому значение process.argv[0] в дочернем процессе Node.js не будет соответствовать параметру argv0, переданному родительским процессом в spawn. Вместо этого получите его с помощью свойства process.argv0.

Если включен параметр signal, вызов .abort() для соответствующего AbortController аналогичен вызову .kill() для дочернего процесса, за исключением того, что переданная обратному вызову ошибка будет иметь тип AbortError:

const { spawn } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const grep = spawn('grep', ['ssh'], { signal });
grep.on('error', (err) => {
  // This will be called with err being an AbortError if the controller aborts
});
controller.abort(); // Stops the child process

import { spawn } from 'node:child_process';
const controller = new AbortController();
const { signal } = controller;
const grep = spawn('grep', ['ssh'], { signal });
grep.on('error', (err) => {
  // This will be called with err being an AbortError if the controller aborts
});
controller.abort(); // Stops the child process

options.detached

В Windows установка для options.detached значения true позволяет дочернему процессу продолжить работу после завершения родительского. У дочернего процесса будет собственное окно консоли. После включения этого параметра для дочернего процесса отключить его уже нельзя.

На платформах, отличных от Windows, если для options.detached задано значение true, дочерний процесс становится лидером новой группы процессов и сеанса. Дочерние процессы могут продолжать работу после завершения родительского независимо от того, отсоединены они или нет. Подробнее см. setsid(2).

По умолчанию родительский процесс ожидает завершения отсоединенного дочернего процесса. Чтобы родительский процесс не ожидал завершения заданного subprocess, используйте метод subprocess.unref(). В результате дочерний процесс не будет учитываться в счетчике ссылок цикла событий родительского процесса, что позволит родительскому процессу завершиться независимо от дочернего, если между ними не установлен канал IPC.

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

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

const { spawn } = require('node:child_process');

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();

import { spawn } from 'node:child_process';
import process from 'node:process';

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();

В качестве альтернативы можно перенаправить вывод дочернего процесса в файлы:

const { openSync } = require('node:fs');
const { spawn } = require('node:child_process');
const out = openSync('./out.log', 'a');
const err = openSync('./out.log', 'a');

const subprocess = spawn('prg', [], {
  detached: true,
  stdio: [ 'ignore', out, err ],
});

subprocess.unref();

import { openSync } from 'node:fs';
import { spawn } from 'node:child_process';
const out = openSync('./out.log', 'a');
const err = openSync('./out.log', 'a');

const subprocess = spawn('prg', [], {
  detached: true,
  stdio: [ 'ignore', out, err ],
});

subprocess.unref();

options.stdio

Параметр options.stdio используется для настройки каналов, устанавливаемых между родительским и дочерним процессами. По умолчанию потоки stdin, stdout и stderr дочернего процесса перенаправляются в соответствующие потоки subprocess.stdin, subprocess.stdout и subprocess.stderr объекта ChildProcess. Это эквивалентно установке значения options.stdio, равного ['pipe', 'pipe', 'pipe'].

Для удобства options.stdio может принимать одну из следующих строк:

• 'pipe': эквивалентно ['pipe', 'pipe', 'pipe'] (значение по умолчанию)
• 'overlapped': эквивалентно ['overlapped', 'overlapped', 'overlapped']
• 'ignore': эквивалентно ['ignore', 'ignore', 'ignore']
• 'inherit': эквивалентно ['inherit', 'inherit', 'inherit'] или [0, 1, 2]

В противном случае значение options.stdio представляет собой массив, в котором каждому индексу соответствует fd в дочернем процессе. fd 0, 1 и 2 соответствуют stdin, stdout и stderr. Можно указать дополнительные fd, чтобы создать дополнительные каналы между родительским и дочерним процессами. Допустимы следующие значения:

1. 'pipe': создает канал между дочерним и родительским процессами. Конец канала на стороне родительского процесса доступен ему как свойство объекта child_process под именем subprocess.stdio[fd]. Каналы, созданные для fd 0, 1 и 2, также доступны как subprocess.stdin, subprocess.stdout и subprocess.stderr соответственно. Это не настоящие каналы Unix, поэтому дочерний процесс не может использовать их через файлы дескрипторов, например /dev/fd/2 или /dev/stdout.

2. 'overlapped': то же, что и 'pipe', но для дескриптора установлен флаг FILE_FLAG_OVERLAPPED. Это необходимо для перекрывающегося ввода-вывода с дескрипторами stdio дочернего процесса. Подробнее см. в документации. В системах, отличных от Windows, это полностью эквивалентно 'pipe'.

3. 'ipc': создает канал IPC для передачи сообщений/файловых дескрипторов между родительским и дочерним процессами. Объект ChildProcess может иметь не более одного файлового дескриптора stdio IPC. Установка этого параметра включает метод subprocess.send(). Если дочерний процесс является экземпляром Node.js, наличие канала IPC включает методы process.send() и process.disconnect(), а также события 'disconnect' и 'message' в дочернем процессе.

   Доступ к дескриптору канала IPC любым способом, кроме process.send(), а также использование канала IPC с дочерним процессом, не являющимся экземпляром Node.js, не поддерживаются.

4. 'ignore': указывает Node.js игнорировать fd в дочернем процессе. Хотя Node.js всегда открывает fd 0, 1 и 2 для порождаемых процессов, установка для fd значения 'ignore' приведет к тому, что Node.js откроет /dev/null и подключит его к fd дочернего процесса.

5. 'inherit': передает соответствующий поток stdio родительского процесса в дочерний или из дочернего в родительский. Для первых трех позиций это эквивалентно process.stdin, process.stdout и process.stderr соответственно. Для любой другой позиции это эквивалентно 'ignore'.

6. Объект <Stream>: передает дочернему процессу поток для чтения или записи, связанный с tty, файлом, сокетом или каналом. Базовый файловый дескриптор потока дублируется в дочернем процессе и привязывается к fd, соответствующему индексу в массиве stdio. У потока должен быть базовый дескриптор (файловые потоки начинают работу только после события 'open'). ПРИМЕЧАНИЕ: хотя технически можно передать stdin как поток для записи или stdout/stderr как поток для чтения, делать это не рекомендуется. Потоки для чтения и записи имеют разное поведение, и их неправильное использование (например, передача потока для чтения вместо ожидаемого потока для записи) может привести к непредвиденным результатам или ошибкам. Такая практика не рекомендуется, поскольку при возникновении ошибок в потоке может привести к неопределенному поведению или потере обратных вызовов. Для обеспечения предусмотренного потока данных между родительским и дочерним процессами всегда используйте stdin для чтения, а stdout/stderr — для записи.

7. Положительное целое число: целое значение интерпретируется как файловый дескриптор, открытый в родительском процессе. Он совместно используется с дочерним процессом — аналогично объектам <Stream>. Передача сокетов в Windows не поддерживается.

8. null, undefined: используется значение по умолчанию. Для fd stdio 0, 1 и 2 (то есть stdin, stdout и stderr) создается канал. Для fd 3 и выше по умолчанию используется 'ignore'.

const { spawn } = require('node:child_process');

// Child will use parent's stdios.
spawn('prg', [], { stdio: 'inherit' });

// Spawn child sharing only stderr.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });

// Open an extra fd=4, to interact with programs presenting a
// startd-style interface.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });

import { spawn } from 'node:child_process';
import process from 'node:process';

// Child will use parent's stdios.
spawn('prg', [], { stdio: 'inherit' });

// Spawn child sharing only stderr.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });

// Open an extra fd=4, to interact with programs presenting a
// startd-style interface.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });

Следует отметить, что при установке канала IPC между родительским и дочерним процессами, если дочерний процесс является экземпляром Node.js, канал IPC при запуске дочернего процесса не учитывается в счетчике ссылок (с помощью unref()) до тех пор, пока дочерний процесс не зарегистрирует обработчик события 'disconnect' или события 'message'. Это позволяет дочернему процессу завершиться обычным образом, не удерживая процесс открытым из-за открытого канала IPC. См. также: child_process.exec() и child_process.fork().

Синхронное создание процессов

Методы child_process.spawnSync(), child_process.execSync() и child_process.execFileSync() являются синхронными и блокируют цикл событий Node.js, приостанавливая выполнение любого дополнительного кода до завершения порожденного процесса.

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

child_process.execFileSync(file[, args][, options])

• file <string> Имя или путь к исполняемому файлу для запуска.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Значение, которое будет передано в stdin запущенного процесса. Если для stdio[0] задано значение 'pipe', передача этого значения переопределит stdio[0].
  • stdio <string> | <Array> Конфигурация stdio дочернего процесса. См. child_process.spawn() stdio. По умолчанию stderr выводится в stderr родительского процесса, если не указан stdio. По умолчанию: 'pipe'.
  • env <Object> Пары ключ-значение переменных окружения. По умолчанию: process.env.
  • uid <number> Задаёт идентификатор пользователя процесса (см. setuid(2)).
  • gid <number> Задаёт идентификатор группы процесса (см. setgid(2)).
  • timeout <number> Максимальное время работы процесса в миллисекундах. По умолчанию: undefined.
  • killSignal <string> | <integer> Значение сигнала, который будет отправлен при завершении запущенного процесса. По умолчанию: 'SIGTERM'.
  • maxBuffer <number> Максимальный объём данных в байтах, допустимый для stdout или stderr. При превышении дочерний процесс завершается. См. примечание в разделе maxBuffer и Unicode. По умолчанию: 1024 * 1024.
  • encoding <string> Кодировка, используемая для всех входных и выходных потоков stdio. По умолчанию: 'buffer'.
  • windowsHide <boolean> Скрывает окно консоли подпроцесса, которое обычно создаётся в Windows. По умолчанию: false.
  • shell <boolean> | <string> Если значение равно true, запускает command в оболочке. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. В качестве строки можно указать другую оболочку. См. разделы Требования к оболочке и Оболочка Windows по умолчанию. По умолчанию: false (без оболочки).
• Возвращает: <Buffer> | <string> Вывод команды в stdout.

Метод child_process.execFileSync() в целом идентичен child_process.execFile(), за исключением того, что он не возвращает управление, пока дочерний процесс полностью не завершится. При превышении времени ожидания и отправке killSignal метод не вернёт управление, пока процесс полностью не завершится.

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

Если время ожидания процесса истекло или он завершился с ненулевым кодом выхода, этот метод вызовет исключение Error, содержащее полный результат вызова базового метода child_process.spawnSync().

Если параметр shell включён, не передавайте этой функции неочищенные пользовательские данные. Любые входные данные, содержащие метасимволы оболочки, могут привести к выполнению произвольных команд.

const { execFileSync } = require('node:child_process');

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // Capture stdout and stderr from child process. Overrides the
    // default behavior of streaming child stderr to the parent stderr
    stdio: 'pipe',

    // Use utf8 encoding for stdio pipes
    encoding: 'utf8',
  });

  console.log(stdout);
} catch (err) {
  if (err.code) {
    // Spawning child process failed
    console.error(err.code);
  } else {
    // Child was spawned but exited with non-zero exit code
    // Error contains any stdout and stderr from the child
    const { stdout, stderr } = err;

    console.error({ stdout, stderr });
  }
}

import { execFileSync } from 'node:child_process';

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // Capture stdout and stderr from child process. Overrides the
    // default behavior of streaming child stderr to the parent stderr
    stdio: 'pipe',

    // Use utf8 encoding for stdio pipes
    encoding: 'utf8',
  });

  console.log(stdout);
} catch (err) {
  if (err.code) {
    // Spawning child process failed
    console.error(err.code);
  } else {
    // Child was spawned but exited with non-zero exit code
    // Error contains any stdout and stderr from the child
    const { stdout, stderr } = err;

    console.error({ stdout, stderr });
  }
}

child_process.execSync(command[, options])

• command <string> Команда для запуска.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Значение, которое будет передано в stdin запущенного процесса. Если для stdio[0] задано значение 'pipe', передача этого значения переопределит stdio[0].
  • stdio <string> | <Array> Конфигурация stdio дочернего процесса. См. child_process.spawn() stdio. По умолчанию stderr выводится в stderr родительского процесса, если не указан stdio. По умолчанию: 'pipe'.
  • env <Object> Пары ключ-значение переменных окружения. По умолчанию: process.env.
  • shell <string> Оболочка для выполнения команды. См. разделы Требования к оболочке и Оболочка Windows по умолчанию. По умолчанию: '/bin/sh' в Unix, process.env.ComSpec в Windows.
  • uid <number> Задаёт идентификатор пользователя процесса. (См. setuid(2)).
  • gid <number> Задаёт идентификатор группы процесса. (См. setgid(2)).
  • timeout <number> Максимальное время работы процесса в миллисекундах. По умолчанию: undefined.
  • killSignal <string> | <integer> Значение сигнала, который будет отправлен при завершении запущенного процесса. По умолчанию: 'SIGTERM'.
  • maxBuffer <number> Максимальный объём данных в байтах, допустимый для stdout или stderr. При превышении дочерний процесс завершается, а его вывод обрезается. См. примечание в разделе maxBuffer и Unicode. По умолчанию: 1024 * 1024.
  • encoding <string> Кодировка, используемая для всех входных и выходных потоков stdio. По умолчанию: 'buffer'.
  • windowsHide <boolean> Скрывает окно консоли подпроцесса, которое обычно создаётся в Windows. По умолчанию: false.
• Возвращает: <Buffer> | <string> Вывод команды в stdout.

Метод child_process.execSync() в целом идентичен child_process.exec(), за исключением того, что он не возвращает управление, пока дочерний процесс полностью не завершится. При превышении времени ожидания и отправке killSignal метод не вернёт управление, пока процесс полностью не завершится. Если дочерний процесс перехватывает сигнал SIGTERM и обрабатывает его, но не завершается, родительский процесс будет ждать завершения дочернего процесса.

Если время ожидания процесса истекло или он завершился с ненулевым кодом выхода, этот метод вызовет исключение. Объект Error будет содержать полный результат вызова child_process.spawnSync().

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

child_process.spawnSync(command[, args][, options])

• command <string> Команда для запуска.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Значение, которое будет передано в stdin запущенного процесса. Если для stdio[0] задано значение 'pipe', передача этого значения переопределит stdio[0].
  • argv0 <string> Явно задаёт значение argv[0], отправляемое дочернему процессу. Если значение не указано, будет установлено command.
  • stdio <string> | <Array> Конфигурация stdio дочернего процесса. См. child_process.spawn() stdio. По умолчанию: 'pipe'.
  • env <Object> Пары ключ-значение переменных окружения. По умолчанию: process.env.
  • uid <number> Задаёт идентификатор пользователя процесса (см. setuid(2)).
  • gid <number> Задаёт идентификатор группы процесса (см. setgid(2)).
  • timeout <number> Максимальное время работы процесса в миллисекундах. По умолчанию: undefined.
  • killSignal <string> | <integer> Значение сигнала, который будет отправлен при завершении запущенного процесса. По умолчанию: 'SIGTERM'.
  • maxBuffer <number> Максимальный объём данных в байтах, допустимый для stdout или stderr. При превышении дочерний процесс завершается, а его вывод обрезается. См. примечание в разделе maxBuffer и Unicode. По умолчанию: 1024 * 1024.
  • encoding <string> Кодировка, используемая для всех входных и выходных потоков stdio. По умолчанию: 'buffer'.
  • shell <boolean> | <string> Если значение равно true, запускает command в оболочке. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. В качестве строки можно указать другую оболочку. См. разделы Требования к оболочке и Оболочка Windows по умолчанию. По умолчанию: false (без оболочки).
  • windowsVerbatimArguments <boolean> В Windows аргументы не заключаются в кавычки и не экранируются. В Unix параметр игнорируется. Автоматически получает значение true, если указан shell и используется CMD. По умолчанию: false.
  • windowsHide <boolean> Скрывает окно консоли подпроцесса, которое обычно создаётся в Windows. По умолчанию: false.
• Возвращает: <Object>
  • pid <number> Идентификатор процесса (PID) дочернего процесса.
  • output <Array> Массив результатов вывода stdio.
  • stdout <Buffer> | <string> Содержимое output[1].
  • stderr <Buffer> | <string> Содержимое output[2].
  • status <number> | <null> Код выхода подпроцесса или null, если подпроцесс завершился из-за сигнала.
  • signal <string> | <null> Сигнал, использованный для завершения подпроцесса, или null, если подпроцесс завершился не из-за сигнала.
  • error <Error> Объект ошибки, если дочерний процесс завершился с ошибкой или истекло время ожидания.

Метод child_process.spawnSync() в целом идентичен child_process.spawn(), за исключением того, что функция не возвращает управление, пока дочерний процесс полностью не завершится. При превышении времени ожидания и отправке killSignal метод не вернёт управление, пока процесс полностью не завершится. Если процесс перехватывает сигнал SIGTERM и обрабатывает его, но не завершается, родительский процесс будет ждать завершения дочернего процесса.

Если параметр shell включён, не передавайте этой функции неочищенные пользовательские данные. Любые входные данные, содержащие метасимволы оболочки, могут привести к выполнению произвольных команд.

Класс: ChildProcess

• Расширяет: <EventEmitter>

Экземпляры ChildProcess представляют запущенные дочерние процессы.

Не предполагается, что экземпляры ChildProcess будут создаваться напрямую. Вместо этого используйте методы child_process.spawn(), child_process.exec(), child_process.execFile() или child_process.fork() для создания экземпляров ChildProcess.

Событие: 'close'

• code <number> Код выхода, если дочерний процесс завершился самостоятельно, или null, если дочерний процесс завершился из-за сигнала.
• signal <string> Сигнал, из-за которого завершился дочерний процесс, или null, если дочерний процесс завершился не из-за сигнала.

Событие 'close' генерируется после завершения процесса и закрытия потоков stdio дочернего процесса. Оно отличается от события 'exit', поскольку несколько процессов могут использовать одни и те же потоки stdio. Событие 'close' всегда генерируется после события 'exit' либо 'error', если не удалось запустить дочерний процесс.

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

const { spawn } = require('node:child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process close all stdio with code ${code}`);
});

ls.on('exit', (code) => {
  console.log(`child process exited with code ${code}`);
});

import { spawn } from 'node:child_process';
import { once } from 'node:events';
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process close all stdio with code ${code}`);
});

ls.on('exit', (code) => {
  console.log(`child process exited with code ${code}`);
});

const [code] = await once(ls, 'close');
console.log(`child process close all stdio with code ${code}`);

Событие: 'disconnect'

Событие 'disconnect' генерируется после вызова метода subprocess.disconnect() в родительском процессе или метода process.disconnect() в дочернем процессе. После отключения отправлять и получать сообщения больше невозможно, а свойство subprocess.connected принимает значение false.

Событие: 'error'

• err <Error> Ошибка.

Событие 'error' генерируется в следующих случаях:

• Не удалось запустить процесс.
• Не удалось завершить процесс.
• Не удалось отправить сообщение дочернему процессу.
• Дочерний процесс был прерван с помощью параметра signal.

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

См. также subprocess.kill() и subprocess.send().

Событие: 'exit'

• code <number> Код выхода, если дочерний процесс завершился самостоятельно, или null, если дочерний процесс завершился из-за сигнала.
• signal <string> Сигнал, из-за которого завершился дочерний процесс, или null, если дочерний процесс завершился не из-за сигнала.

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

Когда генерируется событие 'exit', потоки stdio дочернего процесса могут оставаться открытыми.

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

См. waitpid(2).

Если значение code равно null из-за завершения по сигналу, можно использовать util.convertProcessSignalToExitCode() для преобразования сигнала в код выхода POSIX.

Событие: 'message'

• message <Object> Разобранный объект JSON или примитивное значение.
• sendHandle <Handle> | <undefined> undefined или объект net.Socket, net.Server либо dgram.Socket.

Событие 'message' возникает, когда дочерний процесс использует process.send() для отправки сообщений.

Сообщение проходит сериализацию и разбор. Полученное сообщение может отличаться от исходно отправленного.

Если при запуске дочернего процесса параметру serialization было присвоено значение 'advanced', аргумент message может содержать данные, которые невозможно представить в JSON. Подробнее см. в разделе Расширенная сериализация.

Событие: 'spawn'

Событие 'spawn' возникает после успешного запуска дочернего процесса. Если запустить дочерний процесс не удаётся, событие 'spawn' не возникает, а вместо него возникает событие 'error'.

Если событие 'spawn' возникает, это происходит до всех остальных событий и до получения каких-либо данных через stdout или stderr.

Событие 'spawn' возникает независимо от того, произошла ли ошибка внутри запущенного процесса. Например, если bash some-command запущен успешно, возникнет событие 'spawn', хотя запуск bash может завершиться ошибкой some-command. Это замечание также относится к использованию { shell: true }.

subprocess.channel

• Тип: <Object> Канал, представляющий IPC-канал связи с дочерним процессом.

Свойство subprocess.channel — это ссылка на IPC-канал дочернего процесса. Если IPC-канал отсутствует, это свойство равно undefined.

subprocess.channel.ref()

Этот метод не позволяет IPC-каналу останавливать цикл событий родительского процесса, если ранее был вызван .unref().

subprocess.channel.unref()

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

subprocess.connected

• Тип: <boolean> Значение устанавливается в false после вызова subprocess.disconnect().

Свойство subprocess.connected указывает, можно ли по-прежнему отправлять сообщения дочернему процессу и получать их от него. Когда subprocess.connected равно false, отправлять и получать сообщения больше невозможно.

subprocess.disconnect()

Закрывает IPC-канал между родительским и дочерним процессами, позволяя дочернему процессу корректно завершиться, если нет других соединений, которые не дают ему завершить работу. После вызова этого метода свойства subprocess.connected и process.connected в родительском и дочернем процессах соответственно будут установлены в false, и передавать сообщения между процессами станет невозможно.

Событие 'disconnect' возникает, когда все сообщения получены. Обычно это происходит сразу после вызова subprocess.disconnect().

Если дочерний процесс является экземпляром Node.js (например, запущен с помощью child_process.fork()), метод process.disconnect() также можно вызвать в дочернем процессе, чтобы закрыть IPC-канал.

subprocess.exitCode

• Тип: <integer>

Свойство subprocess.exitCode указывает код завершения дочернего процесса. Если дочерний процесс ещё выполняется, значение поля равно null.

Если дочерний процесс завершён сигналом, значение subprocess.exitCode будет null, а свойству subprocess.signalCode будет присвоено значение. Чтобы получить соответствующий код завершения POSIX, используйте util.convertProcessSignalToExitCode(subprocess.signalCode).

subprocess.kill([signal])

• signal <number> | <string>
• Возвращает: <boolean>

Метод subprocess.kill() отправляет сигнал дочернему процессу. Если аргумент не указан, процессу будет отправлен сигнал 'SIGTERM'. Список доступных сигналов см. в разделе signal(7). Эта функция возвращает true, если вызов kill(2) прошёл успешно, и false в противном случае.

const { spawn } = require('node:child_process');
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');

import { spawn } from 'node:child_process';
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');

Объект ChildProcess может вызвать событие 'error', если доставить сигнал невозможно. Отправка сигнала уже завершившемуся дочернему процессу не считается ошибкой, но может привести к непредвиденным последствиям. В частности, если идентификатор процесса (PID) был повторно присвоен другому процессу, сигнал будет доставлен этому процессу, что может привести к неожиданным результатам.

Хотя функция вызывается kill, отправленный дочернему процессу сигнал может фактически не завершить процесс.

Дополнительную информацию см. в разделе kill(2).

В Windows, где сигналов POSIX нет, аргумент signal игнорируется, за исключением 'SIGKILL', 'SIGTERM', 'SIGINT' и 'SIGQUIT'. Процесс всегда принудительно и немедленно завершается (аналогично 'SIGKILL'). Подробнее см. в разделе События сигналов.

В Linux дочерние процессы дочерних процессов не завершаются при попытке завершить их родительский процесс. Такая ситуация вероятна при запуске нового процесса в оболочке или при использовании параметра shell метода ChildProcess:

const { spawn } = require('node:child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);

import { spawn } from 'node:child_process';

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);

subprocess[Symbol.dispose]()

Вызывает subprocess.kill() с аргументом 'SIGTERM'.

subprocess.killed

• Тип: <boolean> Значение устанавливается в true после успешной отправки сигнала дочернему процессу с помощью subprocess.kill().

Свойство subprocess.killed указывает, успешно ли дочерний процесс получил сигнал от subprocess.kill(). Свойство killed не указывает, был ли завершён дочерний процесс.

subprocess.pid

• Тип: <integer> | <undefined>

Возвращает идентификатор процесса (PID) дочернего процесса. Если из-за ошибок не удаётся запустить дочерний процесс, значение будет undefined и возникнет событие error.

const { spawn } = require('node:child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();

import { spawn } from 'node:child_process';
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();

subprocess.ref()

Вызов subprocess.ref() после вызова subprocess.unref() восстановит счётчик ссылок дочернего процесса, заставив родительский процесс дождаться завершения дочернего процесса, прежде чем завершиться самому.

const { spawn } = require('node:child_process');

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();
subprocess.ref();

import { spawn } from 'node:child_process';
import process from 'node:process';

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();
subprocess.ref();

subprocess.send(message[, sendHandle[, options]][, callback])

• message <Object>
• sendHandle <Handle> | <undefined> undefined или объект net.Socket, net.Server либо dgram.Socket.
• options <Object> Аргумент options, если указан, — это объект, используемый для настройки отправки определённых типов дескрипторов. options поддерживает следующие свойства:
  • keepOpen <boolean> Значение, которое можно использовать при передаче экземпляров net.Socket. Если значение равно true, сокет остаётся открытым в отправляющем процессе. По умолчанию: false.
• callback <Function>
• Возвращает: <boolean>

Если между родительским и дочерним процессами установлен IPC-канал (например, при использовании child_process.fork()), метод subprocess.send() можно использовать для отправки сообщений дочернему процессу. Если дочерний процесс является экземпляром Node.js, эти сообщения можно получить через событие 'message'.

Сообщение проходит сериализацию и разбор. Полученное сообщение может отличаться от исходно отправленного.

Например, в родительском скрипте:

const { fork } = require('node:child_process');
const forkedProcess = fork(`${__dirname}/sub.js`);

forkedProcess.on('message', (message) => {
  console.log('PARENT got message:', message);
});

// Causes the child to print: CHILD got message: { hello: 'world' }
forkedProcess.send({ hello: 'world' });

import { fork } from 'node:child_process';
const forkedProcess = fork(`${import.meta.dirname}/sub.js`);

forkedProcess.on('message', (message) => {
  console.log('PARENT got message:', message);
});

// Causes the child to print: CHILD got message: { hello: 'world' }
forkedProcess.send({ hello: 'world' });

А дочерний скрипт 'sub.js' может выглядеть так:

process.on('message', (message) => {
  console.log('CHILD got message:', message);
});

// Causes the parent to print: PARENT got message: { foo: 'bar', baz: null }
process.send({ foo: 'bar', baz: NaN });
jscopy

У дочерних процессов Node.js есть собственный метод process.send(), позволяющий дочернему процессу отправлять сообщения обратно родительскому.

При отправке сообщения {cmd: 'NODE_foo'} возникает особый случай. Сообщения, содержащие префикс NODE_ в свойстве cmd, зарезервированы для использования в ядре Node.js и не будут вызываться в событии 'message' дочернего процесса. Вместо этого такие сообщения вызывают событие 'internalMessage' и обрабатываются внутри Node.js. Приложениям следует избегать отправки таких сообщений и прослушивания событий 'internalMessage', поскольку их поведение может измениться без предварительного уведомления.

Необязательный аргумент sendHandle, который можно передать в subprocess.send(), предназначен для передачи дочернему процессу объекта TCP-сервера или сокета. Дочерний процесс получит объект в качестве второго аргумента функции обратного вызова, зарегистрированной для события 'message'. Данные, уже полученные сокетом и находящиеся в буфере, дочернему процессу не передаются. Отправка IPC-сокетов в Windows не поддерживается.

Необязательный аргумент callback — это функция, вызываемая после отправки сообщения, но до того, как дочерний процесс может его получить. Функция вызывается с одним аргументом: null в случае успеха или объектом Error в случае ошибки.

Если функция callback не указана и сообщение невозможно отправить, объект ChildProcess вызовет событие 'error'. Такое может произойти, например, если дочерний процесс уже завершился.

Метод subprocess.send() вернёт false, если канал закрыт или если очередь неотправленных сообщений превышает порог, после которого отправлять новые сообщения нецелесообразно. В противном случае метод возвращает true. Функцию callback можно использовать для реализации управления потоком.

Пример: отправка объекта сервера

Аргумент sendHandle можно использовать, например, чтобы передать дочернему процессу дескриптор объекта TCP-сервера, как показано в примере ниже:

const { fork } = require('node:child_process');
const { createServer } = require('node:net');

const subprocess = fork('subprocess.js');

// Open up the server object and send the handle.
const server = createServer();
server.on('connection', (socket) => {
  socket.end('handled by parent');
});
server.listen(1337, () => {
  subprocess.send('server', server);
});

import { fork } from 'node:child_process';
import { createServer } from 'node:net';

const subprocess = fork('subprocess.js');

// Open up the server object and send the handle.
const server = createServer();
server.on('connection', (socket) => {
  socket.end('handled by parent');
});
server.listen(1337, () => {
  subprocess.send('server', server);
});

В таком случае дочерний процесс получит объект сервера следующим образом:

process.on('message', (m, server) => {
  if (m === 'server') {
    server.on('connection', (socket) => {
      socket.end('handled by child');
    });
  }
});
jscopy

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

В приведённом выше примере используется сервер, созданный с помощью модуля node:net, но серверы модуля node:dgram работают точно так же, за исключением того, что нужно прослушивать событие 'message' вместо 'connection' и использовать server.bind() вместо server.listen(). Однако это поддерживается только на платформах Unix.

Пример: отправка объекта сокета

Аналогично, аргумент sendHandler можно использовать для передачи дочернему процессу дескриптора сокета. В приведённом ниже примере запускаются два дочерних процесса, каждый из которых обрабатывает соединения с «обычным» или «высоким» приоритетом:

const { fork } = require('node:child_process');
const { createServer } = require('node:net');

const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);

// Open up the server and send sockets to child. Use pauseOnConnect to prevent
// the sockets from being read before they are sent to the child process.
const server = createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {

  // If this is special priority...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket);
    return;
  }
  // This is normal priority.
  normal.send('socket', socket);
});
server.listen(1337);

import { fork } from 'node:child_process';
import { createServer } from 'node:net';

const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);

// Open up the server and send sockets to child. Use pauseOnConnect to prevent
// the sockets from being read before they are sent to the child process.
const server = createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {

  // If this is special priority...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket);
    return;
  }
  // This is normal priority.
  normal.send('socket', socket);
});
server.listen(1337);

subprocess.js получит дескриптор сокета в качестве второго аргумента функции обратного вызова события:

process.on('message', (m, socket) => {
  if (m === 'socket') {
    if (socket) {
      // Check that the client socket exists.
      // It is possible for the socket to be closed between the time it is
      // sent and the time it is received in the child process.
      socket.end(`Request handled with ${process.argv[2]} priority`);
    }
  }
});
jscopy

Не используйте .maxConnections для сокета, переданного дочернему процессу. Родительский процесс не может отследить момент уничтожения сокета.

Все обработчики 'message' в дочернем процессе должны проверять, существует ли socket, поскольку соединение может быть закрыто за время передачи дочернему процессу.

subprocess.signalCode

• Тип: <string> | <null>

Свойство subprocess.signalCode указывает сигнал, полученный дочерним процессом, если таковой был, иначе — null.

Если дочерний процесс завершён сигналом, значение subprocess.exitCode будет null. Чтобы получить соответствующий код завершения POSIX, используйте util.convertProcessSignalToExitCode(subprocess.signalCode).

subprocess.spawnargs

• Тип: <Array>

Свойство subprocess.spawnargs содержит полный список аргументов командной строки, с которыми был запущен дочерний процесс.

subprocess.spawnfile

• Тип: <string>

Свойство subprocess.spawnfile указывает имя исполняемого файла запущенного дочернего процесса.

Для child_process.fork() его значение будет равно process.execPath. Для child_process.spawn() его значением будет имя исполняемого файла. Для child_process.exec() его значением будет имя оболочки, в которой запущен дочерний процесс.

subprocess.stderr

• Тип: <stream.Readable> | <null> | <undefined>

Объект Readable Stream, представляющий stderr дочернего процесса.

Если при запуске дочернего процесса параметру stdio[2] присвоено значение, отличное от 'pipe', это свойство будет равно null.

subprocess.stderr — это псевдоним subprocess.stdio[2]. Оба свойства указывают на одно и то же значение.

Свойство subprocess.stderr может иметь значение null или undefined, если запустить дочерний процесс не удалось.

subprocess.stdin

• Тип: <stream.Writable> | <null> | <undefined>

Объект Writable Stream, представляющий stdin дочернего процесса.

Если дочерний процесс ожидает чтения всех входных данных, он не продолжит работу, пока этот поток не будет закрыт с помощью end().

Если при запуске дочернего процесса параметру stdio[0] присвоено значение, отличное от 'pipe', это свойство будет равно null.

subprocess.stdin — это псевдоним subprocess.stdio[0]. Оба свойства указывают на одно и то же значение.

Свойство subprocess.stdin может иметь значение null или undefined, если запустить дочерний процесс не удалось.

subprocess.stdio

• Тип: <Array>

Разреженный массив каналов к дочернему процессу, соответствующих позициям в параметре stdio, переданном в child_process.spawn(), которым присвоено значение 'pipe'. subprocess.stdio[0], subprocess.stdio[1] и subprocess.stdio[2] также доступны соответственно как subprocess.stdin, subprocess.stdout и subprocess.stderr.

В следующем примере только fd 1 дочернего процесса (stdout) настроен как канал, поэтому потоком является только subprocess.stdio[1] родительского процесса, а все остальные элементы массива равны null.

const assert = require('node:assert');
const fs = require('node:fs');
const child_process = require('node:child_process');

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // Use parent's stdin for child.
    'pipe', // Pipe child's stdout to parent.
    fs.openSync('err.out', 'w'), // Direct child's stderr to a file.
  ],
});

assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);

assert(subprocess.stdout);
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);

assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);

import assert from 'node:assert';
import fs from 'node:fs';
import child_process from 'node:child_process';

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // Use parent's stdin for child.
    'pipe', // Pipe child's stdout to parent.
    fs.openSync('err.out', 'w'), // Direct child's stderr to a file.
  ],
});

assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);

assert(subprocess.stdout);
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);

assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);

Свойство subprocess.stdio может иметь значение undefined, если запустить дочерний процесс не удалось.

subprocess.stdout

• Тип: <stream.Readable> | <null> | <undefined>

Объект Readable Stream, представляющий stdout дочернего процесса.

Если при запуске дочернего процесса параметру stdio[1] присвоено значение, отличное от 'pipe', это свойство будет равно null.

subprocess.stdout — это псевдоним subprocess.stdio[1]. Оба свойства указывают на одно и то же значение.

const { spawn } = require('node:child_process');

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});

import { spawn } from 'node:child_process';

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});

Свойство subprocess.stdout может иметь значение null или undefined, если запустить дочерний процесс не удалось.

subprocess.unref()

По умолчанию родительский процесс ожидает завершения отсоединённого дочернего процесса. Чтобы родительский процесс не ждал завершения заданного subprocess, используйте метод subprocess.unref(). В результате дочерний процесс не будет учитываться в счётчике ссылок цикла событий родительского процесса, что позволит родительскому процессу завершиться независимо от дочернего, если между ними не установлен IPC-канал.

const { spawn } = require('node:child_process');

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();

import { spawn } from 'node:child_process';
import process from 'node:process';

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
});

subprocess.unref();

maxBuffer и Unicode

Параметр maxBuffer задаёт максимальное количество байтов, допустимое для stdout или stderr. Если это значение превышено, дочерний процесс завершается. Это влияет на вывод с многобайтовыми кодировками символов, такими как UTF-8 или UTF-16. Например, console.log('中文测试') отправит в stdout 13 байтов в кодировке UTF-8, хотя в нём всего 4 символа.

Требования к оболочке

Оболочка должна распознавать параметр -c. Если используется оболочка 'cmd.exe', она должна распознавать параметры /d /s /c, а разбор командной строки должен быть совместимым.

Оболочка Windows по умолчанию

Хотя Microsoft указывает, что %COMSPEC% должен содержать путь к 'cmd.exe' в корневой среде, к дочерним процессам это требование применяется не всегда. Поэтому в функциях child_process, где можно запустить оболочку, в качестве резервного варианта используется 'cmd.exe', если process.env.ComSpec недоступен.

Расширенная сериализация

Дочерние процессы поддерживают механизм сериализации для IPC, основанный на API сериализации модуля node:v8 и алгоритме структурированного клонирования HTML. Этот механизм в целом мощнее и поддерживает больше встроенных типов объектов JavaScript, таких как BigInt, Map и Set, ArrayBuffer и TypedArray, Buffer, Error, RegExp и т. д.

Однако этот формат не является полным надмножеством JSON, поэтому, например, свойства, заданные для объектов таких встроенных типов, не передаются на этапе сериализации. Кроме того, производительность может отличаться от производительности JSON в зависимости от структуры передаваемых данных. Поэтому для использования этой возможности необходимо явно включить её, присвоив параметру serialization значение 'advanced' при вызове child_process.spawn() или child_process.fork().