Unterprozess

[Stabil: 2 - Stabil]

Das Modul node:child_process ermöglicht das Erzeugen von Unterprozessen, ähnlich, aber nicht identisch zu popen(3). Diese Funktionalität wird hauptsächlich durch die Funktion child_process.spawn() bereitgestellt:

CJSESM

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(`Unterprozess beendet mit Code ${code}`)
})

import { spawn } from 'node:child_process'
const ls = spawn('ls', ['-lh', '/usr'])

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

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

ls.on('close', code => {
  console.log(`Unterprozess beendet mit Code ${code}`)
})

Standardmäßig werden Pipes für stdin, stdout und stderr zwischen dem übergeordneten Node.js-Prozess und dem erzeugten Unterprozess eingerichtet. Diese Pipes haben eine begrenzte (und plattformspezifische) Kapazität. Wenn der Unterprozess mehr Daten an stdout schreibt als die Kapazität erlaubt, ohne dass die Ausgabe erfasst wird, blockiert der Unterprozess, bis der Pipe-Puffer mehr Daten aufnehmen kann. Dies entspricht dem Verhalten von Pipes in der Shell. Verwenden Sie die Option { stdio: 'ignore' }, wenn die Ausgabe nicht verarbeitet wird.

Die Befehlssuche wird unter Verwendung 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, wird die Suche unter Unix auf einem Standardsuchpfad von /usr/bin:/bin durchgeführt (siehe Handbuch Ihres Betriebssystems für execvpe/execvp), unter Windows wird die aktuelle Umgebungsvariable PATH des Prozesses verwendet.

Unter Windows sind Umgebungsvariablen nicht casesensitiv. Node.js sortiert die env-Schlüssel lexikografisch und verwendet den ersten, der case-insensitive übereinstimmt. Nur der erste (in lexikografischer Reihenfolge) Eintrag 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 z. B. PATH und Path.

Die Methode child_process.spawn() erzeugt den Unterprozess asynchron, ohne die Node.js-Ereignisschleife zu blockieren. Die Funktion child_process.spawnSync() bietet eine äquivalente Funktionalität synchron, wobei die Ereignisschleife blockiert wird, bis der erzeugte Prozess beendet oder terminiert wird.

Der Einfachheit halber bietet das Modul node:child_process eine Handvoll synchroner und asynchroner Alternativen zu child_process.spawn() und child_process.spawnSync(). Jede dieser Alternativen wird auf Basis von child_process.spawn() oder child_process.spawnSync() implementiert.

child_process.exec(): erzeugt eine Shell und führt einen Befehl in dieser Shell aus, wobei stdout und stderr nach Abschluss an eine Callback-Funktion übergeben werden.
child_process.execFile(): ähnlich zu child_process.exec(), außer dass der Befehl standardmäßig direkt erzeugt wird, ohne vorher eine Shell zu erzeugen.
child_process.fork(): erzeugt 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 z. B. 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 die Ereignisschleife blockiert wird, während die erzeugten 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, die es dem übergeordneten Prozess ermöglicht, Listener-Funktionen zu registrieren, die aufgerufen werden, wenn bestimmte Ereignisse während des Lebenszyklus des untergeordneten 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 untergeordnete Prozess terminiert.

Ausführen von `.bat`- und `.cmd`-Dateien unter Windows

Die Bedeutung der Unterscheidung zwischen child_process.exec() und child_process.execFile() kann je nach Plattform variieren. Unter Unix-artigen Betriebssystemen (Unix, Linux, macOS) kann child_process.execFile() effizienter sein, da standardmäßig keine Shell erzeugt wird. Unter Windows sind .bat- und .cmd-Dateien jedoch ohne Terminal nicht eigenständig ausführbar und können daher nicht mit child_process.execFile() gestartet werden. Unter Windows können .bat- und .cmd-Dateien mit child_process.spawn() mit aktivierter shell-Option, mit child_process.exec() oder durch das Erzeugen von cmd.exe und das Übergeben der .bat- oder .cmd-Datei als Argument (was die shell-Option und child_process.exec() tun) aufgerufen werden. In jedem Fall muss der Skript-Dateiname, falls er Leerzeichen enthält, in Anführungszeichen gesetzt werden.

CJSESM

// ODER...
const { exec, spawn } = require('node:child_process')

exec('my.bat', (err, stdout, stderr) => {
  if (err) {
    console.error(err)
    return
  }
  console.log(stdout)
})

// Skript mit Leerzeichen im Dateinamen:
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true })
// oder:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
})

// ODER...
import { exec, spawn } from 'node:child_process'

exec('my.bat', (err, stdout, stderr) => {
  if (err) {
    console.error(err)
    return
  }
  console.log(stdout)
})

// Skript mit Leerzeichen im Dateinamen:
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true })
// oder:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
})

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

[Verlauf]

Version	Änderungen
v15.4.0	Unterstützung für AbortSignal hinzugefügt.
v16.4.0, v14.18.0	Die Option `cwd` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v8.8.0	Die Option `windowsHide` wird jetzt unterstützt.
v0.1.90	Hinzugefügt in: v0.1.90

command <string> Der auszuführende Befehl mit durch Leerzeichen getrennten Argumenten.
options <Object>
- cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des untergeordneten Prozesses. Standard: process.cwd().
- env <Object> Umgebungs-Schlüssel-Wert-Paare. Standard: process.env.
- encoding <string> Standard: 'utf8'
- shell <string> Shell zum Ausführen des Befehls. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: '/bin/sh' unter Unix, process.env.ComSpec unter Windows.
- signal <AbortSignal> ermöglicht das Abbrechen des untergeordneten Prozesses mit einem AbortSignal.
- timeout <number> Standard: 0
- maxBuffer <number> Größte zulässige Datenmenge in Bytes auf stdout oder stderr. Wenn überschritten, wird der untergeordnete Prozess beendet und die Ausgabe wird abgeschnitten. Siehe Vorbehalt 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> Blendet das Unterprozess-Konsolenfenster aus, 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>
Rückgabewert: <ChildProcess>

Erzeugt eine Shell und führt dann den command innerhalb dieser Shell aus, wobei die generierte Ausgabe gepuffert wird. Die an die exec-Funktion übergebene command-Zeichenkette wird direkt von der Shell verarbeitet, und Sonderzeichen (variieren je nach Shell) müssen entsprechend behandelt werden:

CJSESM

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

exec('"/path/to/test file/test.sh" arg1 arg2')
// Anführungszeichen werden verwendet, damit der Leerzeichen im Pfad nicht als
// Trennzeichen für mehrere Argumente interpretiert wird.

exec('echo "Die \\$HOME Variable ist $HOME"')
// Die $HOME Variable wird im ersten Fall escaped, im zweiten nicht.

import { exec } from 'node:child_process'

exec('"/path/to/test file/test.sh" arg1 arg2')
// Anführungszeichen werden verwendet, damit der Leerzeichen im Pfad nicht als
// Trennzeichen für mehrere Argumente interpretiert wird.

exec('echo "Die \\$HOME Variable ist $HOME"')
// Die $HOME Variable wird im ersten Fall escaped, im zweiten nicht.

Geben Sie niemals nicht bereinigte Benutzereingaben an diese Funktion weiter. Jede Eingabe, die Shell-Metazeichen enthält, kann verwendet werden, um die Ausführung beliebiger Befehle auszulösen.

