Processus enfant

[Stable : 2 - Stable]

Le module node:child_process permet de générer des processus fils de manière similaire, mais pas identique, à popen(3). Cette fonctionnalité est principalement fournie par la fonction child_process.spawn() :

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

Par défaut, des pipes pour stdin, stdout et stderr sont établies entre le processus parent Node.js et le processus fils généré. Ces pipes ont une capacité limitée (et spécifique à la plateforme). Si le processus fils écrit sur stdout au-delà de cette limite sans que la sortie ne soit capturée, le processus fils se bloque en attendant que le buffer de la pipe accepte plus de données. Ceci est identique au comportement des pipes dans le shell. Utilisez l'option { stdio: 'ignore' } si la sortie ne sera pas consommée.

La recherche de commande est effectuée à l'aide de la variable d'environnement options.env.PATH si env est dans l'objet options. Sinon, process.env.PATH est utilisé. Si options.env est défini sans PATH, la recherche sous Unix est effectuée sur un chemin de recherche par défaut de /usr/bin:/bin (voir le manuel de votre système d'exploitation pour execvpe/execvp), sous Windows la variable d'environnement PATH du processus courant est utilisée.

Sous Windows, les variables d'environnement ne tiennent pas compte de la casse. Node.js trie lexicographiquement les clés env et utilise la première qui correspond sans tenir compte de la casse. Seule la première entrée (dans l'ordre lexicographique) sera passée au processus fils. Cela peut entraîner des problèmes sous Windows lors du passage d'objets à l'option env qui ont plusieurs variantes de la même clé, telles que PATH et Path.

La méthode child_process.spawn() génère le processus fils de manière asynchrone, sans bloquer la boucle d'événements Node.js. La fonction child_process.spawnSync() fournit des fonctionnalités équivalentes de manière synchrone, bloquant la boucle d'événements jusqu'à ce que le processus généré se termine ou soit interrompu.

Pour plus de commodité, le module node:child_process fournit quelques alternatives synchrones et asynchrones à child_process.spawn() et child_process.spawnSync(). Chacune de ces alternatives est implémentée par-dessus child_process.spawn() ou child_process.spawnSync().

child_process.exec() : génère un shell et exécute une commande dans ce shell, passant stdout et stderr à une fonction de rappel à la fin.
child_process.execFile() : similaire à child_process.exec() sauf qu'il génère la commande directement sans d'abord générer un shell par défaut.
child_process.fork() : génère un nouveau processus Node.js et appelle un module spécifié avec un canal de communication IPC établi qui permet d'envoyer des messages entre le parent et l'enfant.
child_process.execSync() : une version synchrone de child_process.exec() qui bloquera la boucle d'événements Node.js.
child_process.execFileSync() : une version synchrone de child_process.execFile() qui bloquera la boucle d'événements Node.js.

Pour certains cas d'utilisation, tels que l'automatisation des scripts shell, les équivalents synchrones peuvent être plus pratiques. Dans de nombreux cas, cependant, les méthodes synchrones peuvent avoir un impact significatif sur les performances en raison du blocage de la boucle d'événements pendant que les processus générés se terminent.

Création de processus asynchrones

Les méthodes child_process.spawn(), child_process.fork(), child_process.exec(), et child_process.execFile() suivent toutes le modèle de programmation asynchrone idiomatique typique des autres API Node.js.

Chacune de ces méthodes renvoie une instance ChildProcess. Ces objets implémentent l'API EventEmitter de Node.js, permettant au processus parent d'enregistrer des fonctions d'écoute appelées lorsque certains événements se produisent pendant le cycle de vie du processus enfant.

Les méthodes child_process.exec() et child_process.execFile() permettent également de spécifier une fonction callback optionnelle qui est invoquée lorsque le processus enfant se termine.

Lancement de fichiers `.bat` et `.cmd` sous Windows

L'importance de la distinction entre child_process.exec() et child_process.execFile() peut varier selon la plateforme. Sur les systèmes d'exploitation de type Unix (Unix, Linux, macOS), child_process.execFile() peut être plus efficace car il ne génère pas d'interpréteur de commandes par défaut. Sous Windows, cependant, les fichiers .bat et .cmd ne sont pas exécutables seuls sans terminal et ne peuvent donc pas être lancés à l'aide de child_process.execFile(). Sous Windows, les fichiers .bat et .cmd peuvent être invoqués à l'aide de child_process.spawn() avec l'option shell définie, avec child_process.exec(), ou en lançant cmd.exe et en passant le fichier .bat ou .cmd comme argument (ce que font l'option shell et child_process.exec()). Dans tous les cas, si le nom du fichier script contient des espaces, il doit être entre guillemets.

CJSESM

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

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

// Script avec des espaces dans le nom de fichier :
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true })
// ou :
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
})

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

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

// Script avec des espaces dans le nom de fichier :
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true })
// ou :
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
})

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

[Historique]

Version	Modifications
v15.4.0	Prise en charge de AbortSignal ajoutée.
v16.4.0, v14.18.0	L'option `cwd` peut être un objet `URL` WHATWG utilisant le protocole `file:`.
v8.8.0	L'option `windowsHide` est désormais prise en charge.
v0.1.90	Ajouté dans : v0.1.90

command <string> La commande à exécuter, avec des arguments séparés par des espaces.
options <Object>
- cwd <string> | <URL> Répertoire de travail courant du processus enfant. Valeur par défaut : process.cwd().
- env <Object> Paires clé-valeur de l'environnement. Valeur par défaut : process.env.
- encoding <string> Valeur par défaut : 'utf8'
- shell <string> Interpréteur de commandes pour exécuter la commande. Voir Conditions requises pour l'interpréteur de commandes et Interpréteur de commandes Windows par défaut. Valeur par défaut : '/bin/sh' sous Unix, process.env.ComSpec sous Windows.
- signal <AbortSignal> permet d'interrompre le processus enfant à l'aide d'un AbortSignal.
- timeout <number> Valeur par défaut : 0
- maxBuffer <number> Quantité maximale de données en octets autorisée sur stdout ou stderr. Si cette limite est dépassée, le processus enfant est terminé et toute sortie est tronquée. Voir la mise en garde à maxBuffer et Unicode. Valeur par défaut : 1024 * 1024.
- killSignal <string> | <integer> Valeur par défaut : 'SIGTERM'
- uid <number> Définit l'identité utilisateur du processus (voir setuid(2)).
- gid <number> Définit l'identité de groupe du processus (voir setgid(2)).
- windowsHide <boolean> Masquer la fenêtre de console du sous-processus qui serait normalement créée sur les systèmes Windows. Valeur par défaut : false.
callback <Function> appelé avec la sortie lorsque le processus se termine.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
Retourne : <ChildProcess>

Génère un interpréteur de commandes, puis exécute la commande dans cet interpréteur de commandes, en mettant en mémoire tampon toute sortie générée. La chaîne de caractères command passée à la fonction exec est traitée directement par l'interpréteur de commandes et les caractères spéciaux (varient en fonction de l'interpréteur de commandes) doivent être traités en conséquence :

CJSESM

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

exec('"/path/to/test file/test.sh" arg1 arg2')
// Des guillemets doubles sont utilisés pour que l'espace dans le chemin ne soit pas interprété comme
// un délimiteur de plusieurs arguments.

exec('echo "The \\$HOME variable is $HOME"')
// La variable $HOME est échappée dans le premier cas, mais pas dans le second.

import { exec } from 'node:child_process'

exec('"/path/to/test file/test.sh" arg1 arg2')
// Des guillemets doubles sont utilisés pour que l'espace dans le chemin ne soit pas interprété comme
// un délimiteur de plusieurs arguments.

exec('echo "The \\$HOME variable is $HOME"')
// La variable $HOME est échappée dans le premier cas, mais pas dans le second.

Ne jamais passer d'entrée utilisateur non nettoyée à cette fonction. Toute entrée contenant des métacaractères shell peut être utilisée pour déclencher l'exécution de commandes arbitraires.

