Node.js v26.0.0 Dokumentation

Child-Prozess#

Das node:child_process-Modul bietet die Möglichkeit, Unterprozesse auf eine Weise zu starten, die popen(3) ähnlich, aber nicht identisch ist. Diese Funktionalität wird hauptsächlich durch die Funktion child_process.spawn() bereitgestellt.

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

Standardmäßig werden Pipes für stdin, stdout und stderr zwischen dem übergeordneten Node.js-Prozess und dem gestarteten Unterprozess eingerichtet. Diese Pipes haben eine begrenzte (und plattformspezifische) Kapazität. Wenn der Unterprozess mehr Daten in stdout schreibt, als dieses Limit ohne die Ausgabe zu erfassen, blockiert der Unterprozess und wartet darauf, dass der Pipe-Puffer mehr Daten akzeptiert. Dies ist identisch mit dem Verhalten von Pipes in der Shell. Verwenden Sie die Option { stdio: 'ignore' }, wenn die Ausgabe nicht verbraucht wird.

Die Befehlssuche wird mithilfe der Umgebungsvariablen options.env.PATH durchgeführt, wenn env im options-Objekt enthalten ist. Andernfalls wird process.env.PATH verwendet. Wenn options.env ohne PATH gesetzt ist, erfolgt die Suche unter Unix in einem Standard-Suchpfad von /usr/bin:/bin (siehe das Handbuch Ihres Betriebssystems für execvpe/execvp), unter Windows wird die Umgebungsvariable PATH des aktuellen Prozesses verwendet.

Unter Windows sind Umgebungsvariablen nicht Groß-/Kleinschreibung-sensitiv. Node.js sortiert die env-Schlüssel lexikografisch und verwendet den ersten, der nicht Groß-/Kleinschreibung-sensitiv übereinstimmt. Nur der erste Eintrag (in lexikografischer Reihenfolge) wird an den Unterprozess übergeben. Dies kann unter Windows zu Problemen führen, wenn Objekte an die env-Option übergeben werden, die mehrere Varianten desselben Schlüssels haben, wie PATH und Path.

Die Methode child_process.spawn() startet den Child-Prozess asynchron, ohne die Node.js-Ereignisschleife zu blockieren. Die Funktion child_process.spawnSync() bietet eine äquivalente Funktionalität auf synchrone Weise, die die Ereignisschleife blockiert, bis der gestartete Prozess entweder beendet wird oder terminiert ist.

Zur Vereinfachung bietet das node:child_process-Modul eine Reihe synchroner und asynchroner Alternativen zu child_process.spawn() und child_process.spawnSync(). Jede dieser Alternativen ist auf child_process.spawn() oder child_process.spawnSync() aufgebaut.

• child_process.exec(): startet eine Shell und führt einen Befehl innerhalb dieser Shell aus, wobei stdout und stderr nach Abschluss an eine Callback-Funktion übergeben werden.
• child_process.execFile(): ähnlich wie child_process.exec(), außer dass es den Befehl standardmäßig direkt startet, ohne zuerst eine Shell zu starten.
• child_process.fork(): startet einen neuen Node.js-Prozess und ruft ein bestimmtes Modul mit einem eingerichteten IPC-Kommunikationskanal auf, der das Senden von Nachrichten zwischen übergeordnetem und untergeordnetem Prozess ermöglicht.
• child_process.execSync(): eine synchrone Version von child_process.exec(), die die Node.js-Ereignisschleife blockiert.
• child_process.execFileSync(): eine synchrone Version von child_process.execFile(), die die Node.js-Ereignisschleife blockiert.

Für bestimmte Anwendungsfälle, wie die Automatisierung von Shell-Skripten, können die synchronen Gegenstücke bequemer sein. In vielen Fällen können die synchronen Methoden jedoch erhebliche Auswirkungen auf die Leistung haben, da sie die Ereignisschleife blockieren, während die gestarteten Prozesse abgeschlossen werden.

Asynchrone Prozesserstellung#

Die Methoden child_process.spawn(), child_process.fork(), child_process.exec() und child_process.execFile() folgen alle dem idiomatischen asynchronen Programmiermuster, das für andere Node.js-APIs typisch ist.

Jede der Methoden gibt eine ChildProcess-Instanz zurück. Diese Objekte implementieren die Node.js EventEmitter-API, wodurch der übergeordnete Prozess Listener-Funktionen registrieren kann, die aufgerufen werden, wenn bestimmte Ereignisse während des Lebenszyklus des Child-Prozesses auftreten.

Die Methoden child_process.exec() und child_process.execFile() ermöglichen zusätzlich die Angabe einer optionalen callback-Funktion, die aufgerufen wird, wenn der Child-Prozess beendet wird.

Starten von .bat- und .cmd-Dateien unter Windows#

Die Bedeutung der Unterscheidung zwischen child_process.exec() und child_process.execFile() kann je nach Plattform variieren. Auf Unix-artigen Betriebssystemen (Unix, Linux, macOS) kann child_process.execFile() effizienter sein, da es standardmäßig keine Shell startet. Unter Windows sind .bat- und .cmd-Dateien jedoch ohne ein Terminal nicht eigenständig ausführbar und können daher nicht mit child_process.execFile() gestartet werden. Wenn unter Windows ausgeführt, können .bat- und .cmd-Dateien aufgerufen werden durch

• Verwendung von child_process.spawn() mit gesetzter shell-Option (nicht empfohlen, siehe DEP0190), oder
• Verwendung von child_process.exec(), oder
• Starten von cmd.exe und Übergabe der .bat- oder .cmd-Datei als Argument (was child_process.exec() intern tut).

In jedem Fall muss der Skriptdateiname in Anführungszeichen gesetzt werden, wenn er Leerzeichen enthält.

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

exec('my.bat', (err, stdout, stderr) => { /* ... */ });

// Or, spawning cmd.exe directly:
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

// If the script filename contains spaces, it needs to be quoted
exec('"my script.cmd" a b', (err, stdout, stderr) => { /* ... */ });
import { exec, spawn } from 'node:child_process';

exec('my.bat', (err, stdout, stderr) => { /* ... */ });

// Or, spawning cmd.exe directly:
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

// If the script filename contains spaces, it needs to be quoted
exec('"my script.cmd" a b', (err, stdout, stderr) => { /* ... */ });
copy

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

• command <string> Der auszuführende Befehl, mit durch Leerzeichen getrennten Argumenten.
• options <Object>
  • cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses. Standard: process.cwd().
  • env <Object> Schlüssel-Wert-Paare der Umgebung. Standard: process.env.
  • encoding <string> Standard: 'utf8'
  • shell <string> Shell, mit der der Befehl ausgeführt werden soll. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: '/bin/sh' unter Unix, process.env.ComSpec unter Windows.
  • signal <AbortSignal> ermöglicht das Abbrechen des Child-Prozesses mit einem AbortSignal.
  • timeout <number> Standard: 0
  • maxBuffer <number> Größte Datenmenge in Bytes, die auf stdout oder stderr erlaubt ist. Bei Überschreitung wird der Child-Prozess beendet und jede Ausgabe abgeschnitten. Siehe Warnung unter maxBuffer und Unicode. Standard: 1024 * 1024.
  • killSignal <string> | <integer> Standard: 'SIGTERM'
  • uid <number> Setzt die Benutzeridentität des Prozesses (siehe setuid(2)).
  • gid <number> Setzt die Gruppenidentität des Prozesses (siehe setgid(2)).
  • windowsHide <boolean> Verbirgt das Konsolenfenster des Unterprozesses, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
• callback <Function> wird mit der Ausgabe aufgerufen, wenn der Prozess beendet wird.
  • error <Error>
  • stdout <string> | <Buffer>
  • stderr <string> | <Buffer>
• Gibt zurück: <ChildProcess>

Startet eine Shell und führt dann den command innerhalb dieser Shell aus, wobei alle generierten Ausgaben gepuffert werden. Die an die exec-Funktion übergebene command-Zeichenfolge wird direkt von der Shell verarbeitet, und Sonderzeichen (variieren je nach Shell) müssen entsprechend behandelt werden.

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

Übergeben Sie niemals unsanitisierte Benutzereingaben an diese Funktion. Jede Eingabe, die Shell-Metazeichen enthält, kann dazu verwendet werden, eine beliebige Befehlsausführung auszulösen.