Wenn eine callback-Funktion angegeben ist, wird sie mit den Argumenten (error, stdout, stderr) aufgerufen. Bei Erfolg ist error null. Bei einem Fehler ist error eine Instanz von Error. Die Eigenschaft error.code ist der Exit-Code des Prozesses. Konventionell zeigt jeder Exit-Code außer 0 einen Fehler an. error.signal ist das Signal, das den Prozess beendet hat.

Die Argumente stdout und stderr, die an den Callback übergeben werden, enthalten die stdout- und stderr-Ausgabe des untergeordneten Prozesses. Standardmäßig dekodiert Node.js die Ausgabe als UTF-8 und übergibt Zeichenketten an den Callback. Mit der Option encoding kann die Zeichenkodierung angegeben werden, 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.

CJSESM

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

Wenn timeout größer als 0 ist, sendet der übergeordnete Prozess das durch die Eigenschaft killSignal identifizierte Signal (Standard ist 'SIGTERM'), wenn der untergeordnete 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 deren util.promisify()-Version aufgerufen wird, gibt sie ein Promise für ein Object mit den Eigenschaften stdout und stderr zurück. Die zurückgegebene ChildProcess-Instanz wird dem Promise als child-Eigenschaft angehängt. Im Falle eines Fehlers (einschließlich eines Fehlers, der zu einem anderen Exit-Code als 0 führt), wird ein abgelehntes Promise zurückgegeben, mit dem gleichen error-Objekt, das im Callback angegeben wurde, aber mit zwei zusätzlichen Eigenschaften stdout und stderr.

CJSESM

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

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

CJSESM

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

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

[Verlauf]

Version	Änderungen
v16.4.0, v14.18.0	Die Option `cwd` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v15.4.0, v14.17.0	Unterstützung für AbortSignal wurde hinzugefügt.
v8.8.0	Die Option `windowsHide` wird jetzt unterstützt.
v0.1.91	Hinzugefügt in: v0.1.91

file <string> Der Name oder Pfad der ausführbaren Datei, die ausgeführt werden soll.
args <string[]> Liste von String-Argumenten.
options <Object>
- cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des untergeordneten Prozesses.
- env <Object> Umgebungs-Schlüssel-Wert-Paare. Standard: process.env.
- encoding <string> Standard: 'utf8'
- timeout <number> Standard: 0
- maxBuffer <number> Größte zulässige Datenmenge in Bytes auf stdout oder stderr. Wenn überschritten, wird der untergeordnete Prozess beendet und alle Ausgaben werden abgeschnitten. Siehe Vorbehalt 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> Versteckt das Subprozess-Konsolenfenster, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
- windowsVerbatimArguments <boolean> Auf Windows wird keine Anführungszeichen oder Escaping von Argumenten durchgeführt. Auf Unix ignoriert. Standard: false.
- shell <boolean> | <string> Wenn true, wird command innerhalb einer Shell ausgeführt. Verwendet '/bin/sh' unter Unix und process.env.ComSpec unter Windows. Eine andere Shell kann als Zeichenkette angegeben werden. Siehe Shell-Anforderungen und Standard-Windows-Shell. Standard: false (keine Shell).
- signal <AbortSignal> ermöglicht das Abbrechen des untergeordneten 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() ähnelt child_process.exec(), außer dass sie standardmäßig keine Shell erzeugt. Vielmehr wird die angegebene ausführbare Datei file direkt als neuer Prozess erzeugt, wodurch sie etwas effizienter ist als child_process.exec().

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

CJSESM

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

Die an den Callback übergebenen Argumente stdout und stderr enthalten die stdout- und stderr-Ausgabe des untergeordneten Prozesses. Standardmäßig dekodiert Node.js die Ausgabe als UTF-8 und übergibt Zeichenketten 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()-Version aufgerufen wird, gibt sie ein Promise für ein Object mit den Eigenschaften stdout und stderr zurück. Die zurückgegebene ChildProcess-Instanz wird als child-Eigenschaft an das Promise angehängt. Im Falle eines Fehlers (einschließlich eines Fehlers, der zu einem anderen Exit-Code als 0 führt), wird ein abgelehntes Promise zurückgegeben, mit dem gleichen error-Objekt, das im Callback angegeben wurde, aber mit zwei zusätzlichen Eigenschaften stdout und stderr.

CJSESM

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

Wenn die Option shell aktiviert ist, geben Sie keine nicht bereinigten Benutzereingaben an diese Funktion weiter. Jede Eingabe, die Shell-Metazeichen enthält, kann verwendet werden, um die Ausführung beliebiger Befehle auszulösen.

CJSESM

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

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

[Verlauf]

Version	Änderungen
v17.4.0, v16.14.0	Der Parameter `modulePath` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v16.4.0, v14.18.0	Die Option `cwd` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v15.13.0, v14.18.0	timeout wurde hinzugefügt.
v15.11.0, v14.18.0	killSignal für AbortSignal wurde hinzugefügt.
v15.6.0, v14.17.0	Unterstützung für AbortSignal wurde hinzugefügt.
v13.2.0, v12.16.0	Die Option `serialization` wird jetzt unterstützt.
v8.0.0	Die Option `stdio` kann jetzt eine Zeichenkette sein.
v6.4.0	Die Option `stdio` wird jetzt unterstützt.
v0.5.0	Hinzugefügt in: v0.5.0

modulePath <string> | <URL> Das im Child-Prozess auszuführende Modul.
args <string[]> Liste von String-Argumenten.
options <Object>
- cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des Child-Prozesses.
- detached <boolean> Bereitet den Child-Prozess darauf vor, unabhängig von seinem Elternprozess zu laufen. Das spezifische Verhalten hängt von der Plattform ab, siehe options.detached).
- env <Object> Umgebungs-Schlüssel-Wert-Paare. Standard: process.env.
- execPath <string> Ausführbare Datei, die zum Erstellen des Child-Prozesses verwendet wird.
- execArgv <string[]> Liste von String-Argumenten, die an die ausführbare Datei übergeben werden. Standard: process.execArgv.
- gid <number> Legt die Gruppenidentität des Prozesses fest (siehe setgid(2)).
- serialization <string> Gibt die Art der Serialisierung an, die für das Senden von Nachrichten zwischen Prozessen verwendet wird. Mögliche Werte sind 'json' und 'advanced'. Weitere Informationen finden Sie unter Erweiterte Serialisierung. Standard: 'json'.
- signal <AbortSignal> Ermöglicht das Schließen des Child-Prozesses mithilfe eines AbortSignal.
- killSignal <string> | <integer> Der Signalwert, der verwendet werden soll, wenn der erzeugte Prozess durch Timeout oder Abbruchsignal beendet wird. Standard: 'SIGTERM'.
- silent <boolean> Wenn true, werden stdin, stdout und stderr des Child-Prozesses an den Elternprozess weitergeleitet, andernfalls werden sie vom Elternprozess geerbt, siehe die Optionen 'pipe' und 'inherit' für child_process.spawn()'s stdio für weitere Details. 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> Legt die Benutzeridentität des Prozesses fest (siehe setuid(2)).
- windowsVerbatimArguments <boolean> Keine Anführungszeichen oder Escaping von Argumenten unter Windows. Unter Unix ignoriert. Standard: false.
- timeout <number> In Millisekunden die maximale Laufzeit des Prozesses. Standard: undefined.
Rückgabewert: <ChildProcess>

