Процесс-потомок

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

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.log(`stderr: ${data}`);
});

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

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

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

Для удобства, модуль child_process предоставляет несколько синхронных и асинхронных альтернатив child_process.spawn() и child_process.spawnSync(). Обратите внимание, что каждая из этих альтернатив реализована на основе child_process.spawn() или child_process.spawnSync().

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

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

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

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

Каждый из методов возвращает экземпляр ChildProcess. Эти объекты реализуют API 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.log(data.toString());
});

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

// OR...
const { exec } = 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])[src]

• command <строка> Команда для выполнения с аргументами, разделёнными пробелами.

• options <Объект>

  • cwd <строка> Текущая рабочая директория дочернего процесса. По умолчанию: null.
  • env <Объект> Параметры окружения в формате ключ-значение. По умолчанию: null.
  • encoding <строка> По умолчанию: 'utf8'
  • shell <строка> Оболочка для выполнения команды. См. Требования к оболочке и По умолчанию Windows оболочка. По умолчанию: '/bin/sh' в UNIX, process.env.ComSpec в Windows.
  • timeout <число> По умолчанию: 0
  • maxBuffer <число> Максимальный объём данных в байтах, разрешённый для stdout или stderr. При превышении этого значения дочерний процесс завершается, и вывод усекается. См. замечание в maxBuffer и Unicode. По умолчанию: 200 * 1024.
  • killSignal <строка> | <целое число> По умолчанию: 'SIGTERM'
  • uid <число> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
  • gid <число> Устанавливает идентификатор группы процесса (см. setgid(2)).
  • windowsHide <булево значение> Скрыть консольное окно дочернего процесса, которое обычно создаётся на Windows системах. По умолчанию: false.

• callback <Функция> вызывается с выводом при завершении процесса.

  • error <Ошибка>
  • stdout <строка> | <Буфер>
  • stderr <строка> | <Буфер>
• Возвращает: <Процесс>

Запускает оболочку и выполняет 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
// 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 будет содержать код завершения дочернего процесса, а error.signal будет содержать сигнал, который привёл к завершению процесса. Любой код завершения, отличный от 0, считается ошибкой.

Аргументы 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.log(`stderr: ${stderr}`);
});

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

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

Если этот метод вызывается в виде его util.promisify()ed версии, он возвращает Promise для Object с свойствами stdout и stderr. В случае ошибки (включая любые ошибки, приводящие к коду завершения, отличному от 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.log('stderr:', stderr);
}
lsExample();

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

• file <string> Название или путь к исполняемому файлу, который нужно запустить.
• args <string[]> Список строковых аргументов.

• options <Object>

  • cwd <string> Текущая рабочая директория дочернего процесса.
  • env <Object> Параметры среды в формате ключ-значение.
  • encoding <string> По умолчанию: 'utf8'
  • timeout <number> По умолчанию: 0
  • maxBuffer <number> Максимальный объём данных в байтах, разрешённый для stdout или stderr. Если превышен, дочерний процесс завершается, а любой вывод обрезается. См. замечание в разделе maxBuffer и Unicode. По умолчанию: 200 * 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 (без оболочки).

• callback <Функция> Вызывается при завершении процесса с выводом.

  • error <Ошибка>
  • stdout <строка> | <Буфер>
  • stderr <строка> | <Буфер>
• Возвращает: <Дочерний процесс>

Функция 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 свойствами. В случае ошибки (включая любую ошибку, приводящую к коду выхода, отличному от 0), возвращается отклонённая promise, с тем же объектом 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 включён, не передавайте необработанные данные пользователя в эту функцию. Любой ввод, содержащий метасимволы оболочки, может быть использован для запуска произвольного выполнения команд.

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

• modulePath <string> Модуль для выполнения в дочернем процессе.
• args <string[]> Список строковых аргументов.

• options <Object>

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

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

• command <string> Команда для выполнения.
• args <string[]> Список строковых аргументов.