Wenn eine callback-Funktion bereitgestellt wird, wird diese mit den Argumenten (error, stdout, stderr) aufgerufen. Im Erfolgsfall ist error null. Im Fehlerfall ist error eine Instanz von Error. Die Eigenschaft error.code ist der Exit-Code des Prozesses. Nach Konvention zeigt jeder Exit-Code außer 0 einen Fehler an. error.signal ist das Signal, das den Prozess beendet hat.

Die an den Callback übergebenen stdout- und stderr-Argumente enthalten die stdout- und stderr-Ausgabe des Child-Prozesses. Standardmäßig dekodiert Node.js die Ausgabe als UTF-8 und übergibt Strings an den Callback. Die Option encoding kann verwendet werden, um die Zeichenkodierung anzugeben, die zum Dekodieren der stdout- und stderr-Ausgabe verwendet wird. Wenn encoding 'buffer' oder eine nicht erkannte Zeichenkodierung ist, werden stattdessen Buffer-Objekte an den Callback übergeben.

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

Wenn timeout größer als 0 ist, sendet der übergeordnete Prozess das durch die Eigenschaft killSignal identifizierte Signal (der Standardwert ist 'SIGTERM'), wenn der Child-Prozess länger als timeout Millisekunden läuft.

Im Gegensatz zum POSIX-Systemaufruf exec(3) ersetzt child_process.exec() den bestehenden Prozess nicht und verwendet eine Shell, um den Befehl auszuführen.

Wenn diese Methode als ihre util.promisify()-te Version aufgerufen wird, gibt sie ein Promise für ein Object mit stdout- und stderr-Eigenschaften zurück. Die zurückgegebene ChildProcess-Instanz ist als child-Eigenschaft an das Promise angehängt. Im Fehlerfall (einschließlich jedes Fehlers, der zu einem Exit-Code ungleich 0 führt) wird ein rejected Promise zurückgegeben, mit demselben error-Objekt, das im Callback gegeben wurde, aber mit zwei zusätzlichen Eigenschaften stdout und 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();
copy

Wenn die Option signal aktiviert ist, ist der Aufruf von .abort() für den entsprechenden AbortController ähnlich dem Aufruf von .kill() für den Child-Prozess, außer dass der an den Callback übergebene Fehler ein AbortError ist.

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

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

• file <string> Der Name oder Pfad der auszuführenden Datei.
• args <string[]> Liste der String-Argumente.
• options <Object>
  • cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses.
  • env <Object> Schlüssel-Wert-Paare der Umgebung. Standard: process.env.
  • encoding <string> Standard: 'utf8'
  • timeout <number> Standard: 0
  • maxBuffer <number> Größte Datenmenge in Bytes, die auf stdout oder stderr erlaubt ist. Bei Überschreitung wird der Child-Prozess beendet und jede Ausgabe abgeschnitten. Siehe Warnung unter maxBuffer und Unicode. Standard: 1024 * 1024.
  • killSignal <string> | <integer> Standard: 'SIGTERM'
  • uid <number> Setzt die Benutzeridentität des Prozesses (siehe setuid(2)).
  • gid <number> Setzt die Gruppenidentität des Prozesses (siehe setgid(2)).
  • windowsHide <boolean> Verbirgt das Konsolenfenster des Unterprozesses, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
  • windowsVerbatimArguments <boolean> Unter Windows erfolgt kein Quoting oder Escaping von Argumenten. Unter Unix ignoriert. Standard: false.
  • shell <boolean> | <string> Wenn true, wird der command innerhalb einer Shell ausgeführt. Verwendet '/bin/sh' unter Unix und process.env.ComSpec unter Windows. Eine andere Shell kann als String angegeben werden. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: false (keine Shell).
  • signal <AbortSignal> ermöglicht das Abbrechen des Child-Prozesses mit einem AbortSignal.
• callback <Function> Wird mit der Ausgabe aufgerufen, wenn der Prozess beendet wird.
  • error <Error>
  • stdout <string> | <Buffer>
  • stderr <string> | <Buffer>
• Gibt zurück: <ChildProcess>

Die Funktion child_process.execFile() ist child_process.exec() ähnlich, außer dass sie standardmäßig keine Shell startet. Vielmehr wird die angegebene ausführbare file direkt als neuer Prozess gestartet, wodurch sie etwas effizienter ist als child_process.exec().

Dieselben Optionen wie bei child_process.exec() werden unterstützt. Da keine Shell gestartet wird, werden Verhaltensweisen wie I/O-Umleitung und Dateiglobbing nicht unterstützt.

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

Die an den Callback übergebenen stdout- und stderr-Argumente enthalten die stdout- und stderr-Ausgabe des Child-Prozesses. Standardmäßig dekodiert Node.js die Ausgabe als UTF-8 und übergibt Strings an den Callback. Die Option encoding kann verwendet werden, um die Zeichenkodierung anzugeben, die zum Dekodieren der stdout- und stderr-Ausgabe verwendet wird. Wenn encoding 'buffer' oder eine nicht erkannte Zeichenkodierung ist, werden stattdessen Buffer-Objekte an den Callback übergeben.

Wenn diese Methode als ihre util.promisify()-te Version aufgerufen wird, gibt sie ein Promise für ein Object mit stdout- und stderr-Eigenschaften zurück. Die zurückgegebene ChildProcess-Instanz ist als child-Eigenschaft an das Promise angehängt. Im Fehlerfall (einschließlich jedes Fehlers, der zu einem Exit-Code ungleich 0 führt) wird ein rejected Promise zurückgegeben, mit demselben error-Objekt, das im Callback gegeben wurde, aber mit zwei zusätzlichen Eigenschaften stdout und 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();
copy

Wenn die Option shell aktiviert ist, übergeben Sie keine unsanitisierte Benutzereingabe an diese Funktion. Jede Eingabe, die Shell-Metazeichen enthält, kann verwendet werden, um eine beliebige Befehlsausführung auszulösen.

Wenn die Option signal aktiviert ist, ist der Aufruf von .abort() für den entsprechenden AbortController ähnlich dem Aufruf von .kill() für den Child-Prozess, außer dass der an den Callback übergebene Fehler ein AbortError ist.

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

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

• modulePath <string> | <URL> Das im Child auszuführende Modul.
• args <string[]> Liste der String-Argumente.
• options <Object>
  • cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses.
  • detached <boolean> Bereitet den Child-Prozess darauf vor, unabhängig von seinem übergeordneten Prozess zu laufen. Das spezifische Verhalten hängt von der Plattform ab (siehe options.detached).
  • env <Object> Schlüssel-Wert-Paare der Umgebung. Standard: process.env.
  • execPath <string> Ausführbare Datei, die zum Erstellen des Child-Prozesses verwendet wird.
  • execArgv <string[]> Liste der String-Argumente, die an die ausführbare Datei übergeben werden. Standard: process.execArgv.
  • gid <number> Setzt die Gruppenidentität des Prozesses (siehe setgid(2)).
  • serialization <string> Gibt die Art der Serialisierung an, die zum Senden von Nachrichten zwischen Prozessen verwendet wird. Mögliche Werte sind 'json' und 'advanced'. Siehe Erweiterte Serialisierung für weitere Details. Standard: 'json'.
  • signal <AbortSignal> Ermöglicht das Schließen des Child-Prozesses mit einem AbortSignal.
  • killSignal <string> | <integer> Der Signalwert, der verwendet wird, wenn der gestartete Prozess durch Timeout oder Abort-Signal beendet wird. Standard: 'SIGTERM'.
  • silent <boolean> Wenn true, werden stdin, stdout und stderr des Child-Prozesses an den übergeordneten Prozess weitergeleitet, andernfalls werden sie vom übergeordneten Prozess geerbt. Weitere Details finden Sie in den Optionen 'pipe' und 'inherit' für child_process.spawn()'s stdio. Standard: false.
  • stdio <Array> | <string> Siehe child_process.spawn()'s stdio. Wenn diese Option angegeben wird, überschreibt sie silent. Wenn die Array-Variante verwendet wird, muss sie genau ein Element mit dem Wert 'ipc' enthalten, andernfalls wird ein Fehler ausgelöst. Zum Beispiel [0, 1, 2, 'ipc'].
  • uid <number> Setzt die Benutzeridentität des Prozesses (siehe setuid(2)).
  • windowsVerbatimArguments <boolean> Unter Windows erfolgt kein Quoting oder Escaping von Argumenten. Unter Unix ignoriert. Standard: false.
  • timeout <number> Die maximale Laufzeit des Prozesses in Millisekunden. Standard: undefined.
