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

Исходный код: lib/child_process.js

Модуль 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.error(`stderr: ${data}`);
});

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

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

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

Метод 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.error(data.toString());
});

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

// OR...
const { exec, spawn } = require('child_process');
exec('my.bat', (err, stdout, stderr) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(stdout);
});

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• modulePath <string> Модуль для выполнения в дочернем процессе.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> Текущая рабочая директория дочернего процесса.
  • detached <boolean> Подготовить дочерний процесс для независимого выполнения от родительского. Конкретное поведение зависит от платформы, см. options.detached.
  • env <Object> Параметры окружения в формате ключ-значение. По умолчанию: process.env.
  • execPath <string> Исполняемый файл для создания дочернего процесса.
  • execArgv <string[]> Список строковых аргументов, передаваемых исполняемому файлу. По умолчанию: process.execArgv.
  • serialization <string> Указывает тип сериализации для обмена сообщениями между процессами. Возможные значения: 'json' и 'advanced'. Подробнее см. Расширенная сериализация. По умолчанию: 'json'.
  • 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 в дочернем процессе.

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

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

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

• command <string> Команда для выполнения.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> Текущая рабочая директория дочернего процесса.
  • env <Object> Параметры окружения в формате ключ-значение. По умолчанию: process.env.
  • argv0 <string> Явно задать значение argv[0] для дочернего процесса. Если не указано, будет установлено значение command.
  • stdio <Array> | <string> Настройка stdio дочернего процесса (см. options.stdio).
  • detached <boolean> Подготовить дочерний процесс для независимого выполнения от родительского. Конкретное поведение зависит от платформы, см. options.detached.
  • uid <number> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
  • gid <number> Устанавливает идентификатор группы процесса (см. setgid(2)).
  • serialization <string> Указывает тип сериализации для обмена сообщениями между процессами. Возможные значения: 'json' и 'advanced'. Подробнее см. Расширенная сериализация. По умолчанию: 'json'.
  • shell <boolean> | <string> Если true, выполняет command внутри оболочки. Использует '/bin/sh' на Unix и process.env.ComSpec на Windows. Можно указать другую оболочку в качестве строки. См. Требования к оболочке и Значение оболочки по умолчанию на Windows. По умолчанию: false (без оболочки).
  • windowsVerbatimArguments <boolean> На Windows не происходит цитирования или экранирования аргументов. Игнорируется на Unix. Автоматически устанавливается в true, когда shell задано и является CMD. По умолчанию: 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.error(`stderr: ${data}`);
});

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

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

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

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

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

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

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

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

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

Пример проверки на ошибку spawn:

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

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

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

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

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, 1 и 2, также доступны как subprocess.stdin, subprocess.stdout и subprocess.stderr соответственно.

2. 'ipc': Создаёт канал IPC для передачи сообщений/дескрипторов файлов между родительским и дочерним процессами. У объекта ChildProcess может быть не более одного fd канала IPC. Установка этой опции активирует метод 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, 1 и 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: Используется значение по умолчанию. Для fd stdio 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 issue 7381.

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

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

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

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

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

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

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

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

Класс: ChildProcess

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

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

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

Событие: 'close'

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

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

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

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

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

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

Событие: 'disconnect'

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

Событие: 'error'

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

Событие 'error' срабатывает, когда:

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

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

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

Событие: 'exit'

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

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

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

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

См. waitpid(2).

Событие: 'message'

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

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

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

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

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.exitCode

• <целое>

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

subprocess.kill([signal])

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

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

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

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

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

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

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

См. kill(2) для справки.

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

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

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

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

subprocess.killed

• <булево> Устанавливается в 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.ref()

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

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

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

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

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

• message <Объект>
• sendHandle <Дескриптор>
• options <Объект> Аргумент options, если он есть, это объект, используемый для параметризации отправки определённых типов дескрипторов. options поддерживает следующие свойства:
  • keepOpen <булево> Значение, которое можно использовать при передаче экземпляров net.Socket. При значении true, сокет будет оставаться открытым в процессе отправки. По умолчанию: false.
• callback <Функция>
• Возвращает: <булево>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Дочерний процесс получит объект сервера как:

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

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

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

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

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

const { fork } = require('child_process');
const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);

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

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

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

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

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

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

subprocess.signalCode

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

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

subprocess.spawnargs

• <массив>

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

subprocess.spawnfile

• <строка>

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

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

• <массив>

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

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

const subprocess = spawn('ls');

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

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 и Юникод

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

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

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

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

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

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

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

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