Die Methode child_process.fork() ist ein Sonderfall von child_process.spawn(), der speziell zum Erzeugen neuer Node.js-Prozesse verwendet wird. Wie bei child_process.spawn() wird ein ChildProcess-Objekt zurückgegeben. Der zurückgegebene ChildProcess verfügt über einen zusätzlichen eingebauten Kommunikationskanal, der es ermöglicht, Nachrichten zwischen dem Eltern- und dem Child-Prozess hin und her zu senden. Siehe subprocess.send() für Details.

Beachten Sie, dass erzeugte Node.js-Child-Prozesse unabhängig vom Elternprozess sind, mit Ausnahme des IPC-Kommunikationskanals, der zwischen den beiden hergestellt wird. Jeder Prozess verfügt über seinen eigenen Speicher mit eigenen V8-Instanzen. Aufgrund der zusätzlichen benötigten Ressourcenzuweisungen wird das Erzeugen einer großen Anzahl von Child-Node.js-Prozessen nicht empfohlen.

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

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

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

Die Option shell, die in child_process.spawn() verfügbar ist, 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() auf dem entsprechenden AbortController ähnlich dem Aufruf von .kill() auf dem Child-Prozess, außer dass der Fehler, der an den Callback übergeben wird, ein AbortError ist:

CJSESM

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 => {
    // Dies wird mit err als AbortError aufgerufen, wenn der Controller abbricht
  })
  controller.abort() // Stoppt den Child-Prozess
}

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 => {
    // Dies wird mit err als AbortError aufgerufen, wenn der Controller abbricht
  })
  controller.abort() // Stoppt den Child-Prozess
}

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

[Verlauf]

Version	Änderungen
v16.4.0, v14.18.0	Die Option `cwd` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v15.13.0, v14.18.0	timeout wurde hinzugefügt.
v15.11.0, v14.18.0	killSignal für AbortSignal wurde hinzugefügt.
v15.5.0, v14.17.0	Unterstützung für AbortSignal wurde hinzugefügt.
v13.2.0, v12.16.0	Die Option `serialization` wird jetzt unterstützt.
v8.8.0	Die Option `windowsHide` wird jetzt unterstützt.
v6.4.0	Die Option `argv0` wird jetzt unterstützt.
v5.7.0	Die Option `shell` wird jetzt unterstützt.
v0.1.90	Hinzugefügt in: v0.1.90

command <string> Der auszuführende Befehl.
args <string[]> Liste der String-Argumente.
options <Object>
- cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des untergeordneten Prozesses.
- env <Object> Umgebungs-Schlüssel-Wert-Paare. Standard: process.env.
- argv0 <string> Setzt explizit den Wert von argv[0], der an den untergeordneten Prozess gesendet wird. Dieser wird auf command gesetzt, wenn er nicht angegeben ist.
- stdio <Array> | <string> Stdio-Konfiguration des untergeordneten Prozesses (siehe options.stdio).
- detached <boolean> Bereitet den untergeordneten 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'. Weitere Informationen finden Sie unter Erweiterte Serialisierung. Standard: 'json'.
- shell <boolean> | <string> Wenn true, wird 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 keine Anführungszeichensetzung oder Escaping von Argumenten. Unter Unix wird dies ignoriert. Dies wird automatisch auf true gesetzt, wenn shell angegeben ist und CMD ist. Standard: false.
- windowsHide <boolean> Blendet das Konsolenfenster des Unterprozesses aus, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
- signal <AbortSignal> ermöglicht das Abbrechen des untergeordneten Prozesses mit einem AbortSignal.
- timeout <number> In Millisekunden die maximale Laufzeit des Prozesses. Standard: undefined.
- killSignal <string> | <integer> Der Signalwert, der verwendet werden soll, wenn der erzeugte Prozess durch Timeout oder Abbruchsignal beendet wird. Standard: 'SIGTERM'.
Rückgabewert: <ChildProcess>

Die Methode child_process.spawn() erzeugt einen neuen Prozess mit dem angegebenen command und den Befehlszeilenargumenten in args. Wenn args ausgelassen wird, ist der Standardwert ein leeres Array.

Wenn die Option shell aktiviert ist, geben Sie keine unsanierten Benutzereingaben an diese Funktion weiter. Jegliche Eingabe, die Shell-Metazeichen enthält, kann zur Auslösung einer beliebigen Befehlsausführung verwendet werden.

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

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

Verwenden Sie cwd, um das Arbeitsverzeichnis anzugeben, von dem aus der Prozess erzeugt wird. Wenn nicht angegeben, wird standardmäßig das aktuelle Arbeitsverzeichnis vererbt. Wenn angegeben, der Pfad aber nicht existiert, gibt der untergeordnete 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 sein werden. Der Standardwert ist process.env.

undefined-Werte in env werden ignoriert.

Beispiel für die Ausführung von ls -lh /usr, Erfassung von stdout, stderr und dem Exit-Code:

CJSESM

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

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

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

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

import { spawn } from 'node:child_process'
const ls = spawn('ls', ['-lh', '/usr'])

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

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

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

Beispiel: Eine sehr aufwendige Methode zum Ausführen von ps ax | grep ssh

CJSESM

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

Beispiel zum Überprüfen auf fehlgeschlagene spawn:

CJSESM

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

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

Node.js überschreibt argv[0] beim Start mit process.execPath, daher stimmt process.argv[0] in einem Node.js-Unterprozess nicht mit dem argv0-Parameter überein, der von der Elternkomponente an spawn übergeben wird. Rufen Sie ihn stattdessen mit der Eigenschaft process.argv0 ab.

CJSESM

const { spawn } = require('node:child_process')
const controller = new AbortController()
const { signal } = controller
const grep = spawn('grep', ['ssh'], { signal })
grep.on('error', err => {
  // Dies wird mit err als AbortError aufgerufen, wenn der Controller abbricht
})
controller.abort() // Stoppt den untergeordneten Prozess

import { spawn } from 'node:child_process'
const controller = new AbortController()
const { signal } = controller
const grep = spawn('grep', ['ssh'], { signal })
grep.on('error', err => {
  // Dies wird mit err als AbortError aufgerufen, wenn der Controller abbricht
})
controller.abort() // Stoppt den untergeordneten Prozess

`options.detached`

Hinzugefügt in: v0.7.10

Unter Windows ermöglicht das Setzen von options.detached auf true, dass der untergeordnete Prozess nach dem Beenden des übergeordneten Prozesses weiterläuft. Der untergeordnete Prozess erhält sein eigenes Konsolenfenster. Sobald diese Option für einen untergeordneten Prozess aktiviert wurde, kann sie nicht mehr deaktiviert werden.

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

Standardmäßig wartet der übergeordnete Prozess auf das Beenden des getrennten untergeordneten Prozesses. 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 untergeordneten Prozess nicht in seinen Referenzzähler aufnehmen, sodass der übergeordnete Prozess unabhängig vom untergeordneten Prozess beendet werden kann, es sei denn, es besteht ein etablierter IPC-Kanal zwischen dem untergeordneten und dem übergeordneten Prozess.

Wenn Sie die Option detached verwenden, um einen lang laufenden Prozess zu starten, bleibt der Prozess nach dem Beenden des übergeordneten Prozesses nicht im Hintergrund aktiv, es sei denn, er erhält eine stdio-Konfiguration, die nicht mit dem übergeordneten Prozess verbunden ist. Wenn der stdio des übergeordneten Prozesses vererbt wird, bleibt der untergeordnete Prozess an das Steuerterminal gebunden.