• Gibt zurück: <ChildProcess>

Die Methode child_process.fork() ist ein Sonderfall von child_process.spawn(), der speziell zum Starten neuer Node.js-Prozesse verwendet wird. Wie bei child_process.spawn() wird ein ChildProcess-Objekt zurückgegeben. Das zurückgegebene ChildProcess verfügt über einen zusätzlichen integrierten Kommunikationskanal, der das Hin- und Herschicken von Nachrichten zwischen dem übergeordneten und untergeordneten Prozess ermöglicht. Details finden Sie unter subprocess.send().

Beachten Sie, dass gestartete Node.js-Child-Prozesse unabhängig vom übergeordneten Prozess sind, mit Ausnahme des IPC-Kommunikationskanals, der zwischen beiden eingerichtet wird. Jeder Prozess verfügt über seinen eigenen Speicher mit eigenen V8-Instanzen. Aufgrund der erforderlichen zusätzlichen Ressourcenzuweisungen wird das Starten einer großen Anzahl von Node.js-Child-Prozessen nicht empfohlen.

Standardmäßig startet child_process.fork() neue Node.js-Instanzen unter Verwendung des process.execPath des übergeordneten Prozesses. Die Eigenschaft execPath im options-Objekt ermöglicht die Verwendung eines alternativen Ausführungspfads.

Node.js-Prozesse, die mit einem benutzerdefinierten execPath gestartet werden, kommunizieren mit dem übergeordneten Prozess über den Dateideskriptor (fd), der durch die Umgebungsvariable NODE_CHANNEL_FD im Child-Prozess identifiziert wird.

Im Gegensatz zum POSIX-Systemaufruf fork(2) klont child_process.fork() den aktuellen Prozess nicht.

Die in child_process.spawn() verfügbare Option shell wird von child_process.fork() nicht unterstützt und wird ignoriert, wenn sie gesetzt ist.

Wenn die Option signal aktiviert ist, ist der Aufruf von .abort() für den entsprechenden AbortController ähnlich dem Aufruf von .kill() für den Child-Prozess, außer dass der an den Callback übergebene Fehler ein AbortError ist.

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
}
copy

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

• command <string> Der auszuführende Befehl.
• args <string[]> Liste der String-Argumente.
• options <Object>
  • cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses.
  • env <Object> Schlüssel-Wert-Paare der Umgebung. Standard: process.env.
  • argv0 <string> Setzt den Wert von argv[0] explizit, der an den Child-Prozess gesendet wird. Dieser wird auf command gesetzt, wenn nicht anders angegeben.
  • stdio <Array> | <string> stdio-Konfiguration des Child (siehe options.stdio).
  • detached <boolean> Bereitet den Child-Prozess darauf vor, unabhängig von seinem übergeordneten Prozess zu laufen. Das spezifische Verhalten hängt von der Plattform ab (siehe options.detached).
  • uid <number> Setzt die Benutzeridentität des Prozesses (siehe setuid(2)).
  • gid <number> Setzt die Gruppenidentität des Prozesses (siehe setgid(2)).
  • serialization <string> Gibt die Art der Serialisierung an, die zum Senden von Nachrichten zwischen Prozessen verwendet wird. Mögliche Werte sind 'json' und 'advanced'. Siehe Erweiterte Serialisierung für weitere Details. Standard: 'json'.
  • shell <boolean> | <string> Wenn true, wird der command innerhalb einer Shell ausgeführt. Verwendet '/bin/sh' unter Unix und process.env.ComSpec unter Windows. Eine andere Shell kann als String angegeben werden. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: false (keine Shell).
  • windowsVerbatimArguments <boolean> Unter Windows erfolgt kein Quoting oder Escaping von Argumenten. Unter Unix ignoriert. Dies wird automatisch auf true gesetzt, wenn shell angegeben und CMD ist. Standard: false.
  • windowsHide <boolean> Verbirgt das Konsolenfenster des Unterprozesses, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
  • signal <AbortSignal> ermöglicht das Abbrechen des Child-Prozesses mit einem AbortSignal.
  • timeout <number> Die maximale Laufzeit des Prozesses in Millisekunden. Standard: undefined.
  • killSignal <string> | <integer> Der Signalwert, der verwendet wird, wenn der gestartete Prozess durch Timeout oder Abort-Signal beendet wird. Standard: 'SIGTERM'.
• Gibt zurück: <ChildProcess>

Die Methode child_process.spawn() startet einen neuen Prozess mit dem angegebenen command und den Kommandozeilenargumenten in args. Wenn ausgelassen, ist args standardmäßig ein leeres Array.

Wenn die Option shell aktiviert ist, übergeben Sie keine unsanitisierte Benutzereingabe an diese Funktion. Jede Eingabe, die Shell-Metazeichen enthält, kann verwendet werden, um eine beliebige Befehlsausführung auszulösen.

Ein drittes Argument kann verwendet werden, um zusätzliche Optionen mit diesen Standardwerten anzugeben.

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

Verwenden Sie cwd, um das Arbeitsverzeichnis anzugeben, aus dem der Prozess gestartet wird. Wenn nicht angegeben, wird standardmäßig das aktuelle Arbeitsverzeichnis geerbt. Wenn angegeben, aber der Pfad nicht existiert, gibt der Child-Prozess einen ENOENT-Fehler aus und beendet sich sofort. ENOENT wird auch ausgegeben, wenn der Befehl nicht existiert.

Verwenden Sie env, um Umgebungsvariablen anzugeben, die für den neuen Prozess sichtbar sind. Der Standardwert ist process.env.

undefined-Werte in env werden ignoriert.

Beispiel für das Ausführen von ls -lh /usr, Erfassung von stdout, stderr und dem Exit-Code

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

Beispiel: Eine sehr aufwendige Methode, ps ax | grep ssh auszuführen

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

Beispiel für die Überprüfung eines fehlgeschlagenen spawn-Vorgangs

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.');
});
copy

Bestimmte Plattformen (macOS, Linux) verwenden den Wert von argv[0] als Prozesstitel, während andere (Windows, SunOS) command verwenden.

Node.js überschreibt argv[0] beim Start mit process.execPath, sodass process.argv[0] in einem Node.js-Child-Prozess nicht dem von der Eltern-Shell an spawn übergebenen argv0-Parameter entspricht. Rufen Sie es stattdessen mit der Eigenschaft process.argv0 ab.

Wenn die Option signal aktiviert ist, ist der Aufruf von .abort() für den entsprechenden AbortController ähnlich dem Aufruf von .kill() für den Child-Prozess, außer dass der an den Callback übergebene Fehler ein AbortError ist.

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
copy

options.detached#

Unter Windows ermöglicht das Setzen von options.detached auf true, dass der Child-Prozess nach Beendigung des übergeordneten Prozesses weiterläuft. Der Child-Prozess erhält ein eigenes Konsolenfenster. Einmal für einen Child-Prozess aktiviert, kann dies nicht mehr deaktiviert werden.

Auf Nicht-Windows-Plattformen wird der Child-Prozess, wenn options.detached auf true gesetzt ist, zum Anführer einer neuen Prozessgruppe und Sitzung gemacht. Child-Prozesse können nach dem Beenden des übergeordneten Prozesses weiterlaufen, unabhängig davon, ob sie detached sind oder nicht. Weitere Informationen finden Sie unter setsid(2).

Standardmäßig wartet der übergeordnete Prozess darauf, dass der detached Child-Prozess beendet wird. Um zu verhindern, dass der übergeordnete Prozess auf das Beenden eines bestimmten subprocess wartet, verwenden Sie die Methode subprocess.unref(). Dadurch wird die Ereignisschleife des übergeordneten Prozesses den Child-Prozess nicht in ihre Referenzzählung aufnehmen, wodurch der übergeordnete Prozess unabhängig vom Child-Prozess beendet werden kann, es sei denn, es besteht ein eingerichteter IPC-Kanal zwischen dem Child- und dem übergeordneten Prozess.

