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

Модуль 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])

• 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

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

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

Если функция 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.

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

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

Если этот метод вызывается в его util.promisify() версии, он возвращает Promise для объекта со свойствами stdout и stderr. В случае ошибки возвращается отклоненное 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])

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

• modulePath <string> Модуль для выполнения в дочернем процессе.
• args <Array> Список строковых аргументов.
• options <Object>
  • cwd <string> Текущий рабочий каталог дочернего процесса.
  • env <Object> Переменные окружения в формате ключ-значение.
  • execPath <string> Исполняемый файл для создания дочернего процесса.
  • execArgv <Array> Список строковых аргументов, передаваемых исполняемому файлу. По умолчанию: process.execArgv.
  • silent <boolean> Если true, stdin, stdout и stderr дочернего процесса будут перенаправлены родительскому, в противном случае они будут унаследованы от родительского процесса. См. опции 'pipe' и 'inherit' для child_process.spawn()'s stdio для более подробной информации. По умолчанию: false.
  • stdio <Array> | <string> См. child_process.spawn()'s stdio. При использовании этого варианта, массив должен содержать ровно один элемент со значением '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 в дочернем процессе.

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

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

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

• command <string> Команда для выполнения.
• args <Array> Список строковых аргументов.
• 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. Автоматически устанавливается в значение true, когда задано 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.

Пример запуска 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 позволяет дочернему процессу продолжать выполнение после завершения родительского. Дочерний процесс будет иметь собственное окно консоли. После активации опции detached для дочернего процесса, её нельзя отключить.

На платформах, отличных от 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' - эквивалентно [process.stdin, process.stdout, process.stderr] или [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(), process.on('disconnect') и process.on('message') внутри дочернего процесса.

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

3. 'ignore' - Указывает Node.js игнорировать fd в дочернем процессе. Хотя Node.js всегда открывает fd 0-2 для генерируемых процессов, установка fd в 'ignore' заставит Node.js открыть /dev/null и привязать его к fd дочернего процесса.
4. <Поток> объект — Обмен читаемым или записываемым потоком, который ссылается на tty, файл, сокет или канал с дочерним процессом. Базовый дескриптор файла потока дублируется в дочернем процессе на fd, соответствующий индексу в массиве stdio. Обратите внимание, что поток должен иметь базовый дескриптор (файловые потоки не имеют его до момента события 'open').
5. Положительное целое число — Целое значение интерпретируется как дескриптор файла, который открыт в родительском процессе. Он разделяется с дочерним процессом, аналогично тому, как можно делиться объектами <Поток>.
6. 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()), пока дочерний процесс не зарегистрирует обработчик события process.on('disconnect') или события process.on('message'). Это позволяет дочернему процессу завершиться нормально без блокировки процесса открытым каналом IPC.

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

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

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

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

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

• file <string> Название или путь к исполняемому файлу для запуска.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> Текущий рабочий каталог дочернего процесса.
  • input <string> | <Buffer> | <Uint8Array> Значение, которое будет передано в качестве 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 и Unicode. По умолчанию: 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])

• command <string> Команда для запуска.
• options <Object>
  • cwd <string> Текущий рабочий каталог дочернего процесса.
  • input <string> | <Buffer> | <Uint8Array> Значение, которое будет передано в качестве 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])

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

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

Событие: 'disconnect'

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

Событие: 'error'

Событие 'error' генерируется всякий раз, когда:

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

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

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

Событие: 'exit'

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

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

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

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

См. waitpid(2).

Событие: 'message'

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

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

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

subprocess.channel

• <Объект> Каналы IPC с дочерним процессом.

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

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

• signal <строка>

Метод 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

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

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

subprocess.pid

• <число> Целое число

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

Пример:

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

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

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, эти сообщения могут быть получены через событие process.on('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 и не будут сгенерированы в событии process.on('message') дочернего процесса. Вместо этого такие сообщения генерируются с помощью события process.on('internalMessage') и обрабатываются внутри Node.js. Приложениям следует избегать использования таких сообщений или прослушивания событий 'internalMessage', так как они могут измениться без предварительного уведомления.

Необязательный аргумент sendHandle, который может быть передан в subprocess.send(), предназначен для передачи объекта TCP-сервера или сокета в дочерний процесс. Дочерний процесс получит объект в качестве второго аргумента, переданного в функцию обратного вызова, зарегистрированную на событии process.on('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 существует, так как соединение может быть закрыто в течение времени, необходимого для отправки соединения дочернему процессу.

Примечание: Эта функция использует [JSON.stringify()][] для сериализации message.

subprocess.stderr

• <stream.Readable>

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

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

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

subprocess.stdin

• <stream.Writable>

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

Обратите внимание, что если дочерний процесс ожидает прочитать весь свой ввод, он не продолжит работу, пока этот поток не будет закрыт с помощью 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>

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

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

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

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 недоступен.