Beispiel für einen lang laufenden Prozess, der durch Trennung und Ignorieren der Datei-Deskriptoren des übergeordneten stdio den Abbruch des übergeordneten Prozesses ignoriert:

CJSESM

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

Alternativ kann die Ausgabe des untergeordneten Prozesses in Dateien umgeleitet werden:

CJSESM

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

`options.stdio`

[Verlauf]

Version	Änderungen
v15.6.0, v14.18.0	Das `overlapped`-stdio-Flag hinzugefügt.
v3.3.1	Der Wert `0` wird nun als Dateideskriptor akzeptiert.
v0.7.10	Hinzugefügt in: v0.7.10

Die Option options.stdio wird verwendet, um die Pipes zu konfigurieren, die zwischen dem Eltern- und dem Kindprozess eingerichtet werden. Standardmäßig werden stdin, stdout und stderr des Kindes an die entsprechenden Streams subprocess.stdin, subprocess.stdout und subprocess.stderr des Objekts ChildProcess umgeleitet. Dies entspricht der Einstellung von options.stdio auf ['pipe', 'pipe', 'pipe'].

Der Einfachheit halber kann options.stdio eine der folgenden Zeichenketten sein:

'pipe': entspricht ['pipe', 'pipe', 'pipe'] (Standardwert)
'overlapped': entspricht ['overlapped', 'overlapped', 'overlapped']
'ignore': entspricht ['ignore', 'ignore', 'ignore']
'inherit': entspricht ['inherit', 'inherit', 'inherit'] oder [0, 1, 2]

Andernfalls ist der Wert von options.stdio ein Array, wobei jeder Index einem fd im Kind entspricht. Die fds 0, 1 und 2 entsprechen stdin, stdout und stderr. Zusätzliche fds können angegeben werden, um zusätzliche Pipes zwischen Elternteil und Kind zu erstellen. Der Wert ist einer der folgenden:

CJSESM

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

// Kind verwendet die Stdios des Elternteils.
spawn('prg', [], { stdio: 'inherit' })

// Kind wird erzeugt, wobei nur stderr geteilt wird.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] })

// Öffnet ein zusätzliches fd=4, um mit Programmen zu interagieren, die eine
// startd-ähnliche Schnittstelle präsentieren.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] })

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

// Kind verwendet die Stdios des Elternteils.
spawn('prg', [], { stdio: 'inherit' })

// Kind wird erzeugt, wobei nur stderr geteilt wird.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] })

// Öffnet ein zusätzliches fd=4, um mit Programmen zu interagieren, die eine
// startd-ähnliche Schnittstelle präsentieren.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] })

Es ist erwähnenswert, dass, wenn ein IPC-Kanal zwischen dem Eltern- und dem Kindprozess eingerichtet wird und der Kindprozess eine Node.js-Instanz ist, der Kindprozess mit dem nicht referenzierten IPC-Kanal (mit unref()) gestartet wird, bis der Kindprozess einen Ereignishandler für das Ereignis 'disconnect' oder das Ereignis 'message' registriert. Dies ermöglicht es dem Kindprozess, normal zu beenden, ohne dass der Prozess durch den offenen IPC-Kanal offen gehalten wird. Siehe auch: child_process.exec() und child_process.fork().

Synchroner Prozessaufbau

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

Derartige blockierende Aufrufe sind hauptsächlich nützlich, um allgemeine Skriptaufgaben zu vereinfachen und das Laden/Verarbeiten der Anwendungskonfiguration beim Start zu vereinfachen.

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

[Verlauf]

Version	Änderungen
v16.4.0, v14.18.0	Die Option `cwd` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v10.10.0	Die Option `input` kann jetzt jedes `TypedArray` oder ein `DataView` sein.
v8.8.0	Die Option `windowsHide` wird jetzt unterstützt.
v8.0.0	Die Option `input` kann jetzt ein `Uint8Array` sein.
v6.2.1, v4.5.0	Die Option `encoding` kann jetzt explizit auf `buffer` gesetzt werden.
v0.11.12	Hinzugefügt in: v0.11.12

file <string> Der Name oder Pfad der auszuführenden Datei.
args <string[]> Liste der String-Argumente.
options <Object>
- cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des untergeordneten Prozesses.
- input <string> | <Buffer> | <TypedArray> | <DataView> Der Wert, der als stdin an den erzeugten Prozess übergeben wird. Wenn stdio[0] auf 'pipe' gesetzt ist, überschreibt die Bereitstellung dieses Werts stdio[0].
- stdio <string> | <Array> Stdio-Konfiguration des untergeordneten Prozesses. 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> Umgebungs-Schlüssel-Wert-Paare. Standard: process.env.
- uid <number> Legt die Benutzeridentität des Prozesses fest (siehe setuid(2)).
- gid <number> Legt die Gruppenidentität des Prozesses fest (siehe setgid(2)).
- timeout <number> In Millisekunden die maximale Laufzeit des Prozesses. Standard: undefined.
- killSignal <string> | <integer> Der Signalwert, der verwendet werden soll, wenn der erzeugte Prozess beendet wird. Standard: 'SIGTERM'.
- maxBuffer <number> Größte zulässige Datenmenge in Bytes auf stdout oder stderr. Wenn überschritten, wird der untergeordnete Prozess beendet. Siehe Hinweise unter maxBuffer und Unicode. Standard: 1024 * 1024.
- encoding <string> Die verwendete Codierung für alle Stdio-Ein- und Ausgaben. Standard: 'buffer'.
- windowsHide <boolean> Blendet das Subprozess-Konsolenfenster aus, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
- shell <boolean> | <string> Wenn true, wird 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).
Rückgabewert: <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 untergeordnete Prozess vollständig geschlossen wurde. Wenn ein Timeout aufgetreten ist und killSignal gesendet wird, kehrt die Methode erst zurück, wenn der Prozess vollständig beendet wurde.

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

Wenn der Prozess ein Timeout hat oder einen von Null verschiedenen Exit-Code 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, geben Sie keine ungereinigten Benutzereingaben an diese Funktion weiter. Jede Eingabe, die Shell-Metazeichen enthält, kann verwendet werden, um die Ausführung beliebiger Befehle auszulösen.