• options <Object>

  • cwd <string> Текущая рабочая директория дочернего процесса.
  • env <Object> Параметры окружения (ключ-значение).
  • argv0 <string> Явно задайте значение argv[0], отправляемое дочернему процессу. По умолчанию это command.
  • stdio <Array> | <string> Настройка stdio дочернего процесса (см. options.stdio).
  • detached <boolean> Подготовка дочернего процесса к независимому запуску от родительского процесса. Конкретное поведение зависит от платформы, см. options.detached.
  • uid <number> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
  • gid <number> Устанавливает идентификатор группы процесса (см. setgid(2)).
  • shell <boolean> | <string> Если true, выполнит command внутри оболочки. Использует '/bin/sh' на UNIX и process.env.ComSpec на Windows. Можно указать другую оболочку в виде строки. См. Требования к оболочке и Оболочка по умолчанию для Windows. По умолчанию: false (без оболочки).
  • windowsVerbatimArguments <boolean> На Windows аргументы не цитируются и не экранируются. Игнорируется на Unix. Устанавливается автоматически, когда указано shell. По умолчанию: false.
  • windowsHide <boolean> Скрыть окно консоли дочернего процесса, которое обычно создается на Windows. По умолчанию: false.
• Возвращает: <ChildProcess>

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

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

Дополнительные опции можно указать в качестве третьего аргумента, по умолчанию:

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

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

Используйте 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.log(`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.log(`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.log(`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.log('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.

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' - Создать канал между дочерним процессом и родительским процессом. Родительский конец канала доступен родительскому процессу как свойство объекта child_process как subprocess.stdio[fd]. Каналы, созданные для fd 0 - 2, также доступны как subprocess.stdin, subprocess.stdout и subprocess.stderr соответственно.

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

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

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

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

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

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

7. null, undefined - Использовать значение по умолчанию. Для stdio fd 0, 1 и 2 (другими словами, stdin, stdout и stderr) создается канал. Для fd 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() как узкое место. Для получения дополнительной информации см. Проблему V8 7381.

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

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

Методы child_process.spawnSync(), child_process.execSync() и child_process.execFileSync() являются синхронными и БЛОКИРУЮТ цикл событий Node.js, приостанавливая выполнение любого дополнительного кода, пока созданный процесс не завершится.

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

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

• file <string> Название или путь к исполняемому файлу для запуска.
• args <string[]> Список строковых аргументов.

• options <Object>

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

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

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

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

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

child_process.execSync(command[, options])[src]

• command <string> Команда для выполнения.

• options <Object>

  • cwd <string> Текущая рабочая директория дочернего процесса.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Значение, которое будет передано как stdin дочернему процессу. Указание этого значения переопределит stdio[0].
  • stdio <string> | <Array> Настройка stdio дочернего процесса. stderr по умолчанию будет выводиться в stderr родительского процесса, если не указано stdio. По умолчанию: 'pipe'.
  • env <Object> Пара ключи-значения среды.
  • 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. По умолчанию: 200 * 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])[src]

• command <string> Команда для выполнения.
• args <string[]> Список строковых аргументов.

• options <Object>

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

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

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

Событие: 'close'

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

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

Событие: 'disconnect'

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

Событие: 'error'

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

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

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

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

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

Событие: 'exit'

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

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

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

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

См. waitpid(2).

Событие: 'message'

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

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

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

subprocess.channel

• <Object> Каналы IPC, представляющие подключение к дочернему процессу.

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

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.kill([signal])

• signal <string>

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

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) для справки.

В 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 process in the shell
}, 2000);

subprocess.killed

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

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

subprocess.pid

• <integer>

Возвращает идентификатор процесса (PID) дочернего процесса.

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 <Object>
• sendHandle <Handle>

• options <Object> Аргумент options, если он присутствует, — это объект, используемый для параметризации отправки определённых типов дескрипторов. options поддерживает следующие свойства:

  • keepOpen <boolean> Значение, которое может использоваться при передаче экземпляров net.Socket. Если true, сокет остаётся открытым в процессе отправки. По умолчанию: false.
• callback <Function>
• Возвращает: <boolean>

Когда между родительским и дочерним процессом установлен канал 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`);
    }
  }
});

После передачи сокета дочернему процессу родительский процесс больше не может отслеживать, когда сокет уничтожается. Для указания этого свойство .connections становится null. Рекомендуется не использовать .maxConnections в случае возникновения этой ситуации.

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

subprocess.stderr

• <stream.Readable>

Поток Readable Stream, который представляет собой стандартный поток ошибок (stderr) дочернего процесса.

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

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

subprocess.stdin

• <stream.Writable>

Поток Writable Stream, который представляет собой стандартный поток ввода (stdin ) дочернего процесса.

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

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

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

subprocess.stdio

• <Array>

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

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

const assert = require('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.stdout

• <stream.Readable>

Поток Readable Stream, который представляет собой стандартный поток вывода (stdout ) дочернего процесса.

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

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

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 на UNIX или /d /s /c на Windows. На Windows синтаксический анализ командной строки должен быть совместим с 'cmd.exe'.

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

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