Si une fonction callback est fournie, elle est appelée avec les arguments (error, stdout, stderr). En cas de succès, error sera null. En cas d'erreur, error sera une instance de Error. La propriété error.code sera le code de sortie du processus. Par convention, tout code de sortie autre que 0 indique une erreur. error.signal sera le signal qui a terminé le processus.

Les arguments stdout et stderr passés au rappel contiendront la sortie stdout et stderr du processus enfant. Par défaut, Node.js décodera la sortie en UTF-8 et passera des chaînes de caractères au rappel. L'option encoding peut être utilisée pour spécifier le codage de caractères utilisé pour décoder la sortie stdout et stderr. Si encoding est 'buffer', ou un codage de caractères non reconnu, des objets Buffer seront passés au rappel à la place.

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

Si timeout est supérieur à 0, le processus parent enverra le signal identifié par la propriété killSignal (la valeur par défaut est 'SIGTERM') si le processus enfant dure plus de timeout millisecondes.

Contrairement à l'appel système POSIX exec(3), child_process.exec() ne remplace pas le processus existant et utilise un interpréteur de commandes pour exécuter la commande.

Si cette méthode est appelée en tant que version util.promisify(), elle renvoie une Promise pour un Object avec les propriétés stdout et stderr. L'instance ChildProcess renvoyée est attachée à la Promise en tant que propriété child. En cas d'erreur (y compris toute erreur entraînant un code de sortie autre que 0), une promesse rejetée est renvoyée, avec le même objet error donné dans le rappel, mais avec deux propriétés supplémentaires stdout et 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()

Si l'option signal est activée, l'appel de .abort() sur le AbortController correspondant est similaire à l'appel de .kill() sur le processus enfant, sauf que l'erreur passée au rappel sera une AbortError :

CJSESM

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

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

[Historique]

Version	Modifications
v16.4.0, v14.18.0	L'option `cwd` peut être un objet `URL` WHATWG utilisant le protocole `file:`
v15.4.0, v14.17.0	La prise en charge d'AbortSignal a été ajoutée.
v8.8.0	L'option `windowsHide` est désormais prise en charge.
v0.1.91	Ajouté dans : v0.1.91

file <string> Le nom ou le chemin du fichier exécutable à exécuter.
args <string[]> Liste des arguments de type chaîne de caractères.
options <Object>
- cwd <string> | <URL> Répertoire de travail courant du processus enfant.
- env <Object> Pares clés-valeurs de l'environnement. Valeur par défaut : process.env.
- encoding <string> Valeur par défaut : 'utf8'
- timeout <number> Valeur par défaut : 0
- maxBuffer <number> Quantité maximale de données en octets autorisée sur stdout ou stderr. Si cette limite est dépassée, le processus enfant est terminé et toute sortie est tronquée. Voir avertissement sur maxBuffer et Unicode. Valeur par défaut : 1024 * 1024.
- killSignal <string> | <integer> Valeur par défaut : 'SIGTERM'
- uid <number> Définit l'identité utilisateur du processus (voir setuid(2)).
- gid <number> Définit l'identité de groupe du processus (voir setgid(2)).
- windowsHide <boolean> Masquer la fenêtre de console du sous-processus qui serait normalement créée sur les systèmes Windows. Valeur par défaut : false.
- windowsVerbatimArguments <boolean> Aucune citation ou échappement des arguments n'est effectué sur Windows. Ignoré sur Unix. Valeur par défaut : false.
- shell <boolean> | <string> Si true, exécute command à l'intérieur d'un shell. Utilise '/bin/sh' sur Unix et process.env.ComSpec sur Windows. Un shell différent peut être spécifié sous forme de chaîne de caractères. Voir Exigences relatives au shell et Shell Windows par défaut. Valeur par défaut : false (pas de shell).
- signal <AbortSignal> permet d'avorter le processus enfant à l'aide d'un AbortSignal.
callback <Function> Appelée avec la sortie lorsque le processus se termine.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
Retourne : <ChildProcess>

La fonction child_process.execFile() est similaire à child_process.exec(), sauf qu'elle ne génère pas de shell par défaut. Au lieu de cela, le fichier exécutable file spécifié est généré directement en tant que nouveau processus, ce qui le rend légèrement plus efficace que child_process.exec().

Les mêmes options que child_process.exec() sont prises en charge. Étant donné qu'un shell n'est pas généré, les comportements tels que la redirection E/S et le classement des fichiers ne sont pas pris en charge.

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

Les arguments stdout et stderr passés au rappel contiendront la sortie stdout et stderr du processus enfant. Par défaut, Node.js décode la sortie au format UTF-8 et transmet des chaînes de caractères au rappel. L'option encoding peut être utilisée pour spécifier l'encodage de caractères utilisé pour décoder la sortie stdout et stderr. Si encoding est 'buffer' ou un encodage de caractères non reconnu, des objets Buffer seront transmis au rappel à la place.

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

Si l'option shell est activée, ne pas transmettre d'entrée utilisateur non désinfectée à cette fonction. Toute entrée contenant des métacaractères shell peut être utilisée pour déclencher l'exécution de commandes arbitraires.

CJSESM

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

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

[Historique]

Version	Modifications
v17.4.0, v16.14.0	Le paramètre `modulePath` peut être un objet `URL` WHATWG utilisant le protocole `file:`
v16.4.0, v14.18.0	L'option `cwd` peut être un objet `URL` WHATWG utilisant le protocole `file:`
v15.13.0, v14.18.0	`timeout` a été ajouté.
v15.11.0, v14.18.0	`killSignal` pour `AbortSignal` a été ajouté.
v15.6.0, v14.17.0	La prise en charge de `AbortSignal` a été ajoutée.
v13.2.0, v12.16.0	L'option `serialization` est maintenant prise en charge.
v8.0.0	L'option `stdio` peut maintenant être une chaîne de caractères.
v6.4.0	L'option `stdio` est maintenant prise en charge.
v0.5.0	Ajouté dans : v0.5.0

modulePath <string> | <URL> Le module à exécuter dans le processus enfant.
args <string[]> Liste d'arguments de type chaîne de caractères.
options <Object>
- cwd <string> | <URL> Répertoire courant du processus enfant.
- detached <boolean> Prépare le processus enfant à s'exécuter indépendamment de son processus parent. Le comportement spécifique dépend de la plateforme, voir options.detached).
- env <Object> Paires clé-valeur de l'environnement. Valeur par défaut : process.env.
- execPath <string> Exécutable utilisé pour créer le processus enfant.
- execArgv <string[]> Liste d'arguments de type chaîne de caractères passés à l'exécutable. Valeur par défaut : process.execArgv.
- gid <number> Définit l'identité de groupe du processus (voir setgid(2)).
- serialization <string> Spécifie le type de sérialisation utilisé pour l'envoi de messages entre les processus. Les valeurs possibles sont 'json' et 'advanced'. Voir Sérialisation avancée pour plus de détails. Valeur par défaut : 'json'.
- signal <AbortSignal> Permet de fermer le processus enfant à l'aide d'un AbortSignal.
- killSignal <string> | <integer> La valeur du signal à utiliser lorsque le processus créé sera tué par expiration du délai ou signal d'annulation. Valeur par défaut : 'SIGTERM'.
- silent <boolean> Si true, stdin, stdout et stderr du processus enfant seront redirigés vers le processus parent, sinon ils seront hérités du processus parent, voir les options 'pipe' et 'inherit' pour child_process.spawn()'s stdio pour plus de détails. Valeur par défaut : false.
- stdio <Array> | <string> Voir child_process.spawn()'s stdio. Lorsque cette option est fournie, elle remplace silent. Si la variante tableau est utilisée, elle doit contenir exactement un élément avec la valeur 'ipc' ou une erreur sera levée. Par exemple [0, 1, 2, 'ipc'].
- uid <number> Définit l'identité de l'utilisateur du processus (voir setuid(2)).
- windowsVerbatimArguments <boolean> Aucune citation ou échappement des arguments n'est effectué sous Windows. Ignoré sous Unix. Valeur par défaut : false.
- timeout <number> En millisecondes, durée maximale d'exécution autorisée pour le processus. Valeur par défaut : undefined.
Retourne : <ChildProcess>