CJSESM

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

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // stdout und stderr vom Kindprozess erfassen. Überschreibt das
    // Standardverhalten, child stderr an parent stderr zu streamen
    stdio: 'pipe',

    // utf8-Codierung für stdio-Pipes verwenden
    encoding: 'utf8',
  })

  console.log(stdout)
} catch (err) {
  if (err.code) {
    // Erzeugung des Kindprozesses fehlgeschlagen
    console.error(err.code)
  } else {
    // Kind wurde erzeugt, aber mit nicht-Null-Exit-Code beendet
    // Fehler enthält stdout und stderr vom Kind
    const { stdout, stderr } = err

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

import { execFileSync } from 'node:child_process'

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // stdout und stderr vom Kindprozess erfassen. Überschreibt das
    // Standardverhalten, child stderr an parent stderr zu streamen
    stdio: 'pipe',

    // utf8-Codierung für stdio-Pipes verwenden
    encoding: 'utf8',
  })

  console.log(stdout)
} catch (err) {
  if (err.code) {
    // Erzeugung des Kindprozesses fehlgeschlagen
    console.error(err.code)
  } else {
    // Kind wurde erzeugt, aber mit nicht-Null-Exit-Code beendet
    // Fehler enthält stdout und stderr vom Kind
    const { stdout, stderr } = err

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

`child_process.execSync(command[, options])`

[Verlauf]

Version	Änderungen
v16.4.0, v14.18.0	Die Option `cwd` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v10.10.0	Die Option `input` kann nun jedes `TypedArray` oder ein `DataView` sein.
v8.8.0	Die Option `windowsHide` wird jetzt unterstützt.
v8.0.0	Die Option `input` kann nun ein `Uint8Array` sein.
v0.11.12	Hinzugefügt in: v0.11.12

command <string> Der auszuführende Befehl.
options <Object>
- cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des untergeordneten Prozesses.
- input <string> | <Buffer> | <TypedArray> | <DataView> Der Wert, der als stdin an den erzeugten Prozess übergeben wird. Wenn stdio[0] auf 'pipe' gesetzt ist, überschreibt die Bereitstellung dieses Werts stdio[0].
- stdio <string> | <Array> Stdio-Konfiguration des untergeordneten Prozesses. 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> Umgebungs-Schlüssel-Wert-Paare. 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> Legt die Benutzeridentität des Prozesses fest. (Siehe setuid(2)).
- gid <number> Legt die Gruppenidentität des Prozesses fest. (Siehe setgid(2)).
- timeout <number> In Millisekunden die maximale Laufzeit des Prozesses. Standard: undefined.
- killSignal <string> | <integer> Der Signalwert, der verwendet wird, wenn der erzeugte Prozess beendet wird. Standard: 'SIGTERM'.
- maxBuffer <number> Größte zulässige Datenmenge in Byte auf stdout oder stderr. Wenn überschritten, wird der untergeordnete Prozess beendet und alle Ausgaben werden abgeschnitten. Siehe den Hinweis unter maxBuffer und Unicode. Standard: 1024 * 1024.
- encoding <string> Die verwendete Codierung für alle Stdio-Ein- und Ausgaben. Standard: 'buffer'.
- windowsHide <boolean> Blendet das Unterprozess-Konsolenfenster aus, das normalerweise auf Windows-Systemen erstellt würde. Standard: false.
Rückgabewert: <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 untergeordnete Prozess vollständig geschlossen wurde. Wenn ein Timeout aufgetreten ist und killSignal gesendet wird, kehrt die Methode erst zurück, wenn der Prozess vollständig beendet wurde. Wenn der untergeordnete Prozess das SIGTERM-Signal abfängt und verarbeitet und nicht beendet wird, wartet der übergeordnete Prozess, bis der untergeordnete Prozess beendet wurde.

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

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

[Verlauf]

Version	Änderungen
v16.4.0, v14.18.0	Die Option `cwd` kann ein WHATWG `URL`-Objekt mit dem Protokoll `file:` sein.
v10.10.0	Die Option `input` kann jetzt jedes `TypedArray` oder ein `DataView` sein.
v8.8.0	Die Option `windowsHide` wird jetzt unterstützt.
v8.0.0	Die Option `input` kann jetzt ein `Uint8Array` sein.
v5.7.0	Die Option `shell` wird jetzt unterstützt.
v6.2.1, v4.5.0	Die Option `encoding` kann jetzt explizit auf `buffer` gesetzt werden.
v0.11.12	Hinzugefügt in: v0.11.12

command <string> Der auszuführende Befehl.
args <string[]> Liste der String-Argumente.
options <Object>
- cwd <string> | <URL> Aktuelles Arbeitsverzeichnis des untergeordneten Prozesses.
- input <string> | <Buffer> | <TypedArray> | <DataView> Der Wert, der als stdin an den erzeugten Prozess übergeben wird. Wenn stdio[0] auf 'pipe' gesetzt ist, überschreibt die Angabe dieses Werts stdio[0].
- argv0 <string> Setzt explizit den Wert von argv[0], der an den untergeordneten Prozess gesendet wird. Dieser wird auf command gesetzt, wenn er nicht angegeben ist.
- stdio <string> | <Array> Stdio-Konfiguration des Kindes. Siehe child_process.spawn() stdio. Standard: 'pipe'.
- env <Object> Umgebungs-Schlüssel-Wert-Paare. 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> In Millisekunden die maximale Laufzeit des Prozesses. Standard: undefined.
- killSignal <string> | <integer> Der Signalwert, der verwendet wird, wenn der erzeugte Prozess beendet wird. Standard: 'SIGTERM'.
- maxBuffer <number> Größte Datenmenge in Bytes, die auf stdout oder stderr zulässig ist. Wenn überschritten, wird der untergeordnete Prozess beendet und die Ausgabe abgeschnitten. Siehe Vorbehalt unter maxBuffer und Unicode. Standard: 1024 * 1024.
- encoding <string> Die Codierung, die für alle Stdio-Eingaben und -Ausgaben verwendet wird. Standard: 'buffer'.
- shell <boolean> | <string> Wenn true, wird 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 werden keine Anführungszeichen oder Escape-Sequenzen für Argumente verwendet. Unter Unix wird dies ignoriert. Dies wird automatisch auf true gesetzt, wenn shell angegeben und CMD ist. Standard: false.
- windowsHide <boolean> Blendet das Subprozess-Konsolenfenster aus, das normalerweise auf Windows-Systemen erstellt wird. Standard: false.
Rückgabewert: <Object>
- pid <number> Pid des untergeordneten Prozesses.
- output <Array> Array der Ergebnisse aus 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 Signal, mit dem der Unterprozess beendet wurde, oder null, wenn der Unterprozess nicht aufgrund eines Signals beendet wurde.
- error <Error> Das Fehlerobjekt, wenn der untergeordnete Prozess fehlgeschlagen ist oder ein Timeout aufgetreten ist.

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

Klasse: `ChildProcess`

Hinzugefügt in: v2.2.0

Erweitert: <EventEmitter>

Instanzen von ChildProcess repräsentieren erzeugte untergeordnete Prozesse.

Instanzen von ChildProcess sollen nicht direkt erstellt 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'`

Hinzugefügt in: v0.7.7

code <number> Der Exit-Code, falls der untergeordnete Prozess selbst beendet wurde.
signal <string> Das Signal, mit dem der untergeordnete Prozess beendet wurde.

Das Ereignis 'close' wird ausgelöst, nachdem ein Prozess beendet wurde und die Stdio-Streams eines untergeordneten Prozesses geschlossen wurden. Dies unterscheidet sich vom Ereignis 'exit', da mehrere Prozesse dieselben Stdio-Streams gemeinsam nutzen können. Das Ereignis 'close' wird immer nach dem Ereignis 'exit' oder 'error' ausgelöst, falls der untergeordnete Prozess nicht erzeugt werden konnte.

CJSESM

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

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

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

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

import { spawn } from 'node:child_process'
const ls = spawn('ls', ['-lh', '/usr'])

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

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

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

Ereignis: `'disconnect'`

Hinzugefügt in: v0.7.2

Das Ereignis 'disconnect' wird ausgelöst, nachdem die Methode subprocess.disconnect() im übergeordneten Prozess oder process.disconnect() im untergeordneten Prozess aufgerufen wurde. Nach der Trennung 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 ausgelöst, wenn:

Der Prozess nicht erzeugt werden konnte.
Der Prozess nicht beendet werden konnte.
Das Senden einer Nachricht an den untergeordneten Prozess fehlgeschlagen ist.
Der untergeordnete Prozess über die Option signal abgebrochen wurde.

Das Ereignis 'exit' kann nach einem Fehler auftreten oder auch nicht. Wenn sowohl die Ereignisse 'exit' als auch 'error' überwacht werden, ist darauf zu achten, dass Handlerfunktionen nicht versehentlich mehrfach aufgerufen werden.

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

Ereignis: `'exit'`

Hinzugefügt in: v0.1.90

code <number> Der Exit-Code, falls der untergeordnete Prozess selbst beendet wurde.
signal <string> Das Signal, durch das der untergeordnete Prozess beendet wurde.

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

Wenn das Ereignis 'exit' ausgelöst wird, sind die Stdio-Streams des untergeordneten Prozesses möglicherweise noch geöffnet.

Node.js richtet Signalhandler 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).

Ereignis: `'message'`

Hinzugefügt in: v0.5.9

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

Das Ereignis 'message' wird ausgelöst, wenn ein untergeordneter 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 auf 'advanced' gesetzt wurde, die beim Erzeugen des untergeordneten Prozesses verwendet wird, kann das Argument message Daten enthalten, die JSON nicht darstellen kann. Siehe Erweiterte Serialisierung für weitere Details.

Ereignis: `'spawn'`

Hinzugefügt in: v15.1.0, v14.17.0

Das Ereignis 'spawn' wird ausgegeben, sobald der untergeordnete Prozess erfolgreich erzeugt wurde. Wenn der untergeordnete Prozess nicht erfolgreich erzeugt wird, wird das Ereignis 'spawn' nicht ausgegeben und stattdessen das Ereignis 'error' ausgegeben.

Wenn ausgegeben, kommt das Ereignis 'spawn' vor allen anderen Ereignissen und bevor Daten über stdout oder stderr empfangen werden.

Das Ereignis 'spawn' wird unabhängig davon ausgelöst, ob ein Fehler innerhalb des erzeugten Prozesses auftritt. Wenn beispielsweise bash some-command erfolgreich erzeugt wird, wird das Ereignis 'spawn' ausgelöst, obwohl bash möglicherweise die Erzeugung von some-command nicht schafft. Diese Einschränkung gilt auch bei Verwendung von { shell: true }.

`subprocess.channel`

[Verlauf]

Version	Änderungen
v14.0.0	Das Objekt stellt keine nativen C++-Bindungen mehr versehentlich zur Verfügung.
v7.1.0	Hinzugefügt in: v7.1.0

<Objekt> Eine Pipe, die den IPC-Kanal zum untergeordneten Prozess darstellt.

Die Eigenschaft subprocess.channel ist ein Verweis auf den IPC-Kanal des untergeordneten Prozesses. Wenn kein IPC-Kanal existiert, ist diese Eigenschaft undefined.

`subprocess.channel.ref()`

Hinzugefügt in: v7.1.0

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

`subprocess.channel.unref()`

Hinzugefügt in: v7.1.0

Diese Methode sorgt dafür, dass der IPC-Kanal die Ereignisschleife des übergeordneten Prozesses nicht mehr am Laufen hält und dieser beendet werden kann, auch wenn der Kanal geöffnet ist.

`subprocess.connected`

Hinzugefügt in: v0.7.2

<boolean> Wird auf false gesetzt, nachdem subprocess.disconnect() aufgerufen wurde.

Die Eigenschaft subprocess.connected gibt an, ob es noch möglich ist, Nachrichten von einem untergeordneten Prozess zu senden und zu empfangen. Wenn subprocess.connected false ist, ist es nicht mehr möglich, Nachrichten zu senden oder zu empfangen.

`subprocess.disconnect()`

Hinzugefügt in: v0.7.2

Schließt den IPC-Kanal zwischen übergeordneten und untergeordneten Prozessen und ermöglicht es dem untergeordneten Prozess, ordnungsgemäß zu beenden, sobald keine anderen Verbindungen ihn am Laufen halten. 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 auszutauschen.

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

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

`subprocess.exitCode`

<integer>

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

`subprocess.kill([signal])`

Hinzugefügt in: v0.1.90

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

Die Methode subprocess.kill() sendet ein Signal an den untergeordneten Prozess. Wenn kein Argument angegeben wird, erhält der Prozess das Signal 'SIGTERM'. Siehe signal(7) für eine Liste der verfügbaren Signale. Diese Funktion gibt true zurück, wenn kill(2) erfolgreich ist, und false andernfalls.

CJSESM

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

// Sende SIGHUP an den Prozess.
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}`)
})

// Sende SIGHUP an den Prozess.
grep.kill('SIGHUP')

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

Obwohl die Funktion kill heißt, beendet das an den untergeordneten Prozess gesendete Signal den Prozess möglicherweise nicht tatsächlich.

Siehe kill(2) als Referenz.

Unter Windows, wo POSIX-Signale nicht existieren, wird das Argument signal außer bei 'SIGKILL', 'SIGTERM', 'SIGINT' und 'SIGQUIT' ignoriert, und der Prozess wird immer gewaltsam und abrupt beendet (ähnlich wie 'SIGKILL'). Siehe Signalereignisse für weitere Details.

Unter Linux werden untergeordnete Prozesse von untergeordneten Prozessen nicht beendet, wenn versucht wird, ihren übergeordneten Prozess zu beenden. Dies kann vorkommen, wenn ein neuer Prozess in einer Shell oder mit der Option shell von ChildProcess ausgeführt wird:

CJSESM

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() // Beendet den Node.js-Prozess in der Shell nicht.
}, 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() // Beendet den Node.js-Prozess in der Shell nicht.
}, 2000)

`subprocess[Symbol.dispose]()`

Hinzugefügt in: v20.5.0, v18.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

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

`subprocess.killed`

Hinzugefügt in: v0.5.10

<boolean> Wird auf true gesetzt, nachdem subprocess.kill() erfolgreich ein Signal an den Kindprozess gesendet hat.

Die Eigenschaft subprocess.killed gibt an, ob der Kindprozess erfolgreich ein Signal von subprocess.kill() empfangen hat. Die Eigenschaft killed gibt nicht an, dass der Kindprozess beendet wurde.

`subprocess.pid`

Hinzugefügt in: v0.1.90

<integer> | <undefined>

Gibt die Prozess-ID (PID) des Kindprozesses zurück. Wenn der Kindprozess aufgrund von Fehlern nicht gestartet werden kann, ist der Wert undefined und error wird emittiert.

CJSESM

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

Hinzugefügt in: v0.7.10

Ein Aufruf von subprocess.ref() nach einem Aufruf von subprocess.unref() stellt den entfernten Referenzzähler für den Kindprozess wieder her und zwingt den Elternprozess, auf das Beenden des Kindprozesses zu warten, bevor er selbst beendet wird.

CJSESM

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])`