Bei Verwendung der Option detached zum Starten eines langlebigen Prozesses bleibt der Prozess nach dem Beenden des übergeordneten Prozesses nicht im Hintergrund aktiv, es sei denn, er wird mit einer stdio-Konfiguration versehen, die nicht mit dem übergeordneten Prozess verbunden ist. Wenn das stdio des übergeordneten Prozesses geerbt wird, bleibt der Child-Prozess an das steuernde Terminal gebunden.

Beispiel für einen langlebigen Prozess, indem er detached wird und auch die stdio-Dateideskriptoren des übergeordneten Prozesses ignoriert werden, um die Beendigung des übergeordneten Prozesses zu ignorieren.

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

Alternativ kann man die Ausgabe des Child-Prozesses in Dateien umleiten.

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

options.stdio#

Die Option options.stdio wird verwendet, um die Pipes zu konfigurieren, die zwischen dem übergeordneten und dem Child-Prozess eingerichtet werden. Standardmäßig werden stdin, stdout und stderr des Child an die entsprechenden subprocess.stdin-, subprocess.stdout- und subprocess.stderr-Streams auf dem ChildProcess-Objekt umgeleitet. Dies ist gleichbedeutend mit dem Setzen von options.stdio auf ['pipe', 'pipe', 'pipe'].

Zur Vereinfachung kann options.stdio einer der folgenden Strings sein:

• 'pipe': gleichbedeutend mit ['pipe', 'pipe', 'pipe'] (der Standardwert)
• 'overlapped': gleichbedeutend mit ['overlapped', 'overlapped', 'overlapped']
• 'ignore': gleichbedeutend mit ['ignore', 'ignore', 'ignore']
• 'inherit': gleichbedeutend mit ['inherit', 'inherit', 'inherit'] oder [0, 1, 2]

Andernfalls ist der Wert von options.stdio ein Array, bei dem jeder Index einem Dateideskriptor (fd) im Child entspricht. Die fds 0, 1 und 2 entsprechen stdin, stdout bzw. stderr. Zusätzliche fds können angegeben werden, um zusätzliche Pipes zwischen übergeordnetem und untergeordnetem Prozess zu erstellen. Der Wert ist einer der folgenden:

1. 'pipe': Erstellt eine Pipe zwischen dem Child-Prozess und dem übergeordneten Prozess. Das übergeordnete Ende der Pipe wird dem übergeordneten Prozess als Eigenschaft des child_process-Objekts als subprocess.stdio[fd] zugänglich gemacht. Für die fds 0, 1 und 2 erstellte Pipes sind auch als subprocess.stdin, subprocess.stdout bzw. subprocess.stderr verfügbar. Dies sind keine echten Unix-Pipes, und daher kann der Child-Prozess sie nicht über ihre Deskriptordateien verwenden, z.B. /dev/fd/2 oder /dev/stdout.

2. 'overlapped': Wie 'pipe', außer dass das Flag FILE_FLAG_OVERLAPPED am Handle gesetzt ist. Dies ist für überlappende E/A auf den stdio-Handles des Child-Prozesses erforderlich. Weitere Details finden Sie in den Dokumenten. Dies ist unter Nicht-Windows-Systemen genau dasselbe wie 'pipe'.

3. 'ipc': Erstellt einen IPC-Kanal zum Übergeben von Nachrichten/Dateideskriptoren zwischen übergeordnetem und untergeordnetem Prozess. Ein ChildProcess darf höchstens einen IPC-Stdio-Dateideskriptor haben. Das Setzen dieser Option aktiviert die Methode subprocess.send(). Wenn der Child-Prozess eine Node.js-Instanz ist, ermöglicht das Vorhandensein eines IPC-Kanals die Methoden process.send() und process.disconnect() sowie die Ereignisse 'disconnect' und 'message' innerhalb des Child-Prozesses.

   Der Zugriff auf den IPC-Kanal-Dateideskriptor auf andere Weise als über process.send() oder die Verwendung des IPC-Kanals mit einem Child-Prozess, der keine Node.js-Instanz ist, wird nicht unterstützt.

4. 'ignore': Weist Node.js an, den Dateideskriptor (fd) im Child zu ignorieren. Während Node.js für die von ihm gestarteten Prozesse immer die fds 0, 1 und 2 öffnet, bewirkt das Setzen des fd auf 'ignore', dass Node.js /dev/null öffnet und es an den fd des Child anfügt.

5. 'inherit': Leitet den entsprechenden stdio-Stream an/von dem übergeordneten Prozess weiter. In den ersten drei Positionen entspricht dies process.stdin, process.stdout bzw. process.stderr. In jeder anderen Position entspricht es 'ignore'.

6. <Stream>-Objekt: Teilt einen lesbaren oder schreibbaren Stream, der auf ein TTY, eine Datei, einen Socket oder eine Pipe verweist, mit dem Child-Prozess. Der zugrunde liegende Dateideskriptor des Streams wird im Child-Prozess auf den Dateideskriptor dupliziert, der dem Index im stdio-Array entspricht. Der Stream muss einen zugrunde liegenden Deskriptor haben (Dateistreams beginnen erst, wenn das Ereignis 'open' aufgetreten ist). HINWEIS: Obwohl es technisch möglich ist, stdin als schreibbar oder stdout/stderr als lesbar zu übergeben, wird dies nicht empfohlen. Lesbare und schreibbare Streams sind mit unterschiedlichen Verhaltensweisen konzipiert, und ihre falsche Verwendung (z. B. das Übergeben eines lesbaren Streams, wo ein schreibbarer Stream erwartet wird) kann zu unerwarteten Ergebnissen oder Fehlern führen. Diese Praxis wird abgeraten, da sie zu undefiniertem Verhalten oder verlorenen Callbacks führen kann, wenn der Stream Fehler aufweist. Stellen Sie immer sicher, dass stdin als lesbar und stdout/stderr als schreibbar verwendet wird, um den beabsichtigten Datenfluss zwischen dem übergeordneten und dem Child-Prozess aufrechtzuerhalten.

7. Positive Ganzzahl: Der Ganzzahlwert wird als Dateideskriptor interpretiert, der im übergeordneten Prozess geöffnet ist. Er wird mit dem Child-Prozess geteilt, ähnlich wie <Stream>-Objekte geteilt werden können. Die Übergabe von Sockets wird unter Windows nicht unterstützt.

8. null, undefined: Verwenden Sie den Standardwert. Für stdio-fds 0, 1 und 2 (also stdin, stdout und stderr) wird eine Pipe erstellt. Für fd 3 und höher ist der Standardwert 'ignore'.

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'] });
copy

Es ist zu beachten, dass wenn ein IPC-Kanal zwischen dem übergeordneten und dem untergeordneten Prozess eingerichtet wird und der untergeordnete Prozess eine Node.js-Instanz ist, der untergeordnete Prozess mit dem nicht referenzierten IPC-Kanal (unter Verwendung von unref()) gestartet wird, bis der untergeordnete Prozess einen Event-Handler für das 'disconnect'-Event oder das 'message'-Event registriert. Dies ermöglicht dem untergeordneten Prozess einen normalen Exit, ohne dass der Prozess durch den offenen IPC-Kanal offengehalten wird. Siehe auch: child_process.exec() und child_process.fork().

Synchrone Prozesserstellung#

Die Methoden child_process.spawnSync(), child_process.execSync() und child_process.execFileSync() sind synchron und blockieren die Node.js-Ereignisschleife, wodurch die Ausführung jeglichen zusätzlichen Codes pausiert wird, bis der gestartete Prozess beendet wird.

Blockierende Aufrufe wie diese sind meist nützlich, um allgemeine Skriptaufgaben zu vereinfachen und das Laden/Verarbeiten der Anwendungskonfiguration beim Start zu vereinfachen.

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