La méthode child_process.fork() est un cas particulier de child_process.spawn() utilisée spécifiquement pour générer de nouveaux processus Node.js. Comme child_process.spawn(), un objet ChildProcess est retourné. Le ChildProcess retourné aura un canal de communication supplémentaire intégré qui permet le passage de messages entre le parent et l'enfant. Voir subprocess.send() pour plus de détails.

Gardez à l'esprit que les processus enfants Node.js générés sont indépendants du parent, à l'exception du canal de communication IPC qui est établi entre les deux. Chaque processus a sa propre mémoire, avec ses propres instances V8. En raison des allocations de ressources supplémentaires requises, la génération d'un grand nombre de processus enfants Node.js n'est pas recommandée.

Par défaut, child_process.fork() générera de nouvelles instances Node.js en utilisant le process.execPath du processus parent. La propriété execPath dans l'objet options permet d'utiliser un chemin d'exécution alternatif.

Les processus Node.js lancés avec un execPath personnalisé communiqueront avec le processus parent en utilisant le descripteur de fichier (fd) identifié à l'aide de la variable d'environnement NODE_CHANNEL_FD sur le processus enfant.

Contrairement à l'appel système POSIX fork(2), child_process.fork() ne clone pas le processus actuel.

L'option shell disponible dans child_process.spawn() n'est pas prise en charge par child_process.fork() et sera ignorée si elle est définie.

Si l'option signal est activée, appeler .abort() sur le AbortController correspondant est similaire à appeler .kill() sur le processus enfant, sauf que l'erreur passée au rappel sera une AbortError :

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 => {
    // Ceci sera appelé avec err étant une AbortError si le contrôleur annule
  })
  controller.abort() // Arrête le processus enfant
}

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 => {
    // Ceci sera appelé avec err étant une AbortError si le contrôleur annule
  })
  controller.abort() // Arrête le processus enfant
}

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

[Historique]

Version	Modifications
v16.4.0, v14.18.0	L'option `cwd` peut être un objet `URL` WHATWG utilisant le protocole `file:`
v15.13.0, v14.18.0	`timeout` a été ajouté.
v15.11.0, v14.18.0	`killSignal` pour `AbortSignal` a été ajouté.
v15.5.0, v14.17.0	Le support `AbortSignal` a été ajouté.
v13.2.0, v12.16.0	L'option `serialization` est maintenant supportée.
v8.8.0	L'option `windowsHide` est maintenant supportée.
v6.4.0	L'option `argv0` est maintenant supportée.
v5.7.0	L'option `shell` est maintenant supportée.
v0.1.90	Ajouté dans : v0.1.90

command <string> La commande à exécuter.
args <string[]> Liste des arguments de type chaîne de caractères.
options <Object>
- cwd <string> | <URL> Répertoire de travail courant du processus enfant.
- env <Object> Paires clé-valeur de l'environnement. Par défaut : process.env.
- argv0 <string> Définit explicitement la valeur de argv[0] envoyée au processus enfant. Ceci sera défini sur command s'il n'est pas spécifié.
- stdio <Array> | <string> Configuration du stdio de l'enfant (voir options.stdio).
- detached <boolean> Prépare le processus enfant à s'exécuter indépendamment de son processus parent. Le comportement spécifique dépend de la plateforme, voir options.detached).
- uid <number> Définit l'identité utilisateur du processus (voir setuid(2)).
- gid <number> Définit l'identité de groupe du processus (voir setgid(2)).
- serialization <string> Spécifie le type de sérialisation utilisé pour l'envoi de messages entre les processus. Les valeurs possibles sont 'json' et 'advanced'. Voir Sérialisation avancée pour plus de détails. Par défaut : 'json'.
- shell <boolean> | <string> Si true, exécute command à l'intérieur d'un shell. Utilise '/bin/sh' sous Unix, et process.env.ComSpec sous Windows. Un shell différent peut être spécifié sous forme de chaîne de caractères. Voir Conditions requises pour le shell et Shell Windows par défaut. Par défaut : false (pas de shell).
- windowsVerbatimArguments <boolean> Aucune citation ou échappement des arguments n'est effectué sous Windows. Ignoré sous Unix. Ceci est automatiquement défini sur true lorsque shell est spécifié et qu'il s'agit de CMD. Par défaut : false.
- windowsHide <boolean> Masque la fenêtre de console du sous-processus qui serait normalement créée sur les systèmes Windows. Par défaut : false.
- signal <AbortSignal> permet d'avorter le processus enfant à l'aide d'un AbortSignal.
- timeout <number> En millisecondes, durée maximale d'exécution autorisée du processus. Par défaut : undefined.
- killSignal <string> | <integer> La valeur du signal à utiliser lorsque le processus généré sera tué par expiration du délai ou signal d'annulation. Par défaut : 'SIGTERM'.
Retourne : <ChildProcess>

La méthode child_process.spawn() génère un nouveau processus en utilisant la command donnée, avec les arguments de ligne de commande dans args. Si omis, args a par défaut un tableau vide.

Si l'option shell est activée, ne pas passer d'entrée utilisateur non désinfectée à cette fonction. Toute entrée contenant des métacaractères shell peut être utilisée pour déclencher une exécution de commande arbitraire.

Un troisième argument peut être utilisé pour spécifier des options supplémentaires, avec ces valeurs par défaut :

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

Utiliser cwd pour spécifier le répertoire de travail à partir duquel le processus est généré. S'il n'est pas donné, la valeur par défaut est d'hériter du répertoire de travail courant. S'il est donné, mais que le chemin n'existe pas, le processus enfant émet une erreur ENOENT et se termine immédiatement. ENOENT est également émis lorsque la commande n'existe pas.

Utiliser env pour spécifier les variables d'environnement qui seront visibles par le nouveau processus, la valeur par défaut est process.env.

Les valeurs undefined dans env seront ignorées.

Exemple d'exécution de ls -lh /usr, capture de stdout, stderr, et du code de sortie :

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

Exemple : Une manière très élaborée d'exécuter 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}`)
  }
})

Exemple de vérification d'échec de 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.')
})

Certaines plateformes (macOS, Linux) utiliseront la valeur de argv[0] pour le titre du processus tandis que d'autres (Windows, SunOS) utiliseront command.

Node.js écrase argv[0] avec process.execPath au démarrage, donc process.argv[0] dans un processus enfant Node.js ne correspondra pas au paramètre argv0 passé à spawn par le parent. Récupérez-le avec la propriété process.argv0 à la place.

CJSESM

const { spawn } = require('node:child_process')
const controller = new AbortController()
const { signal } = controller
const grep = spawn('grep', ['ssh'], { signal })
grep.on('error', err => {
  // Ceci sera appelé avec err étant une AbortError si le contrôleur avorte
})
controller.abort() // Arrête le processus enfant

import { spawn } from 'node:child_process'
const controller = new AbortController()
const { signal } = controller
const grep = spawn('grep', ['ssh'], { signal })
grep.on('error', err => {
  // Ceci sera appelé avec err étant une AbortError si le contrôleur avorte
})
controller.abort() // Arrête le processus enfant

`options.detached`

Ajouté dans : v0.7.10

Sous Windows, la configuration de options.detached sur true permet au processus enfant de continuer à s’exécuter après la fermeture du processus parent. Le processus enfant aura sa propre fenêtre de console. Une fois activé pour un processus enfant, il ne peut plus être désactivé.

Sur les plates-formes autres que Windows, si options.detached est défini sur true, le processus enfant devient le leader d’un nouveau groupe de processus et d’une nouvelle session. Les processus enfants peuvent continuer à s’exécuter après la fermeture du processus parent, qu’ils soient détachés ou non. Consultez setsid(2) pour plus d’informations.

