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

// OR...
const { exec, spawn } = require('node: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) => {
  // ...
});

// OR...
import { exec, spawn } from 'node: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> | <URL> Текущий рабочий каталог дочернего процесса. По умолчанию: process.cwd().
  • env <Object> Пары ключ-значение переменных окружения. По умолчанию: process.env.
  • encoding <string> По умолчанию: 'utf8'
  • shell <string> Оболочка, в которой выполняется команда. См. разделы Требования к оболочке и Оболочка Windows по умолчанию. По умолчанию: '/bin/sh' в Unix, process.env.ComSpec в Windows.
  • signal <AbortSignal> позволяет прервать дочерний процесс с помощью AbortSignal.
  • 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.
• callback <Function> вызывается с выходными данными при завершении процесса.
  • error <Error>
  • stdout <string> | <Buffer>
  • stderr <string> | <Buffer>
• Возвращает: <ChildProcess>

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

const { exec } = require('node: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.

import { exec } from 'node: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('node: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}`);
});

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

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

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

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

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

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

import { promisify } from 'node:util';
import child_process from 'node:child_process';
const exec = promisify(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('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();

import { exec } from 'node:child_process';
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
  console.error(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 внутри оболочки. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. В качестве строки можно указать другую оболочку. См. разделы Требования к оболочке и Оболочка 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('node:child_process');
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
  if (error) {
    throw error;
  }
  console.log(stdout);
});

import { execFile } from 'node: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('node:util');
const execFile = util.promisify(require('node:child_process').execFile);
async function getVersion() {
  const { stdout } = await execFile('node', ['--version']);
  console.log(stdout);
}
getVersion();

import { promisify } from 'node:util';
import child_process from 'node:child_process';
const execFile = promisify(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('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = execFile('node', ['--version'], { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();

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

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

• modulePath <string> | <URL> Модуль для запуска в дочернем процессе.
• 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' в разделе stdio метода child_process.spawn(). По умолчанию: false.
  • stdio <Array> | <string> См. раздел stdio метода child_process.spawn(). Если этот параметр задан, он переопределяет 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 дочернего процесса.

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

Параметр shell, доступный в child_process.spawn(), не поддерживается методом child_process.fork() и игнорируется, если задан.

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

const { fork } = require('node:child_process');
const process = require('node:process');

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`);
  }, 1_000);
} else {
  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
}

import { fork } from 'node:child_process';
import process from 'node:process';

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`);
  }, 1_000);
} else {
  const controller = new AbortController();
  const { signal } = controller;
  const child = fork(import.meta.url, ['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 внутри оболочки. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. Другую оболочку можно указать в виде строки. См. разделы Требования к оболочке и Оболочка 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,
}; copy

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

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

Значения undefined в env игнорируются.

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

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

import { spawn } from 'node: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('node: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}`);
  }
});

import { spawn } from 'node: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('node:child_process');
const subprocess = spawn('bad_command');

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

import { spawn } from 'node: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('node: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

import { spawn } from 'node: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

const { spawn } = require('node:child_process');
const process = require('node:process');

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

subprocess.unref();

import { spawn } from 'node:child_process';
import process from 'node:process';

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

subprocess.unref();

const { openSync } = require('node:fs');
const { spawn } = require('node:child_process');
const out = openSync('./out.log', 'a');
const err = openSync('./out.log', 'a');

const subprocess = spawn('prg', [], {
  detached: true,
  stdio: [ 'ignore', out, err ],
});

subprocess.unref();

import { openSync } from 'node:fs';
import { spawn } from 'node:child_process';
const out = openSync('./out.log', 'a');
const err = openSync('./out.log', 'a');

const subprocess = spawn('prg', [], {
  detached: true,
  stdio: [ 'ignore', out, err ],
});

subprocess.unref();

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

import { spawn } from 'node:child_process';
import process from 'node: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'] });

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

• file <string> Имя или путь к исполняемому файлу, который нужно запустить.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Значение, которое будет передано в stdin созданного процесса. Если для stdio[0] задано значение 'pipe', передача этого значения переопределит stdio[0].
  • stdio <string> | <Array> Конфигурация stdio дочернего процесса. См. параметр stdio метода child_process.spawn(). По умолчанию 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 и Unicode. По умолчанию: 1024 * 1024.
  • encoding <string> Кодировка, используемая для всех входных и выходных данных stdio. По умолчанию: 'buffer'.
  • windowsHide <boolean> Скрывает окно консоли дочернего процесса, которое обычно создается в системах Windows. По умолчанию: false.
  • shell <boolean> | <string> Если задано значение true, запускает command в командной оболочке. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. Другую оболочку можно указать в виде строки. См. разделы Требования к командной оболочке и Командная оболочка Windows по умолчанию. По умолчанию: false (без оболочки).
• Возвращает: <Buffer> | <string> Вывод команды в stdout.

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

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

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

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

