Запуск файлов .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';
import { once } from 'node:events';
const ls = spawn('ls', ['-lh', '/usr']);

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

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

const [code] = await once(ls, 'close');
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';
import { once } from 'node:events';
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}`);
});

const [code] = await once(ls, 'close');
console.log(`child process close all stdio 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).

Если code имеет значение null из-за завершения по сигналу, можно использовать util.convertProcessSignalToExitCode(), чтобы преобразовать сигнал в код завершения POSIX.

Событие: '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.exitCode будет иметь значение null, а свойству subprocess.signalCode будет присвоено значение. Чтобы получить соответствующий код завершения POSIX, используйте util.convertProcessSignalToExitCode(subprocess.signalCode).

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'}. Сообщения, свойство cmd которых содержит префикс NODE_, зарезервированы для внутреннего использования ядром 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.exitCode будет иметь значение null. Чтобы получить соответствующий код завершения POSIX, используйте util.convertProcessSignalToExitCode(subprocess.signalCode).

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