Par défaut, le processus parent attendra la fin du processus enfant détaché. Pour empêcher le processus parent d’attendre la fin d’un subprocess donné, utilisez la méthode subprocess.unref(). Cela entraînera l’exclusion du processus enfant du nombre de références de la boucle d’événements du processus parent, permettant au processus parent de se terminer indépendamment du processus enfant, sauf s’il existe un canal IPC établi entre les processus enfant et parent.

Lorsque vous utilisez l’option detached pour démarrer un processus long, celui-ci ne restera pas en cours d’exécution en arrière-plan après la fermeture du processus parent, sauf s’il est fourni avec une configuration stdio qui n’est pas connectée au processus parent. Si le stdio du processus parent est hérité, le processus enfant restera attaché au terminal de contrôle.

Exemple de processus long, en le détachant et en ignorant également les descripteurs de fichiers stdio de son parent, afin d’ignorer la terminaison du parent :

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

Vous pouvez également rediriger la sortie du processus enfant vers des fichiers :

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`

[Historique]

Version	Modifications
v15.6.0, v14.18.0	Ajout de l'indicateur stdio `overlapped`.
v3.3.1	La valeur `0` est maintenant acceptée comme descripteur de fichier.
v0.7.10	Ajouté dans : v0.7.10

L'option options.stdio est utilisée pour configurer les pipes établies entre le processus parent et le processus enfant. Par défaut, les entrées standard (stdin), sorties standard (stdout) et sorties d'erreur standard (stderr) de l'enfant sont redirigées vers les flux subprocess.stdin, subprocess.stdout et subprocess.stderr correspondants sur l'objet ChildProcess. Ceci équivaut à définir options.stdio à ['pipe', 'pipe', 'pipe'].

Pour plus de commodité, options.stdio peut être l'une des chaînes de caractères suivantes :

'pipe' : équivalent à ['pipe', 'pipe', 'pipe'] (la valeur par défaut)
'overlapped' : équivalent à ['overlapped', 'overlapped', 'overlapped']
'ignore' : équivalent à ['ignore', 'ignore', 'ignore']
'inherit' : équivalent à ['inherit', 'inherit', 'inherit'] ou [0, 1, 2]

Sinon, la valeur de options.stdio est un tableau où chaque index correspond à un descripteur de fichier (fd) dans l'enfant. Les descripteurs de fichiers 0, 1 et 2 correspondent respectivement à stdin, stdout et stderr. Des descripteurs de fichiers supplémentaires peuvent être spécifiés pour créer des pipes supplémentaires entre le parent et l'enfant. La valeur est l'une des suivantes :

CJSESM

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

// L'enfant utilisera les stdios du parent.
spawn('prg', [], { stdio: 'inherit' })

// Lancer l'enfant en partageant uniquement stderr.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] })

// Ouvrir un fd=4 supplémentaire, pour interagir avec les programmes présentant une
// interface de type startd.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] })

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

// L'enfant utilisera les stdios du parent.
spawn('prg', [], { stdio: 'inherit' })

// Lancer l'enfant en partageant uniquement stderr.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] })

// Ouvrir un fd=4 supplémentaire, pour interagir avec les programmes présentant une
// interface de type startd.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] })

Il est à noter que lorsqu'un canal IPC est établi entre les processus parent et enfant, et que le processus enfant est une instance Node.js, le processus enfant est lancé avec le canal IPC non référencé (en utilisant unref()) jusqu'à ce que le processus enfant enregistre un gestionnaire d'événements pour l'événement 'disconnect' ou l'événement 'message'. Cela permet au processus enfant de se terminer normalement sans que le processus ne soit maintenu ouvert par le canal IPC ouvert. Voir aussi : child_process.exec() et child_process.fork().

Création de processus synchrone

Les méthodes child_process.spawnSync(), child_process.execSync(), et child_process.execFileSync() sont synchrones et bloqueront la boucle d'événements Node.js, suspendant l'exécution de tout code supplémentaire jusqu'à ce que le processus enfant se termine.

Les appels bloquants comme ceux-ci sont principalement utiles pour simplifier les tâches de script à usage général et pour simplifier le chargement/traitement de la configuration de l'application au démarrage.

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

[Historique]

Version	Modifications
v16.4.0, v14.18.0	L'option `cwd` peut être un objet `URL` WHATWG utilisant le protocole `file:`
v10.10.0	L'option `input` peut maintenant être n'importe quel `TypedArray` ou un `DataView`.
v8.8.0	L'option `windowsHide` est maintenant prise en charge.
v8.0.0	L'option `input` peut maintenant être un `Uint8Array`.
v6.2.1, v4.5.0	L'option `encoding` peut maintenant être explicitement définie sur `buffer`.
v0.11.12	Ajouté dans : v0.11.12

file <string> Le nom ou le chemin du fichier exécutable à exécuter.
args <string[]> Liste des arguments de type chaîne de caractères.
options <Object>
- cwd <string> | <URL> Répertoire de travail courant du processus enfant.
- input <string> | <Buffer> | <TypedArray> | <DataView> La valeur qui sera passée en entrée standard au processus enfant. Si stdio[0] est défini sur 'pipe', la fourniture de cette valeur remplacera stdio[0].
- stdio <string> | <Array> Configuration du stdio de l'enfant. Voir child_process.spawn() et son paramètre stdio. Par défaut, stderr sera envoyé vers le stderr du processus parent, sauf si stdio est spécifié. Valeur par défaut : 'pipe'.
- env <Object> Paires clé-valeur de l'environnement. Valeur par défaut : process.env.
- uid <number> Définit l'identité utilisateur du processus (voir setuid(2)).
- gid <number> Définit l'identité de groupe du processus (voir setgid(2)).
- timeout <number> En millisecondes, durée maximale autorisée pour l'exécution du processus. Valeur par défaut : undefined.
- killSignal <string> | <integer> La valeur du signal à utiliser lorsque le processus enfant sera tué. Valeur par défaut : 'SIGTERM'.
- maxBuffer <number> Quantité maximale de données en octets autorisée sur stdout ou stderr. Si cette limite est dépassée, le processus enfant est terminé. Voir la mise en garde à maxBuffer et Unicode. Valeur par défaut : 1024 * 1024.
- encoding <string> L'encodage utilisé pour toutes les entrées et sorties stdio. Valeur par défaut : 'buffer'.
- windowsHide <boolean> Masquer la fenêtre de console du sous-processus qui serait normalement créée sur les systèmes Windows. Valeur par défaut : false.
- shell <boolean> | <string> Si true, exécute command à l'intérieur d'un shell. Utilise '/bin/sh' sous Unix et process.env.ComSpec sous Windows. Un shell différent peut être spécifié sous forme de chaîne de caractères. Voir Exigences du shell et Shell Windows par défaut. Valeur par défaut : false (pas de shell).
Retourne : <Buffer> | <string> Le stdout de la commande.

La méthode child_process.execFileSync() est généralement identique à child_process.execFile(), à l'exception que la méthode ne retournera pas avant que le processus enfant ne soit complètement fermé. Lorsqu'un délai d'attente est rencontré et que killSignal est envoyé, la méthode ne retournera pas avant que le processus ne soit complètement terminé.

Si le processus enfant intercepte et gère le signal SIGTERM et ne se termine pas, le processus parent attendra toujours que le processus enfant se termine.

Si le processus dépasse le délai imparti ou a un code de retour différent de zéro, cette méthode lèvera une erreur Error qui inclura le résultat complet du child_process.spawnSync() sous-jacent.

CJSESM

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

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // Capture stdout and stderr du processus enfant. Remplace le
    // comportement par défaut qui consiste à diffuser le stderr de l'enfant vers le stderr du parent
    stdio: 'pipe',

    // Utiliser l'encodage utf8 pour les pipes stdio
    encoding: 'utf8',
  })

  console.log(stdout)
} catch (err) {
  if (err.code) {
    // Échec du lancement du processus enfant
    console.error(err.code)
  } else {
    // L'enfant a été lancé mais s'est terminé avec un code de retour différent de zéro
    // L'erreur contient tout stdout et stderr de l'enfant
    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 du processus enfant. Remplace le
    // comportement par défaut qui consiste à diffuser le stderr de l'enfant vers le stderr du parent
    stdio: 'pipe',

    // Utiliser l'encodage utf8 pour les pipes stdio
    encoding: 'utf8',
  })

  console.log(stdout)
} catch (err) {
  if (err.code) {
    // Échec du lancement du processus enfant
    console.error(err.code)
  } else {
    // L'enfant a été lancé mais s'est terminé avec un code de retour différent de zéro
    // L'erreur contient tout stdout et stderr de l'enfant
    const { stdout, stderr } = err

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

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

[Historique]

Version	Modifications
v16.4.0, v14.18.0	L'option `cwd` peut être un objet `URL` WHATWG utilisant le protocole `file:`
v10.10.0	L'option `input` peut maintenant être n'importe quel `TypedArray` ou un `DataView`.
v8.8.0	L'option `windowsHide` est maintenant prise en charge.
v8.0.0	L'option `input` peut maintenant être un `Uint8Array`.
v0.11.12	Ajouté dans : v0.11.12

command <string> La commande à exécuter.
options <Object>
- cwd <string> | <URL> Répertoire de travail courant du processus enfant.
- input <string> | <Buffer> | <TypedArray> | <DataView> La valeur qui sera passée en stdin au processus engendré. Si stdio[0] est défini sur 'pipe', fournir cette valeur remplacera stdio[0].
- stdio <string> | <Array> Configuration stdio de l'enfant. Voir child_process.spawn() et son paramètre stdio. Par défaut, stderr sera envoyé sur le stderr du processus parent, sauf si stdio est spécifié. Défaut : 'pipe'.
- env <Object> Paires clé-valeur de l'environnement. Défaut : process.env.
- shell <string> Interpréteur de commandes pour exécuter la commande. Voir Conditions requises pour l'interpréteur de commandes et Interpréteur de commandes Windows par défaut. Défaut : '/bin/sh' sous Unix, process.env.ComSpec sous Windows.
- uid <number> Définit l'identité utilisateur du processus. (Voir setuid(2)).
- gid <number> Définit l'identité de groupe du processus. (Voir setgid(2)).
- timeout <number> En millisecondes, durée maximale d'exécution autorisée du processus. Défaut : undefined.
- killSignal <string> | <integer> Valeur du signal à utiliser lorsque le processus engendré sera tué. Défaut : 'SIGTERM'.
- maxBuffer <number> Quantité maximale de données en octets autorisée sur stdout ou stderr. Si cette limite est dépassée, le processus enfant est terminé et toute sortie est tronquée. Voir la mise en garde concernant maxBuffer et Unicode. Défaut : 1024 * 1024.
- encoding <string> Encodage utilisé pour toutes les entrées et sorties stdio. Défaut : 'buffer'.
- windowsHide <boolean> Masquer la fenêtre de console du sous-processus qui serait normalement créée sur les systèmes Windows. Défaut : false.
Retourne : <Buffer> | <string> Le stdout de la commande.

La méthode child_process.execSync() est généralement identique à child_process.exec(), à l'exception que la méthode ne retourne pas avant que le processus enfant ne soit complètement fermé. Lorsqu'un délai d'expiration est rencontré et que killSignal est envoyé, la méthode ne retourne pas avant que le processus ne soit complètement terminé. Si le processus enfant intercepte et gère le signal SIGTERM et ne se termine pas, le processus parent attendra que le processus enfant se termine.

Si le processus dépasse le délai imparti ou a un code de retour différent de zéro, cette méthode lève une exception. L'objet Error contiendra le résultat complet de child_process.spawnSync().

Ne jamais passer d'entrée utilisateur non assainie à cette fonction. Toute entrée contenant des métacaractères shell peut être utilisée pour déclencher une exécution de commande arbitraire.

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

[Historique]

Version	Modifications
v16.4.0, v14.18.0	L'option `cwd` peut être un objet `URL` WHATWG utilisant le protocole `file:`
v10.10.0	L'option `input` peut maintenant être n'importe quel `TypedArray` ou un `DataView`.
v8.8.0	L'option `windowsHide` est maintenant prise en charge.
v8.0.0	L'option `input` peut maintenant être un `Uint8Array`.
v5.7.0	L'option `shell` est maintenant prise en charge.
v6.2.1, v4.5.0	L'option `encoding` peut maintenant être explicitement définie sur `buffer`.
v0.11.12	Ajouté dans : v0.11.12

command <string> La commande à exécuter.
args <string[]> Liste des arguments de type chaîne de caractères.
options <Object>
- cwd <string> | <URL> Répertoire de travail courant du processus enfant.
- input <string> | <Buffer> | <TypedArray> | <DataView> La valeur qui sera passée en entrée standard au processus enfant. Si stdio[0] est défini sur 'pipe', la fourniture de cette valeur remplacera stdio[0].
- argv0 <string> Définit explicitement la valeur de argv[0] envoyée au processus enfant. Cette valeur sera définie sur command si elle n'est pas spécifiée.
- stdio <string> | <Array> Configuration d'E/S standard de l'enfant. Voir la configuration stdio de child_process.spawn(). Valeur par défaut : 'pipe'.
- env <Object> Paires clé-valeur de l'environnement. Valeur par défaut : process.env.
- uid <number> Définit l'identité utilisateur du processus (voir setuid(2)).
- gid <number> Définit l'identité de groupe du processus (voir setgid(2)).
- timeout <number> En millisecondes, durée maximale d'exécution autorisée du processus. Valeur par défaut : undefined.
- killSignal <string> | <integer> La valeur du signal à utiliser lorsque le processus enfant sera tué. Valeur par défaut : 'SIGTERM'.
- maxBuffer <number> Quantité maximale de données en octets autorisée sur stdout ou stderr. Si cette limite est dépassée, le processus enfant est terminé et toute sortie est tronquée. Voir la mise en garde à maxBuffer et Unicode. Valeur par défaut : 1024 * 1024.
- encoding <string> L'encodage utilisé pour toutes les entrées et sorties stdio. Valeur par défaut : 'buffer'.
- shell <boolean> | <string> Si true, exécute command à l'intérieur d'un interpréteur de commandes. Utilise '/bin/sh' sous Unix et process.env.ComSpec sous Windows. Un interpréteur de commandes différent peut être spécifié sous forme de chaîne de caractères. Voir Conditions requises pour l'interpréteur de commandes et Interpréteur de commandes Windows par défaut. Valeur par défaut : false (pas d'interpréteur de commandes).
- windowsVerbatimArguments <boolean> Aucune citation ou échappement des arguments n'est effectué sous Windows. Ignoré sous Unix. Cette option est définie sur true automatiquement lorsque shell est spécifié et qu'il s'agit de CMD. Valeur par défaut : false.
- windowsHide <boolean> Masque la fenêtre de console de sous-processus qui serait normalement créée sur les systèmes Windows. Valeur par défaut : false.
Retourne : <Object>
- pid <number> PID du processus enfant.
- output <Array> Tableau des résultats de la sortie stdio.
- stdout <Buffer> | <string> Le contenu de output[1].
- stderr <Buffer> | <string> Le contenu de output[2].
- status <number> | <null> Le code de sortie du sous-processus, ou null si le sous-processus a été terminé en raison d'un signal.
- signal <string> | <null> Le signal utilisé pour tuer le sous-processus, ou null si le sous-processus n'a pas été terminé en raison d'un signal.
- error <Error> L'objet d'erreur si le processus enfant a échoué ou a dépassé le délai imparti.

La méthode child_process.spawnSync() est généralement identique à child_process.spawn(), à l'exception du fait que la fonction ne retourne pas avant que le processus enfant ne soit complètement fermé. Lorsqu'un délai d'attente a été rencontré et que killSignal est envoyé, la méthode ne retourne pas avant que le processus ne soit complètement terminé. Si le processus intercepte et gère le signal SIGTERM et ne se termine pas, le processus parent attendra que le processus enfant se termine.

Si l'option shell est activée, ne pas transmettre d'entrée utilisateur non nettoyée à cette fonction. Toute entrée contenant des métacaractères shell peut être utilisée pour déclencher l'exécution de commandes arbitraires.

Classe : `ChildProcess`

Ajouté dans : v2.2.0

Étend : <EventEmitter>

Les instances de ChildProcess représentent les processus enfants générés.

Les instances de ChildProcess ne sont pas destinées à être créées directement. Utilisez plutôt les méthodes child_process.spawn(), child_process.exec(), child_process.execFile() ou child_process.fork() pour créer des instances de ChildProcess.

Événement : `'close'`

Ajouté dans : v0.7.7

code <number> Le code de sortie si le processus enfant s'est terminé de lui-même.
signal <string> Le signal par lequel le processus enfant a été terminé.

L'événement 'close' est émis après la fin d'un processus et la fermeture des flux stdio d'un processus enfant. Ceci est distinct de l'événement 'exit', car plusieurs processus peuvent partager les mêmes flux stdio. L'événement 'close' sera toujours émis après que 'exit' a déjà été émis, ou 'error' si le processus enfant n'a pas réussi à se générer.

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

Événement : `'disconnect'`

Ajouté dans : v0.7.2

L'événement 'disconnect' est émis après l'appel de la méthode subprocess.disconnect() dans le processus parent ou process.disconnect() dans le processus enfant. Après la déconnexion, il n'est plus possible d'envoyer ou de recevoir des messages, et la propriété subprocess.connected est false.

Événement : `'error'`

err <Error> L'erreur.

L'événement 'error' est émis chaque fois que :

Le processus n'a pas pu être généré.
Le processus n'a pas pu être tué.
L'envoi d'un message au processus enfant a échoué.
Le processus enfant a été interrompu via l'option signal.

L'événement 'exit' peut ou non se déclencher après une erreur. Lorsque vous écoutez à la fois les événements 'exit' et 'error', évitez d'appeler accidentellement les fonctions de gestionnaire plusieurs fois.

Voir aussi subprocess.kill() et subprocess.send().

Événement : `'exit'`

Ajouté dans : v0.1.90

code <number> Le code de sortie si le processus enfant s'est terminé de lui-même.
signal <string> Le signal par lequel le processus enfant a été terminé.

L'événement 'exit' est émis après la fin du processus enfant. Si le processus s'est terminé, code est le code de sortie final du processus, sinon null. Si le processus a été terminé suite à la réception d'un signal, signal est le nom de chaîne du signal, sinon null. L'un des deux sera toujours différent de null.

Lorsque l'événement 'exit' est déclenché, les flux stdio du processus enfant peuvent toujours être ouverts.

Node.js établit des gestionnaires de signaux pour SIGINT et SIGTERM, et les processus Node.js ne se termineront pas immédiatement suite à la réception de ces signaux. Au lieu de cela, Node.js effectuera une séquence d'actions de nettoyage, puis relèvera le signal géré.

Voir waitpid(2).

Événement : `'message'`

Ajouté dans : v0.5.9

message <Objet> Un objet JSON analysé ou une valeur primitive.
sendHandle <Handle> | <indéfini> undefined ou un objet net.Socket, net.Server, ou dgram.Socket.

L'événement 'message' est déclenché lorsqu'un processus enfant utilise process.send() pour envoyer des messages.

Le message passe par une sérialisation et une analyse. Le message résultant peut ne pas être le même que celui envoyé à l'origine.

Si l'option serialization était définie sur 'advanced' lors du lancement du processus enfant, l'argument message peut contenir des données que JSON ne peut pas représenter. Voir Sérialisation avancée pour plus de détails.

Événement : `'spawn'`

Ajouté dans : v15.1.0, v14.17.0

L'événement 'spawn' est émis une fois que le processus enfant a été correctement lancé. Si le processus enfant n'est pas lancé avec succès, l'événement 'spawn' n'est pas émis et l'événement 'error' est émis à la place.

S'il est émis, l'événement 'spawn' intervient avant tous les autres événements et avant toute réception de données via stdout ou stderr.

L'événement 'spawn' se déclenchera indépendamment du fait qu'une erreur se produise à l'intérieur du processus lancé. Par exemple, si bash some-command est lancé avec succès, l'événement 'spawn' se déclenchera, même si bash peut échouer à lancer some-command. Cette mise en garde s'applique également lors de l'utilisation de { shell: true }.

`subprocess.channel`

[Historique]

Version	Modifications
v14.0.0	L'objet n'expose plus accidentellement les liaisons natives C++.
v7.1.0	Ajouté dans : v7.1.0

<Objet> Un tube représentant le canal IPC vers le processus enfant.

La propriété subprocess.channel est une référence au canal IPC de l'enfant. Si aucun canal IPC n'existe, cette propriété est undefined.

`subprocess.channel.ref()`

Ajouté dans : v7.1.0

Cette méthode permet au canal IPC de maintenir la boucle d'événements du processus parent en cours d'exécution si .unref() a été appelé auparavant.

`subprocess.channel.unref()`

Ajouté dans : v7.1.0

Cette méthode permet au canal IPC de ne pas maintenir la boucle d'événements du processus parent en cours d'exécution, et le laisse se terminer même lorsque le canal est ouvert.

`subprocess.connected`

Ajouté dans : v0.7.2

<booléen> Fixé à false après l'appel de subprocess.disconnect().

La propriété subprocess.connected indique s'il est encore possible d'envoyer et de recevoir des messages d'un processus enfant. Lorsque subprocess.connected est false, il n'est plus possible d'envoyer ou de recevoir des messages.

`subprocess.disconnect()`

Ajouté dans : v0.7.2

Ferme le canal IPC entre les processus parent et enfant, permettant au processus enfant de se terminer correctement une fois qu'il n'y a plus d'autres connexions le maintenant en vie. Après avoir appelé cette méthode, les propriétés subprocess.connected et process.connected dans les processus parent et enfant (respectivement) seront définies sur false, et il ne sera plus possible de transmettre des messages entre les processus.

L'événement 'disconnect' sera émis lorsqu'il n'y a pas de messages en cours de réception. Cela sera le plus souvent déclenché immédiatement après l'appel de subprocess.disconnect().

Lorsque le processus enfant est une instance Node.js (par exemple, générée à l'aide de child_process.fork()), la méthode process.disconnect() peut être invoquée dans le processus enfant pour fermer également le canal IPC.

`subprocess.exitCode`

<entier>

La propriété subprocess.exitCode indique le code de sortie du processus enfant. Si le processus enfant est toujours en cours d'exécution, le champ sera null.

`subprocess.kill([signal])`

Ajouté dans : v0.1.90

signal <nombre> | <chaîne de caractères>
Retourne : <booléen>

La méthode subprocess.kill() envoie un signal au processus enfant. Si aucun argument n'est donné, le processus recevra le signal 'SIGTERM'. Voir signal(7) pour une liste des signaux disponibles. Cette fonction retourne true si kill(2) réussit, et false sinon.

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

// Envoyer SIGHUP au processus.
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}`)
})