[Verlauf]

Version	Änderungen
v5.8.0	Der Parameter `options` und insbesondere die Option `keepOpen` werden jetzt unterstützt.
v5.0.0	Diese Methode gibt jetzt einen booleschen Wert für die Flusskontrolle zurück.
v4.0.0	Der Parameter `callback` wird jetzt unterstützt.
v0.5.9	Hinzugefügt in: v0.5.9

message <Objekt>
sendHandle <Handle> | <undefiniert> undefined oder ein net.Socket, net.Server oder dgram.Socket Objekt.
options <Objekt> Das options-Argument ist, falls vorhanden, ein Objekt, das zum Parametrisieren des Sendens bestimmter Handle-Typen verwendet wird. options unterstützt die folgenden Eigenschaften:
- keepOpen <boolean> Ein Wert, der verwendet werden kann, wenn Instanzen von net.Socket übergeben werden. Wenn true, bleibt der Socket im sendenden Prozess geöffnet. Standardwert: false.
callback <Funktion>
Rückgabewert: <boolean>

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

Die Nachricht wird durch Serialisierung und Parsing verarbeitet. Die resultierende Nachricht ist möglicherweise nicht identisch mit der ursprünglich gesendeten Nachricht.

Beispiel im übergeordneten Skript:

CJSESM

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

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