• file <string> Der Name oder Pfad der auszuführenden Datei.
• args <string[]> Liste der String-Argumente.
• options <Object>
  • cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Der Wert, der als stdin an den gestarteten Prozess übergeben wird. Wenn stdio[0] auf 'pipe' gesetzt ist, überschreibt die Bereitstellung dieses Wertes stdio[0].
  • stdio <string> | <Array> stdio-Konfiguration des Child. Siehe child_process.spawn()'s stdio. stderr wird standardmäßig an stderr des übergeordneten Prozesses ausgegeben, es sei denn, stdio ist angegeben. Standard: 'pipe'.
  • env <Object> Schlüssel-Wert-Paare der Umgebung. Standard: process.env.
  • uid <number> Setzt die Benutzeridentität des Prozesses (siehe setuid(2)).
  • gid <number> Setzt die Gruppenidentität des Prozesses (siehe setgid(2)).
  • timeout <number> Die maximale Laufzeit des Prozesses in Millisekunden. Standard: undefined.
  • killSignal <string> | <integer> Der Signalwert, der verwendet wird, wenn der gestartete Prozess beendet wird. Standard: 'SIGTERM'.
  • maxBuffer <number> Größte Datenmenge in Bytes, die auf stdout oder stderr erlaubt ist. Bei Überschreitung wird der Child-Prozess beendet. Siehe Warnung unter maxBuffer und Unicode. Standard: 1024 * 1024.
  • encoding <string> Die für alle stdio-Ein- und Ausgaben verwendete Kodierung. Standard: 'buffer'.
  • windowsHide <boolean> Verbirgt das Konsolenfenster des Unterprozesses, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
  • shell <boolean> | <string> Wenn true, wird der command innerhalb einer Shell ausgeführt. Verwendet '/bin/sh' unter Unix und process.env.ComSpec unter Windows. Eine andere Shell kann als String angegeben werden. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: false (keine Shell).
• Gibt zurück: <Buffer> | <string> Die stdout-Ausgabe des Befehls.

Die Methode child_process.execFileSync() ist im Allgemeinen identisch mit child_process.execFile(), mit der Ausnahme, dass die Methode erst zurückkehrt, wenn der Child-Prozess vollständig geschlossen wurde. Wenn ein Timeout aufgetreten ist und killSignal gesendet wurde, kehrt die Methode erst zurück, wenn der Prozess vollständig beendet wurde.

Wenn der Child-Prozess das Signal SIGTERM abfängt und verarbeitet und nicht beendet wird, wartet der übergeordnete Prozess weiterhin, bis der Child-Prozess beendet wurde.

Wenn der Prozess ein Timeout hat oder einen Exit-Code ungleich Null aufweist, löst diese Methode einen Error aus, der das vollständige Ergebnis des zugrunde liegenden child_process.spawnSync() enthält.

Wenn die Option shell aktiviert ist, übergeben Sie keine unsanitisierte Benutzereingabe an diese Funktion. Jede Eingabe, die Shell-Metazeichen enthält, kann verwendet werden, um eine beliebige Befehlsausführung auszulösen.

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

child_process.execSync(command[, options])#

• command <string> Der auszuführende Befehl.
• options <Object>
  • cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Der Wert, der als stdin an den gestarteten Prozess übergeben wird. Wenn stdio[0] auf 'pipe' gesetzt ist, überschreibt die Bereitstellung dieses Wertes stdio[0].
  • stdio <string> | <Array> stdio-Konfiguration des Child. Siehe child_process.spawn()'s stdio. stderr wird standardmäßig an stderr des übergeordneten Prozesses ausgegeben, es sei denn, stdio ist angegeben. Standard: 'pipe'.
  • env <Object> Schlüssel-Wert-Paare der Umgebung. Standard: process.env.
  • shell <string> Shell, mit der der Befehl ausgeführt werden soll. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: '/bin/sh' unter Unix, process.env.ComSpec unter Windows.
  • uid <number> Setzt die Benutzeridentität des Prozesses. (Siehe setuid(2)).
  • gid <number> Setzt die Gruppenidentität des Prozesses. (Siehe setgid(2)).
  • timeout <number> Die maximale Laufzeit des Prozesses in Millisekunden. Standard: undefined.
  • killSignal <string> | <integer> Der Signalwert, der verwendet wird, wenn der gestartete Prozess beendet wird. Standard: 'SIGTERM'.
  • maxBuffer <number> Größte Datenmenge in Bytes, die auf stdout oder stderr erlaubt ist. Bei Überschreitung wird der Child-Prozess beendet und jede Ausgabe abgeschnitten. Siehe Warnung unter maxBuffer und Unicode. Standard: 1024 * 1024.
  • encoding <string> Die für alle stdio-Ein- und Ausgaben verwendete Kodierung. Standard: 'buffer'.
  • windowsHide <boolean> Verbirgt das Konsolenfenster des Unterprozesses, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
• Gibt zurück: <Buffer> | <string> Die stdout-Ausgabe des Befehls.

Die Methode child_process.execSync() ist im Allgemeinen identisch mit child_process.exec(), mit der Ausnahme, dass die Methode erst zurückkehrt, wenn der Child-Prozess vollständig geschlossen wurde. Wenn ein Timeout aufgetreten ist und killSignal gesendet wurde, kehrt die Methode erst zurück, wenn der Prozess vollständig beendet wurde. Wenn der Child-Prozess das Signal SIGTERM abfängt und verarbeitet und nicht beendet wird, wartet der übergeordnete Prozess weiterhin, bis der Child-Prozess beendet wurde.

Wenn der Prozess ein Timeout hat oder einen Exit-Code ungleich Null aufweist, löst diese Methode einen Fehler aus. Das Error-Objekt enthält das gesamte Ergebnis von child_process.spawnSync().

Übergeben Sie niemals unsanitisierte Benutzereingaben an diese Funktion. Jede Eingabe, die Shell-Metazeichen enthält, kann dazu verwendet werden, eine beliebige Befehlsausführung auszulösen.

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

• command <string> Der auszuführende Befehl.
• args <string[]> Liste der String-Argumente.
• options <Object>
  • cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses.
  • input <string> | <Buffer> | <TypedArray> | <DataView> Der Wert, der als stdin an den gestarteten Prozess übergeben wird. Wenn stdio[0] auf 'pipe' gesetzt ist, überschreibt die Bereitstellung dieses Wertes stdio[0].
  • argv0 <string> Setzt den Wert von argv[0] explizit, der an den Child-Prozess gesendet wird. Dieser wird auf command gesetzt, wenn nicht anders angegeben.
  • stdio <string> | <Array> stdio-Konfiguration des Child. Siehe child_process.spawn()'s stdio. Standard: 'pipe'.
  • env <Object> Schlüssel-Wert-Paare der Umgebung. Standard: process.env.
  • uid <number> Setzt die Benutzeridentität des Prozesses (siehe setuid(2)).
  • gid <number> Setzt die Gruppenidentität des Prozesses (siehe setgid(2)).
  • timeout <number> Die maximale Laufzeit des Prozesses in Millisekunden. Standard: undefined.
  • killSignal <string> | <integer> Der Signalwert, der verwendet wird, wenn der gestartete Prozess beendet wird. Standard: 'SIGTERM'.
  • maxBuffer <number> Größte Datenmenge in Bytes, die auf stdout oder stderr erlaubt ist. Bei Überschreitung wird der Child-Prozess beendet und jede Ausgabe abgeschnitten. Siehe Warnung unter maxBuffer und Unicode. Standard: 1024 * 1024.
  • encoding <string> Die für alle stdio-Ein- und Ausgaben verwendete Kodierung. Standard: 'buffer'.
  • shell <boolean> | <string> Wenn true, wird der command innerhalb einer Shell ausgeführt. Verwendet '/bin/sh' unter Unix und process.env.ComSpec unter Windows. Eine andere Shell kann als String angegeben werden. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: false (keine Shell).
  • windowsVerbatimArguments <boolean> Unter Windows erfolgt kein Quoting oder Escaping von Argumenten. Unter Unix ignoriert. Dies wird automatisch auf true gesetzt, wenn shell angegeben und CMD ist. Standard: false.
  • windowsHide <boolean> Verbirgt das Konsolenfenster des Unterprozesses, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