// Envoyer SIGHUP au processus.
grep.kill('SIGHUP')

L'objet ChildProcess peut émettre un événement 'error' si le signal ne peut pas être envoyé. L'envoi d'un signal à un processus enfant qui a déjà quitté n'est pas une erreur, mais peut avoir des conséquences imprévues. Plus précisément, si l'identifiant de processus (PID) a été réaffecté à un autre processus, le signal sera envoyé à ce processus à la place, ce qui peut avoir des résultats inattendus.

Bien que la fonction s'appelle kill, le signal envoyé au processus enfant peut ne pas réellement terminer le processus.

Voir kill(2) pour référence.

Sous Windows, où les signaux POSIX n'existent pas, l'argument signal sera ignoré sauf pour 'SIGKILL', 'SIGTERM', 'SIGINT' et 'SIGQUIT', et le processus sera toujours tué de force et brutalement (similaire à 'SIGKILL'). Voir Événements de signal pour plus de détails.

Sous Linux, les processus enfants des processus enfants ne seront pas terminés lorsqu'on tente de tuer leur parent. Cela est susceptible de se produire lors de l'exécution d'un nouveau processus dans un shell ou avec l'option shell de ChildProcess :

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() // Ne termine pas le processus Node.js dans le 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() // Ne termine pas le processus Node.js dans le shell.
}, 2000)

