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

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

// On Windows Only...
const { spawn } = require('child_process');
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

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

bat.stderr.on('data', (data) => {
  console.error(data.toString());
});

bat.on('exit', (code) => {
  console.log(`Child exited with code ${code}`);
});

// OR...
const { exec, spawn } = require('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 <строка> Команда для выполнения с аргументами, разделёнными пробелами.
• options <объект>
  • cwd <строка> Текущий рабочий каталог дочернего процесса. По умолчанию: process.cwd().
  • env <объект> Параметры окружения в формате ключ-значение. По умолчанию: process.env.
  • encoding <строка> По умолчанию: 'utf8'
  • shell <строка> Оболочка для выполнения команды. См. Требования к оболочке и Значение оболочки по умолчанию для Windows. По умолчанию: '/bin/sh' в Unix, process.env.ComSpec в Windows.
  • timeout <число> По умолчанию: 0
  • maxBuffer <число> Максимальный объём данных в байтах, разрешённых для stdout или stderr. Если предел превышен, дочерний процесс завершается, а выходные данные обрезаются. См. замечание в maxBuffer и Юникод. По умолчанию: 1024 * 1024.
  • killSignal <строка> | <целое> По умолчанию: 'SIGTERM'
  • uid <число> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
  • gid <число> Устанавливает идентификатор группы процесса (см. setgid(2)).
  • windowsHide <логическое> Скрыть консольное окно дочернего процесса, которое обычно создаётся в Windows. По умолчанию: false.
• callback <функция> вызывается с выводом при завершении процесса.
  • error <ошибка>
  • stdout <строка> | <буфер>
  • stderr <строка> | <буфер>
• Возвращает: <ChildProcess>

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

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('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), возвращается отклонённая promise с тем же объектом error , что и в обработчике, но с двумя дополнительными свойствами stdout и stderr.

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

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

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

• file <string> Название или путь исполняемого файла для запуска.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> Текущий рабочий каталог дочернего процесса.
  • env <Object> Параметры окружения в формате ключ-значение. По умолчанию: process.env.
  • encoding <string> По умолчанию: 'utf8'
  • timeout <number> По умолчанию: 0
  • maxBuffer <number> Максимальный объём данных в байтах, разрешённый для stdout или stderr. При превышении лимита дочерний процесс завершается, а любой вывод усекается. См. замечание в разделе maxBuffer и Юникод. По умолчанию: 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 внутри оболочки. Использует '/bin/sh' на Unix и process.env.ComSpec на Windows. Можно указать другую оболочку как строку. См. Требования к оболочке и По умолчанию оболочка Windows. По умолчанию: false (без оболочки).
  • signal <AbortSignal> позволяет прервать execFile с помощью 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('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('util');
const execFile = util.promisify(require('child_process').execFile);
async function getVersion() {
  const { stdout } = await execFile('node', ['--version']);
  console.log(stdout);
}
getVersion();

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

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

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

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

• modulePath <string> Модуль для выполнения в дочернем процессе.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> Текущая рабочая директория дочернего процесса.
  • 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.
  • silent <boolean> Если true, stdin, stdout и stderr дочернего процесса будут переданы родителю, иначе они будут унаследованы от родителя. См. опции 'pipe' и 'inherit' для child_process.spawn()`s stdio для дополнительных деталей. По умолчанию: false.
  • stdio <Array> | <string> См. child_process.spawn()`s stdio. При использовании этой опции она переопределяет silent. Если используется массив, он должен содержать ровно один элемент со значением 'ipc', иначе будет выброшено исключение. Например, [0, 1, 2, 'ipc'].
  • uid <number> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
  • windowsVerbatimArguments <boolean> На Windows не выполняется цитирование или экранирование аргументов. Игнорируется в Unix. По умолчанию: false.
• Возвращает: <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 в дочернем процессе.

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

Опция shell , доступная в child_process.spawn(), не поддерживается child_process.fork() и будет проигнорирована при установке.

Опция signal работает точно так же, как и в child_process.spawn().

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

• command <строка> Команда для выполнения.

• args <массив строк> Список строковых аргументов.

• options <объект>

  • cwd <строка> Текущий рабочий каталог дочернего процесса.
  • env <объект> Параметры среды в формате ключ-значение. По умолчанию: process.env.
  • argv0 <строка> Явное задание значения argv[0] для отправки дочернему процессу. Будет установлено в command если не указано.
  • stdio <массив> | <строка> Настройка stdio дочернего процесса (см. options.stdio).
  • detached <логическое значение> Подготовка дочернего процесса к независимому выполнению от родительского процесса. Конкретное поведение зависит от платформы, см. options.detached).
  • uid <число> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
  • gid <число> Устанавливает идентификатор группы процесса (см. setgid(2)).
  • serialization <строка> Указывает тип сериализации, используемой для отправки сообщений между процессами. Возможные значения: 'json' и 'advanced'. Подробнее см. Дополнительная сериализация. По умолчанию: 'json'.
  • shell <логическое значение> | <строка> Если true, запускает command внутри оболочки. Использует '/bin/sh' в Unix и process.env.ComSpec в Windows. Можно указать другую оболочку в виде строки. См. Требования к оболочке и Стандартная оболочка Windows. По умолчанию: false (без оболочки).
  • windowsVerbatimArguments <логическое значение> В Windows не производится цитирование или экранирование аргументов. В Unix игнорируется. Автоматически устанавливается в true при указании shell и CMD. По умолчанию: false.
  • windowsHide <логическое значение> Скрывает окно консоли подпроцесса, которое обычно создаётся в Windows. По умолчанию: false.
  • signal <AbortSignal> позволяет прервать выполнение execFile с помощью AbortSignal.

• Возвращает: <ChildProcess>

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

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

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

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

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

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

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

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

const { spawn } = require('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('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('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 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 process

options.detached

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

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

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

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

Пример долгоживущего процесса с откреплением и игнорированием родительских stdio дескрипторов для игнорирования завершения родительского процесса:

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

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

subprocess.unref();

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

const fs = require('fs');
const { spawn } = require('child_process');
const out = fs.openSync('./out.log', 'a');
const err = fs.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'] (по умолчанию)
• 'ignore': эквивалентно ['ignore', 'ignore', 'ignore']
• 'inherit': эквивалентно ['inherit', 'inherit', 'inherit'] или [0, 1, 2]

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

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

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

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

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

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

5. <Поток> объект: Поделиться потоком чтения или записи, который относится к tty, файлу, сокету или каналу связи (pipe) с дочерним процессом. Базовый дескриптор файла потока дублируется в дочернем процессе в дескриптор, соответствующий индексу в массиве stdio. Поток должен иметь базовый дескриптор (потоки файлов не имеют его, пока не произойдет событие 'open').

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

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

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

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

В операционных системах семейства Unix метод child_process.spawn() выполняет операции с памятью синхронно, прежде чем отделить цикл событий от дочернего процесса. Приложения с большим объемом потребления памяти могут столкнуться с узким местом из-за частых вызовов child_process.spawn(). Более подробную информацию можно найти в вопросе 7381 V8.

См. также: child_process.exec() и child_process.fork().

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

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

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

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

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

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

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

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

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

child_process.execSync(command[, options])

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

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

const { spawn } = require('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' генерируется, когда:

1. Процесс не может быть запущен,
2. Процесс не может быть убит,
3. Отправка сообщения дочернему процессу не удалась.

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

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

Событие: 'exit'

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

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

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

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

См. waitpid(2).

Событие: 'message'

• message <Объект> Разложенный JSON-объект или примитивное значение.
• sendHandle <Дескриптор> Объект net.Socket или net.Server, или undefined.

Событие '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

• <Объект> Труба, представляющая канал IPC с дочерним процессом.

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

subprocess.channel.ref()

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

subprocess.channel.unref()

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

subprocess.connected

• <логическое> Устанавливается в 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

• <целое>

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

subprocess.kill([signal])

• signal <число> | <строка>
• Возвращает: <логическое>

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

const { spawn } = require('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'). Дополнительные сведения см. в разделе События сигналов.

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

'use strict';
const { spawn } = require('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.killed

• <boolean> Устанавливается в значение true после того, как subprocess.kill() успешно отправляет сигнал дочернему процессу.

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

subprocess.pid

• <целое число> | <неопределено>

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

const { spawn } = require('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('child_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 <Объект>
• sendHandle <Обработчик>
• options <Объект> Аргумент options, если он присутствует, — это объект, используемый для параметризации отправки определённых типов дескрипторов. options поддерживает следующие свойства:
  • keepOpen <логическое значение> Значение, которое можно использовать при передаче экземпляров net.Socket. Если true, сокет сохраняется открытым в процессе отправки. По умолчанию: false.
• callback <Функция>
• Возвращает: <логическое значение>

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

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

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

const cp = require('child_process');
const n = cp.fork(`${__dirname}/sub.js`);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// Open up the server object and send the handle.
const server = require('net').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');
    });
  }
});

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

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

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

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

const { fork } = require('child_process');
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 = require('net').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);

Дочерний процесс получит дескриптор сокета в качестве второго аргумента, переданного в функцию обратного вызова события:

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

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

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

subprocess.signalCode

• <строка> | <null>

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

subprocess.spawnargs

• <Массив>

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

subprocess.spawnfile

• <строка>

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

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

subprocess.stderr

• <поток.Чтение>

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

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

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

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

subprocess.stdin

• <stream.Writable>

Поток, представляющий стандартный ввод дочернего процесса.

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

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

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

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

subprocess.stdio

• <Array>

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

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

const assert = require('assert');
const fs = require('fs');
const child_process = require('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>

Поток, представляющий стандартный вывод дочернего процесса.

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

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

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

const subprocess = spawn('ls');

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

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

subprocess.unref()

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

const { spawn } = require('child_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('中文测试') отправит 13 байт, закодированных в UTF-8, в stdout, хотя там всего 4 символа.

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

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

По умолчанию для оболочки Windows

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

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

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

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