• Rückgabewert: <Object>
  • pid <number> Pid des Child-Prozesses.
  • output <Array> Array von Ergebnissen der stdio-Ausgabe.
  • stdout <Buffer> | <string> Der Inhalt von output[1].
  • stderr <Buffer> | <string> Der Inhalt von output[2].
  • status <number> | <null> Der Exit-Code des Unterprozesses, oder null, wenn der Unterprozess aufgrund eines Signals beendet wurde.
  • signal <string> | <null> Das zum Beenden des Unterprozesses verwendete Signal, oder null, wenn der Unterprozess nicht aufgrund eines Signals beendet wurde.
  • error <Error> Das Fehlerobjekt, wenn der Child-Prozess fehlgeschlagen ist oder ein Timeout hatte.

Die Methode child_process.spawnSync() ist im Allgemeinen identisch mit child_process.spawn(), mit der Ausnahme, dass die Funktion erst zurückkehrt, wenn der Child-Prozess vollständig geschlossen wurde. Wenn ein Timeout aufgetreten ist und killSignal gesendet wurde, kehrt die Methode erst zurück, wenn der Prozess vollständig beendet wurde. Wenn der Prozess das Signal SIGTERM abfängt und verarbeitet und nicht beendet wird, wartet der übergeordnete Prozess weiterhin, bis der Child-Prozess beendet wurde.

Wenn die Option shell aktiviert ist, übergeben Sie keine unsanitisierte Benutzereingabe an diese Funktion. Jede Eingabe, die Shell-Metazeichen enthält, kann verwendet werden, um eine beliebige Befehlsausführung auszulösen.

Klasse: ChildProcess#

• Erweitert: <EventEmitter>

Instanzen von ChildProcess repräsentieren gestartete Child-Prozesse.

Instanzen von ChildProcess sind nicht dazu gedacht, direkt erstellt zu werden. Verwenden Sie stattdessen die Methoden child_process.spawn(), child_process.exec(), child_process.execFile() oder child_process.fork(), um Instanzen von ChildProcess zu erstellen.

Ereignis: 'close'#

• code <number> Der Exit-Code, wenn der Child-Prozess von selbst beendet wurde, oder null, wenn der Child-Prozess aufgrund eines Signals terminiert wurde.
• signal <string> Das Signal, durch das der Child-Prozess beendet wurde, oder null, wenn der Child-Prozess nicht aufgrund eines Signals terminiert wurde.

Das Ereignis 'close' wird ausgelöst, nachdem ein Prozess beendet wurde und die stdio-Streams eines Child-Prozesses geschlossen wurden. Dies unterscheidet sich vom Ereignis 'exit', da mehrere Prozesse dieselben stdio-Streams teilen könnten. Das Ereignis 'close' wird immer nach dem bereits ausgelösten 'exit'-Ereignis oder 'error'-Ereignis ausgelöst, wenn der Child-Prozess nicht gestartet werden konnte.

Wenn der Prozess beendet wurde, ist code der endgültige Exit-Code des Prozesses, andernfalls null. Wenn der Prozess aufgrund eines Signals terminiert wurde, ist signal der String-Name des Signals, andernfalls null. Einer der beiden Werte wird immer nicht-null sein.

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

Ereignis: 'disconnect'#

Das Ereignis 'disconnect' wird nach dem Aufruf der Methode subprocess.disconnect() im übergeordneten Prozess oder process.disconnect() im untergeordneten Prozess ausgelöst. Nach dem Trennen ist es nicht mehr möglich, Nachrichten zu senden oder zu empfangen, und die Eigenschaft subprocess.connected ist false.

Ereignis: 'error'#

• err <Error> Der Fehler.

Das Ereignis 'error' wird immer ausgelöst, wenn

• Der Prozess konnte nicht gestartet werden.
• Der Prozess konnte nicht beendet werden.
• Das Senden einer Nachricht an den Child-Prozess ist fehlgeschlagen.
• Der Child-Prozess wurde über die Option signal abgebrochen.

Das Ereignis 'exit' kann nach einem Fehler auftreten oder auch nicht. Beim Abhören sowohl der 'exit'- als auch der 'error'-Ereignisse ist darauf zu achten, dass Handler-Funktionen nicht versehentlich mehrmals aufgerufen werden.

Siehe auch subprocess.kill() und subprocess.send().

Ereignis: 'exit'#

• code <number> Der Exit-Code, wenn der Child-Prozess von selbst beendet wurde, oder null, wenn der Child-Prozess aufgrund eines Signals terminiert wurde.
• signal <string> Das Signal, durch das der Child-Prozess beendet wurde, oder null, wenn der Child-Prozess nicht aufgrund eines Signals terminiert wurde.

Das Ereignis 'exit' wird ausgelöst, nachdem der Child-Prozess beendet wurde. Wenn der Prozess beendet wurde, ist code der endgültige Exit-Code des Prozesses, andernfalls null. Wenn der Prozess aufgrund eines Signals terminiert wurde, ist signal der String-Name des Signals, andernfalls null. Einer der beiden Werte wird immer nicht-null sein.

Wenn das Ereignis 'exit' ausgelöst wird, können die stdio-Streams des Child-Prozesses noch offen sein.

Node.js richtet Signal-Handler für SIGINT und SIGTERM ein, und Node.js-Prozesse werden nicht sofort aufgrund des Empfangs dieser Signale beendet. Stattdessen führt Node.js eine Reihe von Bereinigungsaktionen durch und löst dann das behandelte Signal erneut aus.

Siehe waitpid(2).

Wenn code aufgrund der Signalbeendigung null ist, können Sie util.convertProcessSignalToExitCode() verwenden, um das Signal in einen POSIX-Exit-Code umzuwandeln.

Ereignis: 'message'#

• message <Object> Ein geparstes JSON-Objekt oder ein primitiver Wert.
• sendHandle <Handle> | <undefined> undefined oder ein net.Socket-, net.Server- oder dgram.Socket-Objekt.

Das Ereignis 'message' wird ausgelöst, wenn ein Child-Prozess process.send() verwendet, um Nachrichten zu senden.

Die Nachricht durchläuft Serialisierung und Parsing. Die resultierende Nachricht ist möglicherweise nicht identisch mit der ursprünglich gesendeten.

Wenn die Option serialization beim Starten des Child-Prozesses auf 'advanced' gesetzt wurde, kann das message-Argument Daten enthalten, die JSON nicht darstellen kann. Weitere Details finden Sie unter Erweiterte Serialisierung.

Ereignis: 'spawn'#

Das Ereignis 'spawn' wird ausgelöst, sobald der Child-Prozess erfolgreich gestartet wurde. Wenn der Child-Prozess nicht erfolgreich gestartet wird, wird das Ereignis 'spawn' nicht ausgelöst, stattdessen wird das Ereignis 'error' ausgelöst.

Wenn ausgelöst, tritt das Ereignis 'spawn' vor allen anderen Ereignissen und vor dem Empfang von Daten über stdout oder stderr auf.

Das Ereignis 'spawn' wird ausgelöst, unabhängig davon, ob ein Fehler innerhalb des gestarteten Prozesses auftritt. Wenn zum Beispiel bash some-command erfolgreich gestartet wird, wird das Ereignis 'spawn' ausgelöst, obwohl bash möglicherweise some-command nicht starten kann. Diese Einschränkung gilt auch bei Verwendung von { shell: true }.

subprocess.channel#

• Typ: <Object> Eine Pipe, die den IPC-Kanal zum Child-Prozess darstellt.

Die Eigenschaft subprocess.channel ist eine Referenz auf den IPC-Kanal des Child. Wenn kein IPC-Kanal existiert, ist diese Eigenschaft undefined.

subprocess.channel.ref()#

Diese Methode bewirkt, dass der IPC-Kanal die Ereignisschleife des übergeordneten Prozesses am Laufen hält, wenn zuvor .unref() aufgerufen wurde.

subprocess.channel.unref()#

Diese Methode bewirkt, dass der IPC-Kanal die Ereignisschleife des übergeordneten Prozesses nicht am Laufen hält und sie beenden lässt, selbst wenn der Kanal offen ist.

subprocess.connected#

• Typ: <boolean> Auf false gesetzt, nachdem subprocess.disconnect() aufgerufen wurde.

Die Eigenschaft subprocess.connected zeigt an, ob es noch möglich ist, Nachrichten von einem Child-Prozess zu senden und zu empfangen. Wenn subprocess.connected false ist, ist das Senden oder Empfangen von Nachrichten nicht mehr möglich.

subprocess.disconnect()#

