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

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

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

Методы child_process.exec() и child_process.execFile() дополнительно позволяют указать необязательную функцию-обработчик callback, которая вызывается при завершении дочернего процесса.

Запуск файлов .bat и .cmd в Windows

Значение различия между child_process.exec() и child_process.execFile() может варьироваться в зависимости от платформы. В операционных системах типа Unix (Unix, Linux, macOS) child_process.execFile() может быть более эффективным, так как по умолчанию не запускает оболочку. Однако в Windows файлы .bat и .cmd не являются исполняемыми без терминала и поэтому не могут быть запущены с помощью child_process.execFile(). При работе в Windows файлы .bat и .cmd можно вызывать с помощью child_process.spawn() с установленным параметром shell, с помощью child_process.exec() или путем запуска cmd.exe и передачи файла .bat или .cmd в качестве аргумента (что делают параметр shell и child_process.exec()). В любом случае, если имя файла сценария содержит пробелы, его необходимо заключить в кавычки.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const { exec } = require('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 с stdout и stderr свойствами. Возвращаемый ChildProcess экземпляр прикреплён к Promise как свойство child. В случае ошибки (включая любую ошибку, приводящую к коду завершения, отличному от 0), возвращается отклоненный промис с тем же объектом 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();

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

const { exec } = require('child_process');
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
  console.log(error); // an AbortError
});
controller.abort();

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

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

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

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

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

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

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

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

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

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

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

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

• modulePath <string> Модуль для запуска в дочернем процессе.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущая рабочая директория дочернего процесса.
  • detached <boolean> Подготовить дочерний процесс для независимого выполнения от родительского процесса. Конкретное поведение зависит от платформы, см. options.detached.
  • env <Object> Параметры окружения в формате ключ-значение. По умолчанию: process.env.
  • execPath <string> Исполняемый файл для создания дочернего процесса.
  • execArgv <string[]> Список строковых аргументов, передаваемых исполняемому файлу. По умолчанию: process.execArgv.
  • gid <number> Устанавливает идентификатор группы процесса (см. setgid(2)).
  • serialization <string> Указывает тип сериализации для обмена сообщениями между процессами. Возможные значения: 'json' и 'advanced'. Подробнее см. Расширенная сериализация. По умолчанию: 'json'.
  • signal <AbortSignal> Позволяет закрывать дочерний процесс с помощью AbortSignal.
  • killSignal <string> | <integer> Значение сигнала, используемого при завершении дочернего процесса по таймауту или сигналу прерывания. По умолчанию: 'SIGTERM'.
  • silent <boolean> Если true, stdin, stdout и stderr дочернего процесса будут перенаправлены в родительский, иначе они будут унаследованы от родителя. Подробнее см. опции 'pipe' и 'inherit' для child_process.spawn()'s stdio. По умолчанию: false.
  • stdio <Array> | <string> См. child_process.spawn()'s stdio. При указании этой опции она переопределяет silent. Если используется массив, он должен содержать ровно один элемент со значением 'ipc', иначе будет выброшено исключение. Например, [0, 1, 2, 'ipc'].
  • uid <number> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
  • windowsVerbatimArguments <boolean> На Windows не выполняется цитирование или экранирование аргументов. Игнорируется на Unix. По умолчанию: false.
  • timeout <number> Максимальное время выполнения процесса в миллисекундах. По умолчанию: undefined.
• Возвращает: <ChildProcess>

Метод child_process.fork() — это специальный случай child_process.spawn(), используемый для запуска новых процессов Node.js. Как и child_process.spawn(), возвращает объект ChildProcess. Возвращаемый объект ChildProcess будет иметь встроенный дополнительный канал связи, позволяющий обмениваться сообщениями между родительским и дочерним процессами. Подробнее см. subprocess.send().

Обратите внимание, что запущенные дочерние процессы Node.js независимы от родительского, за исключением канала IPC, созданного между ними. Каждый процесс имеет собственную память и собственные экземпляры V8. Из-за дополнительных затрат ресурсов не рекомендуется запускать большое количество дочерних процессов Node.js.

По умолчанию, child_process.fork() запустит новые экземпляры Node.js, используя process.execPath родительского процесса. Свойство execPath в объекте options позволяет использовать альтернативный путь к исполняемому файлу.