`subprocess[Symbol.dispose]()`

Ajouté dans : v20.5.0, v18.18.0

[Stable : 1 - Expérimental]

Stable : 1 Stabilité : 1 - Expérimental

Appelle subprocess.kill() avec 'SIGTERM'.

`subprocess.killed`

Ajouté dans : v0.5.10

<booléen> Défini sur true après que subprocess.kill() a été utilisé pour envoyer avec succès un signal au processus enfant.

La propriété subprocess.killed indique si le processus enfant a bien reçu un signal de subprocess.kill(). La propriété killed n'indique pas que le processus enfant a été terminé.

`subprocess.pid`

Ajouté dans : v0.1.90

<entier> | <indéfini>

Retourne l'identifiant de processus (PID) du processus enfant. Si le processus enfant ne parvient pas à se lancer en raison d'erreurs, la valeur est alors undefined et error est émis.

CJSESM

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

console.log(`PID du processus enfant lancé : ${grep.pid}`)
grep.stdin.end()

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

console.log(`PID du processus enfant lancé : ${grep.pid}`)
grep.stdin.end()

`subprocess.ref()`

Ajouté dans : v0.7.10

Appeler subprocess.ref() après avoir appelé subprocess.unref() restaurera le nombre de références supprimé pour le processus enfant, forçant le processus parent à attendre la fin du processus enfant avant de se terminer lui-même.

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

