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

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

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

Методы 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, с помощью child_process.exec() либо запустив cmd.exe и передав ему файл .bat или .cmd в качестве аргумента (именно это делают параметр shell и child_process.exec()). В любом случае, если имя файла сценария содержит пробелы, его необходимо заключить в кавычки.

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

exec('my.bat', (err, stdout, stderr) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(stdout);
});

// Script with spaces in the filename:
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true });
// or:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
});

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

exec('my.bat', (err, stdout, stderr) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(stdout);
});

// Script with spaces in the filename:
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true });
// or:
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> См. раздел stdio для child_process.spawn(). Если этот параметр указан, он переопределяет 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');
const process = require('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(__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,
}; copy

Используйте 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';
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}`);
});

Пример: очень сложный способ запуска 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 process = require('node: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) дочернего процесса. Дескрипторы 0, 1 и 2 соответствуют stdin, stdout и stderr. Можно указать дополнительные дескрипторы для создания дополнительных каналов между родительским и дочерним процессами. Значение может быть одним из следующих:

1. 'pipe': создает канал между дочерним и родительским процессами. Родительский конец канала доступен родительскому процессу как свойство объекта child_process под именем subprocess.stdio[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 игнорировать дескриптор файла в дочернем процессе. Хотя Node.js всегда открывает дескрипторы 0, 1 и 2 для запускаемых процессов, установка значения 'ignore' заставит Node.js открыть /dev/null и связать его с дескриптором дочернего процесса.

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

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

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

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

const { spawn } = require('node:child_process');
const process = require('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'] });

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 дочернего процесса. См. параметр stdio метода child_process.spawn(). По умолчанию 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 дочернего процесса. См. параметр stdio метода child_process.spawn(). По умолчанию 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 дочернего процесса. См. параметр stdio метода child_process.spawn(). По умолчанию: '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> Идентификатор процесса дочернего процесса.
  • 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> Код завершения, если дочерний процесс завершился самостоятельно.
• signal <string> Сигнал, по которому был завершён дочерний процесс.

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

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';
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}`);
});

Событие: 'disconnect'

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

Событие: 'error'

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

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

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

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

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

Событие: 'exit'

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

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

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

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

См. waitpid(2).

Событие: '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.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 process = require('node: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 }); copy

У дочерних процессов 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');
    });
  }
}); copy

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

В приведённом выше примере используется сервер, созданный с помощью модуля 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`);
    }
  }
}); copy

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

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

subprocess.signalCode

• <string> | <null>

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

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 соответственно.

В следующем примере только файловый дескриптор дочернего процесса 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 process = require('node: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().