Процессы Node.js, запущенные с пользовательским execPath, будут общаться с родительским процессом, используя дескриптор файла (fd), определяемый переменной среды NODE_CHANNEL_FD в дочернем процессе.

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

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

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

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`);
  }, 1_000);
} else {
  const { fork } = require('child_process');
  const controller = new AbortController();
  const { signal } = controller;
  const child = fork(__filename, ['child'], { signal });
  child.on('error', (err) => {
    // This will be called with err being an AbortError if the controller aborts
  });
  controller.abort(); // Stops the child process
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const { spawn } = require('child_process');
const controller = new AbortController();
const { signal } = controller;
const grep = spawn('grep', ['ssh'], { signal });
grep.on('error', (err) => {
  // This will be called with err being an AbortError if the controller aborts
});
controller.abort(); // Stops the child process

options.detached

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

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

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

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

Пример долго выполняющегося процесса, отсоединением и игнорированием родительских stdio дескрипторов файлов, чтобы проигнорировать завершение родительского:

const { spawn } = require('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'] (по умолчанию)
• 'overlapped': эквивалентно ['overlapped', 'overlapped', 'overlapped']
• 'ignore': эквивалентно ['ignore', 'ignore', 'ignore']
• 'inherit': эквивалентно ['inherit', 'inherit', 'inherit'] или [0, 1, 2]

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

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

2. 'overlapped': Аналогично 'pipe', но флаг FILE_FLAG_OVERLAPPED устанавливается для дескриптора. Это необходимо для перекрывающегося ввода-вывода (overlapped I/O) для стандартных потоков ввода-вывода дочернего процесса. Для более подробной информации см. документацию. Это точно так же, как 'pipe' на системах, отличных от Windows.

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

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

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

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

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

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

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

// Child will use parent's stdios.
spawn('prg', [], { stdio: 'inherit' });

// Spawn child sharing only stderr.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });

// Open an extra fd=4, to interact with programs presenting a
// startd-style interface.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });

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

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

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

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

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

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

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

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

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

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

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

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

child_process.execSync(command[, options])

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

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

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

Класс: ChildProcess

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

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

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

Событие: 'close'

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

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

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

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

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

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

Событие: 'disconnect'

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

Событие: 'error'

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

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

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

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

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

Событие: 'exit'

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

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

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

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

См. waitpid(2).

Событие: 'message'

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

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

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

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

Событие: 'spawn'

Событие 'spawn' срабатывает после успешного запуска дочернего процесса. Если дочерний процесс не был запущен успешно, событие 'spawn' не срабатывает, а срабатывает событие 'error'.

Если событие срабатывает, оно происходит до всех других событий и до получения любых данных через stdout или stderr.

Событие 'spawn' срабатывает независимо от того, возникла ли ошибка внутри запущенного процесса. Например, если bash some-command запускается успешно, событие 'spawn' срабатывает, хотя bash может не удаться запустить some-command. Это ограничение также относится к использованию { shell: true }.

subprocess.channel

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

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

subprocess.channel.ref()

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

subprocess.channel.unref()

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

subprocess.connected

• <логическое значение> Устанавливается в значение false после вызова subprocess.disconnect().

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

subprocess.disconnect()

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

Событие 'disconnect' будет выведено, когда в процессе обработки нет сообщений. Чаще всего оно срабатывает сразу после вызова subprocess.disconnect().

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

subprocess.exitCode

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

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

subprocess.kill([signal])

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

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

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

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

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

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

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

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

В Windows, где POSIX-сигналы отсутствуют, аргумент signal будет проигнорирован, и процесс будет завершен принудительно и внезапно (аналогично 'SIGKILL'). См. События сигналов для получения более подробной информации.

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

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

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

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

subprocess.killed

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

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

subprocess.pid

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

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

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

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

subprocess.ref()

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

subprocess.signalCode

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

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

subprocess.spawnargs

• <Массив>

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

subprocess.spawnfile

• <строка>

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

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

subprocess.stderr

• <stream.Readable>

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

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

subprocess.stderr является псевдонимом для subprocess.stdio[2].

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

subprocess.stdin

• <stream.Writable>

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

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

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

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

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

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.stdio может быть undefined, если дочерний процесс не был успешно запущен.

subprocess.stdout

• <stream.Readable>

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

subprocess.unref()

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

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

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

subprocess.unref();

maxBuffer и Юникод

Опция 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().