[Historique]

Version	Modifications
v5.8.0	Le paramètre `options`, et l'option `keepOpen` en particulier, sont désormais pris en charge.
v5.0.0	Cette méthode renvoie désormais un booléen pour le contrôle de flux.
v4.0.0	Le paramètre `callback` est désormais pris en charge.
v0.5.9	Ajouté dans : v0.5.9

message <Objet>
sendHandle <Handle> | <indéfini> indéfini, ou un objet net.Socket, net.Server, ou dgram.Socket.
options <Objet> L'argument options, s'il est présent, est un objet utilisé pour paramétrer l'envoi de certains types de handles. options prend en charge les propriétés suivantes :
- keepOpen <booléen> Une valeur pouvant être utilisée lors du passage d'instances de net.Socket. Lorsqu'il est défini sur true, le socket reste ouvert dans le processus d'envoi. Défaut : false.
callback <Fonction>
Retourne : <booléen>

Lorsqu'un canal IPC a été établi entre les processus parent et enfant (c'est-à-dire lors de l'utilisation de child_process.fork()), la méthode subprocess.send() peut être utilisée pour envoyer des messages au processus enfant. Lorsque le processus enfant est une instance Node.js, ces messages peuvent être reçus via l'événement 'message'.

Le message passe par une sérialisation et une analyse. Le message résultant peut ne pas être le même que celui envoyé à l'origine.

Par exemple, dans le script parent :

CJSESM

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

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

// Provoque l'impression suivante dans l'enfant : 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)
})

// Provoque l'impression suivante dans l'enfant : CHILD got message: { hello: 'world' }
forkedProcess.send({ hello: 'world' })

Et le script enfant, 'sub.js', pourrait ressembler à ceci :

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

// Provoque l'impression suivante dans le parent : PARENT got message: { foo: 'bar', baz: null }
process.send({ foo: 'bar', baz: NaN })

Les processus enfants Node.js auront une méthode process.send() qui permet au processus enfant d'envoyer des messages au processus parent.

Il existe un cas particulier lors de l'envoi d'un message {cmd: 'NODE_foo'}. Les messages contenant un préfixe NODE_ dans la propriété cmd sont réservés à une utilisation au sein du cœur de Node.js et ne seront pas émis dans l'événement 'message' de l'enfant. Au lieu de cela, ces messages sont émis à l'aide de l'événement 'internalMessage' et sont consommés en interne par Node.js. Les applications doivent éviter d'utiliser de tels messages ou d'écouter les événements 'internalMessage' car ils sont sujets à modification sans préavis.

L'argument facultatif sendHandle qui peut être passé à subprocess.send() permet de transmettre un serveur TCP ou un objet socket au processus enfant. Le processus enfant recevra l'objet comme deuxième argument passé à la fonction de rappel enregistrée sur l'événement 'message'. Les données reçues et mises en mémoire tampon dans le socket ne seront pas envoyées à l'enfant. L'envoi de sockets IPC n'est pas pris en charge sous Windows.

Le paramètre callback facultatif est une fonction qui est appelée après l'envoi du message mais avant que le processus enfant ne l'ait peut-être reçu. La fonction est appelée avec un seul argument : null en cas de succès, ou un objet Error en cas d'échec.

Si aucune fonction callback n'est fournie et que le message ne peut pas être envoyé, un événement 'error' sera émis par l'objet ChildProcess. Cela peut se produire, par exemple, lorsque le processus enfant a déjà quitté.

subprocess.send() renverra false si le canal est fermé ou lorsque le retard des messages non envoyés dépasse un seuil qui rend imprudent d'en envoyer d'autres. Sinon, la méthode renvoie true. La fonction callback peut être utilisée pour implémenter le contrôle de flux.

Exemple : envoi d’un objet serveur

L’argument sendHandle peut être utilisé, par exemple, pour passer le handle d’un objet serveur TCP au processus enfant, comme illustré dans l’exemple ci-dessous :

CJSESM

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

const subprocess = fork('subprocess.js')

// Ouvrir l’objet serveur et envoyer le 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')

// Ouvrir l’objet serveur et envoyer le handle.
const server = createServer()
server.on('connection', socket => {
  socket.end('handled by parent')
})
server.listen(1337, () => {
  subprocess.send('server', server)
})

Le processus enfant recevrait alors l’objet serveur comme suit :

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

Une fois que le serveur est partagé entre le parent et l’enfant, certaines connexions peuvent être traitées par le parent et d’autres par l’enfant.

Bien que l’exemple ci-dessus utilise un serveur créé à l’aide du module node:net, les serveurs du module node:dgram utilisent exactement le même flux de travail, à l’exception de l’écoute sur un événement 'message' au lieu de 'connection' et de l’utilisation de server.bind() au lieu de server.listen(). Ceci n’est cependant pris en charge que sur les plates-formes Unix.

Exemple : envoi d’un objet socket

De même, l’argument sendHandler peut être utilisé pour passer le handle d’une socket au processus enfant. L’exemple ci-dessous génère deux enfants qui gèrent chacun les connexions avec une priorité « normale » ou « spéciale » :

CJSESM

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

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

// Ouvrir le serveur et envoyer les sockets à l’enfant. Utiliser pauseOnConnect pour empêcher
// la lecture des sockets avant qu’elles ne soient envoyées au processus enfant.
const server = createServer({ pauseOnConnect: true })
server.on('connection', socket => {
  // S’il s’agit d’une priorité spéciale…
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket)
    return
  }
  // Ceci est une priorité normale.
  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'])

// Ouvrir le serveur et envoyer les sockets à l’enfant. Utiliser pauseOnConnect pour empêcher
// la lecture des sockets avant qu’elles ne soient envoyées au processus enfant.
const server = createServer({ pauseOnConnect: true })
server.on('connection', socket => {
  // S’il s’agit d’une priorité spéciale…
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket)
    return
  }
  // Ceci est une priorité normale.
  normal.send('socket', socket)
})
server.listen(1337)

Le fichier subprocess.js recevrait le handle de la socket comme deuxième argument passé à la fonction de rappel d’événement :

process.on('message', (m, socket) => {
  if (m === 'socket') {
    if (socket) {
      // Vérifier que la socket client existe.
      // Il est possible que la socket soit fermée entre le moment où elle est envoyée et le moment où elle est reçue dans le processus enfant.
      socket.end(`Request handled with ${process.argv[2]} priority`)
    }
  }
})