Schließt den IPC-Kanal zwischen übergeordnetem und untergeordnetem Prozess, wodurch der untergeordnete Prozess ordnungsgemäß beendet werden kann, sobald keine weiteren Verbindungen ihn am Leben erhalten. Nach dem Aufruf dieser Methode werden die Eigenschaften subprocess.connected und process.connected sowohl im übergeordneten als auch im untergeordneten Prozess (jeweils) auf false gesetzt, und es ist nicht mehr möglich, Nachrichten zwischen den Prozessen zu übergeben.

Das Ereignis 'disconnect' wird ausgelöst, wenn keine Nachrichten mehr empfangen werden. Dies wird meist sofort nach dem Aufruf von subprocess.disconnect() ausgelöst.

Wenn der Child-Prozess eine Node.js-Instanz ist (z. B. mit child_process.fork() gestartet), kann die Methode process.disconnect() innerhalb des Child-Prozesses aufgerufen werden, um auch den IPC-Kanal zu schließen.

subprocess.exitCode#

• Typ: <integer>

Die Eigenschaft subprocess.exitCode gibt den Exit-Code des Child-Prozesses an. Wenn der Child-Prozess noch läuft, ist das Feld null.

Wenn der Child-Prozess durch ein Signal terminiert wird, ist subprocess.exitCode null und subprocess.signalCode wird gesetzt. Um den entsprechenden POSIX-Exit-Code zu erhalten, verwenden Sie util.convertProcessSignalToExitCode(subprocess.signalCode).

subprocess.kill([signal])#

• signal <number> | <string>
• Rückgabewert: <boolean>

Die Methode subprocess.kill() sendet ein Signal an den Child-Prozess. Wenn kein Argument angegeben wird, wird dem Prozess das Signal 'SIGTERM' gesendet. Eine Liste der verfügbaren Signale finden Sie unter signal(7). Diese Funktion gibt true zurück, wenn kill(2) erfolgreich ist, und false andernfalls.

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');
copy

Das ChildProcess-Objekt kann ein 'error'-Ereignis auslösen, wenn das Signal nicht zugestellt werden kann. Das Senden eines Signals an einen Child-Prozess, der bereits beendet wurde, ist kein Fehler, kann aber unvorhergesehene Folgen haben. Insbesondere wenn die Prozess-ID (PID) einem anderen Prozess neu zugewiesen wurde, wird das Signal stattdessen an diesen Prozess gesendet, was zu unerwarteten Ergebnissen führen kann.

Obwohl die Funktion kill genannt wird, beendet das an den Child-Prozess gesendete Signal den Prozess möglicherweise nicht tatsächlich.

Siehe kill(2) als Referenz.

Unter Windows, wo POSIX-Signale nicht existieren, wird das signal-Argument ignoriert, außer für 'SIGKILL', 'SIGTERM', 'SIGINT' und 'SIGQUIT', und der Prozess wird immer zwangsweise und abrupt beendet (ähnlich wie 'SIGKILL'). Weitere Details finden Sie unter Signal Events.

Unter Linux werden Child-Prozesse von Child-Prozessen nicht beendet, wenn versucht wird, deren übergeordneten Prozess zu beenden. Dies tritt wahrscheinlich auf, wenn ein neuer Prozess in einer Shell oder mit der Option shell von ChildProcess ausgeführt wird.

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

subprocess[Symbol.dispose]()#

Ruft subprocess.kill() mit 'SIGTERM' auf.

subprocess.killed#

• Typ: <boolean> Auf true gesetzt, nachdem subprocess.kill() erfolgreich zum Senden eines Signals an den Child-Prozess verwendet wurde.

Die Eigenschaft subprocess.killed zeigt an, ob der Child-Prozess erfolgreich ein Signal von subprocess.kill() empfangen hat. Die Eigenschaft killed gibt nicht an, dass der Child-Prozess terminiert wurde.

subprocess.pid#

• Typ: <integer> | <undefined>

Gibt die Prozess-ID (PID) des Child-Prozesses zurück. Wenn der Child-Prozess aufgrund von Fehlern nicht gestartet werden kann, ist der Wert undefined und ein error wird ausgelöst.

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

subprocess.ref()#

Der Aufruf von subprocess.ref() nach einem Aufruf von subprocess.unref() stellt die entfernte Referenzzählung für den Child-Prozess wieder her, wodurch der übergeordnete Prozess gezwungen wird, auf den Exit des Child-Prozesses zu warten, bevor er selbst beendet wird.

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

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

• message <Object>
• sendHandle <Handle> | <undefined> undefined oder ein net.Socket-, net.Server- oder dgram.Socket-Objekt.
• options <Object> Das options-Argument ist, falls vorhanden, ein Objekt zur Parametrisierung des Versands bestimmter Handle-Typen. options unterstützt folgende Eigenschaften:
  • keepOpen <boolean> Ein Wert, der beim Übergeben von Instanzen von net.Socket verwendet werden kann. Wenn true, bleibt der Socket im sendenden Prozess offen. Standard: false.
• callback <Function>
• Rückgabewert: <boolean>

Wenn ein IPC-Kanal zwischen dem übergeordneten und dem untergeordneten Prozess eingerichtet wurde (d. h. bei Verwendung von child_process.fork()), kann die Methode subprocess.send() verwendet werden, um Nachrichten an den untergeordneten Prozess zu senden. Wenn der untergeordnete Prozess eine Node.js-Instanz ist, können diese Nachrichten über das Ereignis 'message' empfangen werden.

Die Nachricht durchläuft Serialisierung und Parsing. Die resultierende Nachricht ist möglicherweise nicht identisch mit der ursprünglich gesendeten.

Zum Beispiel im übergeordneten Skript

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

Und dann könnte das Child-Skript, 'sub.js', so aussehen

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

Child-Node.js-Prozesse verfügen über eine eigene process.send()-Methode, die es dem Child-Prozess ermöglicht, Nachrichten an den übergeordneten Prozess zurückzusenden.

Es gibt einen Sonderfall beim Senden einer Nachricht {cmd: 'NODE_foo'}. Nachrichten, die ein NODE_-Präfix in der Eigenschaft cmd enthalten, sind für die Verwendung innerhalb des Node.js-Kerns reserviert und werden nicht im 'message'-Ereignis des Child ausgelöst. Stattdessen werden solche Nachrichten unter Verwendung des 'internalMessage'-Ereignisses ausgelöst und intern von Node.js verarbeitet. Anwendungen sollten die Verwendung solcher Nachrichten oder das Abhören von 'internalMessage'-Ereignissen vermeiden, da dies ohne vorherige Ankündigung geändert werden kann.

Das optionale sendHandle-Argument, das an subprocess.send() übergeben werden kann, dient dazu, ein TCP-Server- oder Socket-Objekt an den Child-Prozess zu übergeben. Der Child-Prozess empfängt das Objekt als zweites Argument, das an die im Ereignis 'message' registrierte Callback-Funktion übergeben wird. Alle Daten, die im Socket empfangen und gepuffert werden, werden nicht an den Child gesendet. Das Senden von IPC-Sockets wird unter Windows nicht unterstützt.

Der optionale callback ist eine Funktion, die nach dem Senden der Nachricht, aber bevor der Child-Prozess sie möglicherweise empfangen hat, aufgerufen wird. Die Funktion wird mit einem einzigen Argument aufgerufen: null bei Erfolg oder ein Error-Objekt bei Fehler.

Wenn keine callback-Funktion bereitgestellt wird und die Nachricht nicht gesendet werden kann, wird ein 'error'-Ereignis vom ChildProcess-Objekt ausgelöst. Dies kann beispielsweise passieren, wenn der Child-Prozess bereits beendet wurde.

subprocess.send() gibt false zurück, wenn der Kanal geschlossen wurde oder wenn die Warteschlange der nicht gesendeten Nachrichten einen Schwellenwert überschreitet, der das Senden weiterer Nachrichten unklug erscheinen lässt. Andernfalls gibt die Methode true zurück. Die callback-Funktion kann zur Implementierung der Flusskontrolle verwendet werden.

Beispiel: Senden eines Server-Objekts#

Das sendHandle-Argument kann beispielsweise verwendet werden, um das Handle eines TCP-Server-Objekts an den Child-Prozess zu übergeben, wie im folgenden Beispiel dargestellt.

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