// Führt dazu, dass das Kind ausgibt: 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)
})

// Führt dazu, dass das Kind ausgibt: CHILD got message: { hello: 'world' }
forkedProcess.send({ hello: 'world' })

Und dann könnte das Kindskript, 'sub.js', so aussehen:

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

// Führt dazu, dass der Parent ausgibt: PARENT got message: { foo: 'bar', baz: null }
process.send({ foo: 'bar', baz: NaN })

Kind-Node.js-Prozesse verfügen über eine eigene Methode process.send(), mit der der Kindprozess Nachrichten an den Elternprozess zurücksenden kann.

Es gibt einen Sonderfall beim Senden einer {cmd: 'NODE_foo'}-Nachricht. Nachrichten, die ein NODE_-Präfix in der cmd-Eigenschaft enthalten, sind für die Verwendung im Node.js-Kern reserviert und werden nicht im Ereignis 'message' des Kindes ausgelöst. Solche Nachrichten werden stattdessen über das Ereignis 'internalMessage' ausgelöst und intern von Node.js verarbeitet. Anwendungen sollten die Verwendung solcher Nachrichten oder das Abhören von 'internalMessage'-Ereignissen vermeiden, da diese sich ohne vorherige Ankündigung ändern können.

Das optionale Argument sendHandle, das an subprocess.send() übergeben werden kann, dient zum Übergeben eines TCP-Server- oder Socket-Objekts an den Kindprozess. Der Kindprozess erhält das Objekt als zweites Argument, das an die Callback-Funktion übergeben wird, die für das Ereignis 'message' registriert ist. Alle Daten, die im Socket empfangen und gepuffert werden, werden nicht an das Kind gesendet. Das Senden von IPC-Sockets wird unter Windows nicht unterstützt.

Der optionale callback ist eine Funktion, die aufgerufen wird, nachdem die Nachricht gesendet wurde, aber bevor der Kindprozess sie möglicherweise empfangen hat. 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 Objekt ChildProcess ausgelöst. Dies kann beispielsweise passieren, wenn der Kindprozess bereits beendet wurde.

subprocess.send() gibt false zurück, wenn der Kanal geschlossen ist oder wenn der Rückstand nicht gesendeter Nachrichten einen Schwellenwert überschreitet, der es unklug macht, mehr zu senden. Andernfalls gibt die Methode true zurück. Die callback-Funktion kann verwendet werden, um die Flusskontrolle zu implementieren.

Beispiel: Senden eines Serverobjekts

Das Argument sendHandle kann beispielsweise verwendet werden, um den Handle eines TCP-Serverobjekts an den untergeordneten Prozess zu übergeben, wie im folgenden Beispiel gezeigt:

CJSESM

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

const subprocess = fork('subprocess.js')

// Serverobjekt öffnen und den Handle senden.
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')

// Serverobjekt öffnen und den Handle senden.
const server = createServer()
server.on('connection', socket => {
  socket.end('handled by parent')
})
server.listen(1337, () => {
  subprocess.send('server', server)
})

Der untergeordnete Prozess würde das Serverobjekt dann wie folgt empfangen:

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

Sobald der Server nun zwischen Eltern- und Kindprozess geteilt wird, können einige Verbindungen vom Eltern- und einige vom Kindprozess bearbeitet werden.

Während das obige Beispiel einen Server verwendet, der mit dem Modul node:net erstellt wurde, verwenden Server des Moduls node:dgram genau den gleichen Workflow, mit der Ausnahme, dass sie auf einem Ereignis 'message' anstelle von 'connection' lauschen und server.bind() anstelle von server.listen() verwenden. Dies wird jedoch nur auf Unix-Plattformen unterstützt.

Beispiel: Senden eines Socket-Objekts

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

CJSESM

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

const normal = fork('subprocess.js', ['normal'])
const special = fork('subprocess.js', ['special'])

// Server öffnen und Sockets an Kindprozess senden. `pauseOnConnect` verwenden, um zu verhindern,
// dass die Sockets gelesen werden, bevor sie an den Kindprozess gesendet werden.
const server = createServer({ pauseOnConnect: true })
server.on('connection', socket => {
  // Wenn dies besondere Priorität hat...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket)
    return
  }
  // Dies ist normale Priorität.
  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'])

// Server öffnen und Sockets an Kindprozess senden. `pauseOnConnect` verwenden, um zu verhindern,
// dass die Sockets gelesen werden, bevor sie an den Kindprozess gesendet werden.
const server = createServer({ pauseOnConnect: true })
server.on('connection', socket => {
  // Wenn dies besondere Priorität hat...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket)
    return
  }
  // Dies ist normale Priorität.
  normal.send('socket', socket)
})
server.listen(1337)

subprocess.js würde den Socket-Handle als zweites Argument an die Ereignis-Callback-Funktion übergeben erhalten:

process.on('message', (m, socket) => {
  if (m === 'socket') {
    if (socket) {
      // Überprüfen, ob der Client-Socket existiert.
      // Es ist möglich, dass der Socket zwischen dem Zeitpunkt, an dem er gesendet wird, und dem Zeitpunkt, an dem er im Kindprozess empfangen wird, geschlossen wird.
      socket.end(`Request handled with ${process.argv[2]} priority`)
    }
  }
})

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

Alle 'message'-Handler im Unterprozess sollten überprüfen, ob socket existiert, da die Verbindung während der Zeit, die benötigt wird, um die Verbindung an das Kind zu senden, geschlossen sein kann.

`subprocess.signalCode`

<string> | <null>

Die Eigenschaft subprocess.signalCode gibt das Signal an, das der untergeordnete Prozess gegebenenfalls empfangen hat, andernfalls null.

`subprocess.spawnargs`

<Array>

Die Eigenschaft subprocess.spawnargs stellt die vollständige Liste der Befehlszeilenargumente dar, mit denen der untergeordnete Prozess gestartet wurde.

`subprocess.spawnfile`

<string>

Die Eigenschaft subprocess.spawnfile gibt den ausführbaren Dateinamen des gestarteten untergeordneten Prozesses an.

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

`subprocess.stderr`

Hinzugefügt in: v0.1.90

<stream.Readable> | <null> | <undefined>

Ein Readable Stream, der den stderr des untergeordneten Prozesses darstellt.

Wenn der untergeordnete Prozess mit stdio[2] auf einen anderen Wert als 'pipe' gesetzt wurde, 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 untergeordnete Prozess nicht erfolgreich erzeugt werden konnte.