const { execFileSync } = require('node:child_process');

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // Capture stdout and stderr from child process. Overrides the
    // default behavior of streaming child stderr to the parent stderr
    stdio: 'pipe',

    // Use utf8 encoding for stdio pipes
    encoding: 'utf8',
  });

  console.log(stdout);
} catch (err) {
  if (err.code) {
    // Spawning child process failed
    console.error(err.code);
  } else {
    // Child was spawned but exited with non-zero exit code
    // Error contains any stdout and stderr from the child
    const { stdout, stderr } = err;

    console.error({ stdout, stderr });
  }
}

import { execFileSync } from 'node:child_process';

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // Capture stdout and stderr from child process. Overrides the
    // default behavior of streaming child stderr to the parent stderr
    stdio: 'pipe',

    // Use utf8 encoding for stdio pipes
    encoding: 'utf8',
  });

  console.log(stdout);
} catch (err) {
  if (err.code) {
    // Spawning child process failed
    console.error(err.code);
  } else {
    // Child was spawned but exited with non-zero exit code
    // Error contains any stdout and stderr from the child
    const { stdout, stderr } = err;

    console.error({ stdout, stderr });
  }
}

child_process.execSync(command[, options])

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

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

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

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

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

• command <string> Команда для запуска.
• args <string[]> Список строковых аргументов.
• options <Object>
  • cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Значение, которое будет передано в stdin созданного процесса. Если для stdio[0] задано значение 'pipe', передача этого значения переопределит stdio[0].
  • argv0 <string> Явно задает значение argv[0], передаваемое дочернему процессу. Если значение не указано, будет установлено command.
  • stdio <string> | <Array> Конфигурация stdio дочернего процесса. См. параметр stdio метода child_process.spawn(). По умолчанию: '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 и Unicode. По умолчанию: 1024 * 1024.
  • encoding <string> Кодировка, используемая для всех входных и выходных данных stdio. По умолчанию: 'buffer'.
  • shell <boolean> | <string> Если задано значение true, запускает command в командной оболочке. В Unix используется '/bin/sh', а в Windows — process.env.ComSpec. Другую оболочку можно указать в виде строки. См. разделы Требования к командной оболочке и Командная оболочка 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, не передавайте этой функции непроверенные пользовательские данные. Любые данные, содержащие метасимволы командной оболочки, могут использоваться для выполнения произвольных команд.

Событие: 'close'

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

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

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

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

import { spawn } from 'node: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> Ошибка.

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

• Не удалось создать процесс.
• Не удалось завершить процесс.
• Не удалось отправить сообщение дочернему процессу.
• Дочерний процесс был прерван с помощью параметра signal.

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

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

Событие: 'exit'

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

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

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

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

См. waitpid(2).

Событие: 'message'

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

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

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

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

Событие: 'spawn'

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

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

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

subprocess.channel

• Тип: <Object> Канал, представляющий канал IPC для дочернего процесса.

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

subprocess.connected

• Тип: <boolean> Принимает значение false после вызова subprocess.disconnect().

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

subprocess.disconnect()

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

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

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

subprocess.exitCode

• Тип: <integer>

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

subprocess.kill([signal])

• signal <number> | <string>
• Возвращает: <boolean>

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

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

import { spawn } from 'node: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', 'SIGTERM', 'SIGINT' и 'SIGQUIT'; процесс всегда завершается принудительно и без предупреждения (аналогично 'SIGKILL'). Подробнее см. в разделе События сигналов.

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

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

import { spawn } from 'node: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[Symbol.dispose]()

Вызывает subprocess.kill() с аргументом 'SIGTERM'.

subprocess.killed

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

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

subprocess.pid

• Тип: <integer> | <undefined>

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

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

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

import { spawn } from 'node: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('node:child_process');
const process = require('node:process');

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

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

import { spawn } from 'node:child_process';
import process from 'node:process';

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

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

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

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

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

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

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

const { fork } = require('node:child_process');
const forkedProcess = fork(`${__dirname}/sub.js`);

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

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

import { fork } from 'node:child_process';
const forkedProcess = fork(`${import.meta.dirname}/sub.js`);

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

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

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

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

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

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

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

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

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

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

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

const { fork } = require('node:child_process');
const { createServer } = require('node:net');

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

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

import { fork } from 'node:child_process';
import { createServer } from 'node:net';

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

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

const { fork } = require('node:child_process');
const { createServer } = require('node:net');

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 = 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);

import { fork } from 'node:child_process';
import { createServer } from 'node:net';

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

subprocess.signalCode

• Тип: <string> | <null>

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

subprocess.spawnargs

• Тип: <Array>

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

subprocess.spawnfile

• Тип: <string>

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

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

subprocess.stderr

• Тип: <stream.Readable> | <null> | <undefined>

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

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

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

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

subprocess.stdin

• Тип: <stream.Writable> | <null> | <undefined>

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

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

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

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

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

subprocess.stdio

• Тип: <Array>

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

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

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

import assert from 'node:assert';
import fs from 'node:fs';
import child_process from 'node: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> | <null> | <undefined>

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

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

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

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

const subprocess = spawn('ls');

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

import { spawn } from 'node:child_process';

const subprocess = spawn('ls');

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

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

subprocess.unref()

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

const { spawn } = require('node:child_process');
const process = require('node:process');

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

subprocess.unref();

import { spawn } from 'node:child_process';
import process from 'node:process';

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

subprocess.unref();