Der Child-Prozess würde dann das Server-Objekt als

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

Sobald der Server nun zwischen dem übergeordneten und dem untergeordneten Prozess geteilt wird, können einige Verbindungen vom übergeordneten Prozess und andere vom untergeordneten Prozess bearbeitet werden.

Während das obige Beispiel einen Server verwendet, der mit dem node:net-Modul erstellt wurde, verwenden node:dgram-Modulserver genau denselben Workflow, mit den Ausnahmen, dass auf ein 'message'-Ereignis anstelle von 'connection' gehört und server.bind() anstelle von server.listen() verwendet wird. Dies wird jedoch nur auf Unix-Plattformen unterstützt.

Beispiel: Senden eines Socket-Objekts#

Ähnlich kann das Argument sendHandler verwendet werden, um das Handle eines Sockets an den Child-Prozess zu übergeben. Das folgende Beispiel startet zwei Child-Prozesse, die jeweils Verbindungen mit "normaler" oder "spezieller" Priorität bearbeiten.

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

Die subprocess.js würde das Socket-Handle als zweites Argument erhalten, das an die Ereignis-Callback-Funktion übergeben wird.

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

Verwenden Sie .maxConnections nicht für einen Socket, der an einen Unterprozess übergeben wurde. Der übergeordnete Prozess kann nicht nachverfolgen, wann der Socket zerstört wird.

Alle 'message'-Handler im Unterprozess sollten überprüfen, ob der socket existiert, da die Verbindung während der Zeit, die zum Senden der Verbindung an den Child benötigt wird, möglicherweise geschlossen wurde.

subprocess.signalCode#

• Typ: <string> | <null>

Die Eigenschaft subprocess.signalCode gibt das vom Child-Prozess empfangene Signal an, falls vorhanden, ansonsten null.

Wenn der Child-Prozess durch ein Signal terminiert wird, ist subprocess.exitCode null. Um den entsprechenden POSIX-Exit-Code zu erhalten, verwenden Sie util.convertProcessSignalToExitCode(subprocess.signalCode).

subprocess.spawnargs#

• Typ: <Array>

Die Eigenschaft subprocess.spawnargs repräsentiert die vollständige Liste der Kommandozeilenargumente, mit denen der Child-Prozess gestartet wurde.

subprocess.spawnfile#

• Typ: <string>

Die Eigenschaft subprocess.spawnfile gibt den Namen der ausführbaren Datei des gestarteten Child-Prozesses an.

Für child_process.fork() ist der Wert gleich process.execPath. Für child_process.spawn() ist der Wert der Name der ausführbaren Datei. Für child_process.exec() ist der Wert der Name der Shell, in der der Child-Prozess gestartet wird.

subprocess.stderr#

• Typ: <stream.Readable> | <null> | <undefined>

Ein Readable Stream, der den stderr des Child-Prozesses repräsentiert.

Wenn der Child-Prozess mit stdio[2] gestartet wurde, das auf etwas anderes als 'pipe' gesetzt ist, dann ist dies null.

subprocess.stderr ist ein Alias für subprocess.stdio[2]. Beide Eigenschaften verweisen auf denselben Wert.

Die Eigenschaft subprocess.stderr kann null oder undefined sein, wenn der Child-Prozess nicht erfolgreich gestartet werden konnte.

subprocess.stdin#

• Typ: <stream.Writable> | <null> | <undefined>

Ein Writable Stream, der den stdin des Child-Prozesses repräsentiert.

Wenn ein Child-Prozess darauf wartet, alle seine Eingaben zu lesen, wird der Child-Prozess erst fortgesetzt, wenn dieser Stream über end() geschlossen wurde.

Wenn der Child-Prozess mit stdio[0] gestartet wurde, das auf etwas anderes als 'pipe' gesetzt ist, dann ist dies null.

subprocess.stdin ist ein Alias für subprocess.stdio[0]. Beide Eigenschaften verweisen auf denselben Wert.

Die Eigenschaft subprocess.stdin kann null oder undefined sein, wenn der Child-Prozess nicht erfolgreich gestartet werden konnte.

subprocess.stdio#

• Typ: <Array>

Ein dünnbesetztes Array von Pipes zum Child-Prozess, entsprechend den Positionen in der stdio-Option, die an child_process.spawn() übergeben wurde und auf den Wert 'pipe' gesetzt sind. subprocess.stdio[0], subprocess.stdio[1] und subprocess.stdio[2] sind auch als subprocess.stdin, subprocess.stdout bzw. subprocess.stderr verfügbar.

Im folgenden Beispiel ist nur der fd 1 (stdout) des Child als Pipe konfiguriert, sodass nur subprocess.stdio[1] des übergeordneten Prozesses ein Stream ist; alle anderen Werte im Array sind 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);
copy

Die subprocess.stdio-Eigenschaft kann undefined sein, wenn der Child-Prozess nicht erfolgreich gestartet werden konnte.

subprocess.stdout#

• Typ: <stream.Readable> | <null> | <undefined>

Ein Readable Stream, der das stdout des Child-Prozesses darstellt.

Wenn der Child-Prozess mit stdio[1] auf etwas anderes als 'pipe' gesetzt gestartet wurde, dann ist dies null.

subprocess.stdout ist ein Alias für subprocess.stdio[1]. Beide Eigenschaften verweisen auf denselben Wert.

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

Die subprocess.stdout-Eigenschaft kann null oder undefined sein, wenn der Child-Prozess nicht erfolgreich gestartet werden konnte.

subprocess.unref()#

Standardmäßig wartet der Elternprozess darauf, dass der abgetrennte Child-Prozess beendet wird. Um zu verhindern, dass der Elternprozess auf das Beenden eines bestimmten subprocess wartet, verwenden Sie die Methode subprocess.unref(). Dadurch wird die Event-Schleife des Elternprozesses den Child-Prozess nicht in ihre Referenzzählung einbeziehen, was es dem Elternprozess ermöglicht, unabhängig vom Child-Prozess zu beenden, es sei denn, es besteht ein etablierter IPC-Kanal zwischen dem Child- und dem Elternprozess.

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

maxBuffer und Unicode#

Die Option maxBuffer gibt die maximale Anzahl von Bytes an, die auf stdout oder stderr erlaubt sind. Wird dieser Wert überschritten, wird der Child-Prozess beendet. Dies wirkt sich auf Ausgaben aus, die Multibyte-Zeichenkodierungen wie UTF-8 oder UTF-16 enthalten. Zum Beispiel sendet console.log('中文测试') 13 UTF-8-kodierte Bytes an stdout, obwohl es nur 4 Zeichen sind.

Shell-Anforderungen#

Die Shell sollte den Switch -c verstehen. Wenn die Shell 'cmd.exe' ist, sollte sie die Switches /d /s /c verstehen und die Kommandozeilen-Analyse sollte kompatibel sein.

Standard-Windows-Shell#

Obwohl Microsoft festlegt, dass %COMSPEC% den Pfad zu 'cmd.exe' in der Stammumgebung enthalten muss, unterliegen Child-Prozesse nicht immer derselben Anforderung. Daher wird in child_process-Funktionen, in denen eine Shell gestartet werden kann, 'cmd.exe' als Fallback verwendet, wenn process.env.ComSpec nicht verfügbar ist.

Erweiterte Serialisierung#

Child-Prozesse unterstützen einen Serialisierungsmechanismus für IPC, der auf der Serialisierungs-API des node:v8-Moduls basiert, die wiederum auf dem HTML Structured Clone Algorithmus aufbaut. Dieser ist im Allgemeinen leistungsfähiger und unterstützt mehr eingebaute JavaScript-Objekttypen wie BigInt, Map und Set, ArrayBuffer und TypedArray, Buffer, Error, RegExp usw.

Dieses Format ist jedoch kein vollständiges Superset von JSON, und z.B. auf Objekten solcher eingebauten Typen gesetzte Eigenschaften werden nicht durch den Serialisierungsschritt übertragen. Darüber hinaus ist die Leistung möglicherweise nicht gleichwertig mit der von JSON, abhängig von der Struktur der übergebenen Daten. Daher erfordert diese Funktion eine explizite Aktivierung, indem die Option serialization beim Aufruf von child_process.spawn() oder child_process.fork() auf 'advanced' gesetzt wird.