`subprocess.stdin`

Hinzugefügt in: v0.1.90

<stream.Writable> | <null> | <undefined>

Ein Writable Stream, der den stdin des untergeordneten Prozesses darstellt.

Wenn ein untergeordneter Prozess darauf wartet, seine gesamte Eingabe zu lesen, wird der untergeordnete Prozess erst fortgesetzt, wenn dieser Stream über end() geschlossen wurde.

Wenn der untergeordnete Prozess mit stdio[0] auf einen anderen Wert als 'pipe' gesetzt wurde, 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 untergeordnete Prozess nicht erfolgreich erzeugt werden konnte.

`subprocess.stdio`

Hinzugefügt in: v0.7.10

<Array>

Ein spärliches Array von Pipes zum untergeordneten Prozess, entsprechend den Positionen in der Option stdio, die an child_process.spawn() übergeben und auf den Wert 'pipe' gesetzt wurden. subprocess.stdio[0], subprocess.stdio[1] und subprocess.stdio[2] sind auch als subprocess.stdin, subprocess.stdout und subprocess.stderr verfügbar.

Im folgenden Beispiel ist nur der fd 1 (stdout) des Kindes als Pipe konfiguriert, daher ist nur subprocess.stdio[1] des Elternteils ein Stream, alle anderen Werte im Array sind null.

CJSESM

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, // Verwendet den stdin des Elternteils für das Kind.
    'pipe', // Leitet stdout des Kindes an den Elternteil weiter.
    fs.openSync('err.out', 'w'), // Leitet stderr des Kindes an eine Datei weiter.
  ],
})

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, // Verwendet den stdin des Elternteils für das Kind.
    'pipe', // Leitet stdout des Kindes an den Elternteil weiter.
    fs.openSync('err.out', 'w'), // Leitet stderr des Kindes an eine Datei weiter.
  ],
})

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)

Die Eigenschaft subprocess.stdio kann undefined sein, wenn der untergeordnete Prozess nicht erfolgreich erzeugt werden konnte.

`subprocess.stdout`

Hinzugefügt in: v0.1.90

<stream.Readable> | <null> | <undefined>

Ein Readable Stream, der die stdout des Kindprozesses darstellt.

Wenn der Kindprozess mit stdio[1] auf einen anderen Wert als 'pipe' gesetzt wurde, ist dies null.

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

CJSESM

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

Die Eigenschaft subprocess.stdout kann null oder undefined sein, wenn der Kindprozess nicht erfolgreich erzeugt werden konnte.

`subprocess.unref()`

Hinzugefügt in: v0.7.10

Standardmäßig wartet der übergeordnete Prozess darauf, dass der getrennte Kindprozess beendet wird. Um zu verhindern, dass der übergeordnete Prozess auf das Beenden eines gegebenen subprocess wartet, verwenden Sie die Methode subprocess.unref(). Dies bewirkt, dass die Ereignisschleife des übergeordneten Prozesses den Kindprozess nicht in seine Referenzzählung aufnimmt, sodass der übergeordnete Prozess unabhängig vom Kindprozess beendet werden kann, es sei denn, es besteht ein etablierter IPC-Kanal zwischen dem Kind- und dem übergeordneten Prozess.

CJSESM

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

`maxBuffer` und Unicode

Die Option maxBuffer gibt die maximal zulässige Anzahl von Bytes auf stdout oder stderr an. Wird dieser Wert überschritten, wird der untergeordnete Prozess beendet. Dies wirkt sich auf Ausgaben aus, die mehrbytetige Zeichenkodierungen wie UTF-8 oder UTF-16 enthalten. Beispielsweise sendet console.log('中文测试') 13 UTF-8-codierte Bytes an stdout, obwohl nur 4 Zeichen vorhanden sind.

Shell-Anforderungen

Die Shell sollte den Schalter -c verstehen. Wenn die Shell 'cmd.exe' ist, sollte sie die Schalter /d /s /c verstehen und die Befehlszeilenverarbeitung sollte kompatibel sein.

Standard-Windows-Shell

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

Erweiterte Serialisierung

Hinzugefügt in: v13.2.0, v12.16.0

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

Dieses Format ist jedoch keine vollständige Obermenge von JSON, und z. B. Eigenschaften, die für Objekte solcher integrierten Typen gesetzt sind, werden nicht durch den Serialisierungsschritt weitergegeben. Darüber hinaus ist die Leistung möglicherweise nicht äquivalent zu der von JSON, abhängig von der Struktur der übergebenen Daten. Daher erfordert diese Funktion das Opt-in, indem die Option serialization auf 'advanced' gesetzt wird, wenn child_process.spawn() oder child_process.fork() aufgerufen wird.

Unterprozess ​

Asynchrone Prozesserstellung ​

Ausführen von .bat- und .cmd-Dateien unter Windows ​

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

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

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

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

options.detached ​

options.stdio ​

Synchroner Prozessaufbau ​

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

child_process.execSync(command[, options]) ​

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

Klasse: ChildProcess ​

Ereignis: 'close' ​

Ereignis: 'disconnect' ​

Ereignis: 'error' ​

Ereignis: 'exit' ​

Ereignis: 'message' ​

Ereignis: 'spawn' ​

subprocess.channel ​

subprocess.channel.ref() ​

subprocess.channel.unref() ​

subprocess.connected ​

subprocess.disconnect() ​

subprocess.exitCode ​

subprocess.kill([signal]) ​

subprocess[Symbol.dispose]() ​

subprocess.killed ​

subprocess.pid ​

subprocess.ref() ​

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

Beispiel: Senden eines Serverobjekts ​

Beispiel: Senden eines Socket-Objekts ​

subprocess.signalCode ​

subprocess.spawnargs ​

subprocess.spawnfile ​

subprocess.stderr ​

subprocess.stdin ​

subprocess.stdio ​

subprocess.stdout ​

subprocess.unref() ​

maxBuffer und Unicode ​

Shell-Anforderungen ​

Standard-Windows-Shell ​

Erweiterte Serialisierung ​

Unterprozess

Asynchrone Prozesserstellung

Ausführen von `.bat`- und `.cmd`-Dateien unter Windows

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

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

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

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

`options.detached`

`options.stdio`

Synchroner Prozessaufbau

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

`child_process.execSync(command[, options])`

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

Klasse: `ChildProcess`

Ereignis: `'close'`

Ereignis: `'disconnect'`

Ereignis: `'error'`

Ereignis: `'exit'`

Ereignis: `'message'`

Ereignis: `'spawn'`

`subprocess.channel`

`subprocess.channel.ref()`

`subprocess.channel.unref()`

`subprocess.connected`

`subprocess.disconnect()`

`subprocess.exitCode`

`subprocess.kill([signal])`

`subprocess[Symbol.dispose]()`

`subprocess.killed`

`subprocess.pid`

`subprocess.ref()`

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

Beispiel: Senden eines Serverobjekts

Beispiel: Senden eines Socket-Objekts

`subprocess.signalCode`

`subprocess.spawnargs`

`subprocess.spawnfile`

`subprocess.stderr`

`subprocess.stdin`

`subprocess.stdio`

`subprocess.stdout`

`subprocess.unref()`

`maxBuffer` und Unicode

Shell-Anforderungen

Standard-Windows-Shell

Erweiterte Serialisierung