N’utilisez pas .maxConnections sur une socket qui a été passée à un sous-processus. Le parent ne peut pas suivre quand la socket est détruite.

Tout gestionnaire 'message' dans le sous-processus doit vérifier que socket existe, car la connexion peut avoir été fermée pendant le temps nécessaire pour envoyer la connexion à l’enfant.

`subprocess.signalCode`

<string> | <null>

La propriété subprocess.signalCode indique le signal reçu par le processus enfant, le cas échéant, sinon null.

`subprocess.spawnargs`

<Array>

La propriété subprocess.spawnargs représente la liste complète des arguments de ligne de commande avec lesquels le processus enfant a été lancé.

`subprocess.spawnfile`

<string>

La propriété subprocess.spawnfile indique le nom du fichier exécutable du processus enfant lancé.

Pour child_process.fork(), sa valeur sera égale à process.execPath. Pour child_process.spawn(), sa valeur sera le nom du fichier exécutable. Pour child_process.exec(), sa valeur sera le nom de l'interpréteur de commandes dans lequel le processus enfant est lancé.

`subprocess.stderr`

Ajouté dans : v0.1.90

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

Un flux Readable qui représente le stderr du processus enfant.

Si le processus enfant a été généré avec stdio[2] défini sur une valeur autre que 'pipe', alors cela sera null.

subprocess.stderr est un alias pour subprocess.stdio[2]. Les deux propriétés feront référence à la même valeur.

La propriété subprocess.stderr peut être null ou undefined si le processus enfant n'a pas pu être généré avec succès.

`subprocess.stdin`

Ajouté dans : v0.1.90

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

Un Writable Stream qui représente le stdin du processus enfant.

Si un processus enfant attend de lire toute son entrée, le processus enfant ne continuera pas tant que ce flux n'aura pas été fermé via end().

Si le processus enfant a été généré avec stdio[0] défini sur une valeur autre que 'pipe', alors cela sera null.

subprocess.stdin est un alias pour subprocess.stdio[0]. Les deux propriétés référenceront la même valeur.

La propriété subprocess.stdin peut être null ou undefined si le processus enfant n'a pas pu être généré avec succès.

`subprocess.stdio`

Ajouté dans : v0.7.10

<Array>

Un tableau creux de pipes vers le processus enfant, correspondant aux positions dans l'option stdio passée à child_process.spawn() qui ont été définies sur la valeur 'pipe'. subprocess.stdio[0], subprocess.stdio[1] et subprocess.stdio[2] sont également disponibles sous forme de subprocess.stdin, subprocess.stdout et subprocess.stderr, respectivement.

Dans l'exemple suivant, seul le descripteur de fichier 1 (stdout) de l'enfant est configuré comme une pipe, donc seul subprocess.stdio[1] du parent est un flux, toutes les autres valeurs du tableau sont 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, // Utilise le stdin du parent pour l'enfant.
    'pipe', // Pipe le stdout de l'enfant vers le parent.
    fs.openSync('err.out', 'w'), // Dirige le stderr de l'enfant vers un fichier.
  ],
})

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, // Utilise le stdin du parent pour l'enfant.
    'pipe', // Pipe le stdout de l'enfant vers le parent.
    fs.openSync('err.out', 'w'), // Dirige le stderr de l'enfant vers un fichier.
  ],
})

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)

La propriété subprocess.stdio peut être undefined si le processus enfant n'a pas pu être généré avec succès.

`subprocess.stdout`

Ajouté dans : v0.1.90

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

Un flux Readable qui représente le stdout du processus enfant.

Si le processus enfant a été généré avec stdio[1] défini sur une valeur autre que 'pipe', alors cela sera null.

subprocess.stdout est un alias pour subprocess.stdio[1]. Les deux propriétés feront référence à la même valeur.

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

La propriété subprocess.stdout peut être null ou undefined si le processus enfant n'a pas pu être généré avec succès.

`subprocess.unref()`

Ajouté dans : v0.7.10

Par défaut, le processus parent attendra la fin du processus enfant détaché. Pour empêcher le processus parent d'attendre la fin d'un subprocess donné, utilisez la méthode subprocess.unref(). Cela aura pour effet d'empêcher la boucle d'événements du parent d'inclure le processus enfant dans son compteur de références, permettant au parent de se terminer indépendamment de l'enfant, sauf s'il existe un canal IPC établi entre les processus enfant et parent.

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` et Unicode

L'option maxBuffer spécifie le nombre maximal d'octets autorisés sur stdout ou stderr. Si cette valeur est dépassée, le processus enfant est terminé. Cela affecte la sortie qui inclut des encodages de caractères multi-octets tels que UTF-8 ou UTF-16. Par exemple, console.log('中文测试') enverra 13 octets codés en UTF-8 à stdout bien qu'il n'y ait que 4 caractères.

Exigences Shell

Le shell doit comprendre l'option -c. Si le shell est 'cmd.exe', il doit comprendre les options /d /s /c et l'analyse de la ligne de commande doit être compatible.

Shell Windows par défaut

Bien que Microsoft spécifie que %COMSPEC% doit contenir le chemin d'accès à 'cmd.exe' dans l'environnement racine, les processus enfants ne sont pas toujours soumis à la même exigence. Ainsi, dans les fonctions child_process où un shell peut être généré, 'cmd.exe' est utilisé comme solution de secours si process.env.ComSpec n'est pas disponible.

Sérialisation avancée

Ajouté dans : v13.2.0, v12.16.0

Les processus enfants prennent en charge un mécanisme de sérialisation pour l'IPC basé sur l' API de sérialisation du module node:v8, basé sur l' algorithme de clonage structuré HTML. Ceci est généralement plus puissant et prend en charge davantage de types d'objets JavaScript intégrés, tels que BigInt, Map et Set, ArrayBuffer et TypedArray, Buffer, Error, RegExp, etc.

Cependant, ce format n'est pas un sur-ensemble complet de JSON, et par exemple, les propriétés définies sur des objets de ces types intégrés ne seront pas transmises via l'étape de sérialisation. De plus, les performances peuvent ne pas être équivalentes à celles de JSON, selon la structure des données transmises. Par conséquent, cette fonctionnalité nécessite une activation explicite en définissant l'option serialization sur 'advanced' lors de l'appel de child_process.spawn() ou de child_process.fork().

Processus enfant ​

Création de processus asynchrones ​

Lancement de fichiers .bat et .cmd sous 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 ​

Création de processus synchrone ​

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

child_process.execSync(command[, options]) ​

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

Classe : ChildProcess ​

Événement : 'close' ​

Événement : 'disconnect' ​

Événement : 'error' ​

Événement : 'exit' ​

Événement : 'message' ​

Événement : '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]) ​

Exemple : envoi d’un objet serveur ​

Exemple : envoi d’un objet socket ​

subprocess.signalCode ​

subprocess.spawnargs ​

subprocess.spawnfile ​

subprocess.stderr ​

subprocess.stdin ​

subprocess.stdio ​

subprocess.stdout ​

subprocess.unref() ​

maxBuffer et Unicode ​

Exigences Shell ​

Shell Windows par défaut ​

Sérialisation avancée ​

Processus enfant

Création de processus asynchrones

Lancement de fichiers `.bat` et `.cmd` sous 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`

Création de processus synchrone

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

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

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

Classe : `ChildProcess`

Événement : `'close'`

Événement : `'disconnect'`

Événement : `'error'`

Événement : `'exit'`

Événement : `'message'`

Événement : `'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])`

Exemple : envoi d’un objet serveur

Exemple : envoi d’un objet socket

`subprocess.signalCode`

`subprocess.spawnargs`

`subprocess.spawnfile`

`subprocess.stderr`

`subprocess.stdin`

`subprocess.stdio`

`subprocess.stdout`

`subprocess.unref()`

`maxBuffer` et Unicode

Exigences Shell

Shell Windows par défaut

Sérialisation avancée