Node js windows spawn — Ваш верный помощник с OS Windows

Source Code: lib/child_process.js

The node:child_process module provides the ability to spawn subprocesses in
a manner that is similar, but not identical, to popen(3). This capability
is primarily provided by the child_process.spawn() function:

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

By default, pipes for stdin, stdout, and stderr are established between
the parent Node.js process and the spawned subprocess. These pipes have
limited (and platform-specific) capacity. If the subprocess writes to
stdout in excess of that limit without the output being captured, the
subprocess blocks waiting for the pipe buffer to accept more data. This is
identical to the behavior of pipes in the shell. Use the { stdio: 'ignore' }
option if the output will not be consumed.

The command lookup is performed using the options.env.PATH environment
variable if env is in the options object. Otherwise, process.env.PATH is
used. If options.env is set without PATH, lookup on Unix is performed
on a default search path search of /usr/bin:/bin (see your operating system’s
manual for execvpe/execvp), on Windows the current processes environment
variable PATH is used.

On Windows, environment variables are case-insensitive. Node.js
lexicographically sorts the env keys and uses the first one that
case-insensitively matches. Only first (in lexicographic order) entry will be
passed to the subprocess. This might lead to issues on Windows when passing
objects to the env option that have multiple variants of the same key, such as
PATH and Path.

The child_process.spawn() method spawns the child process asynchronously,
without blocking the Node.js event loop. The child_process.spawnSync()
function provides equivalent functionality in a synchronous manner that blocks
the event loop until the spawned process either exits or is terminated.

For convenience, the node:child_process module provides a handful of
synchronous and asynchronous alternatives to child_process.spawn() and
child_process.spawnSync(). Each of these alternatives are implemented on
top of child_process.spawn() or child_process.spawnSync().

child_process.exec(): spawns a shell and runs a command within that
shell, passing the stdout and stderr to a callback function when
complete.
child_process.execFile(): similar to child_process.exec() except
that it spawns the command directly without first spawning a shell by
default.
child_process.fork(): spawns a new Node.js process and invokes a
specified module with an IPC communication channel established that allows
sending messages between parent and child.
child_process.execSync(): a synchronous version of
child_process.exec() that will block the Node.js event loop.
child_process.execFileSync(): a synchronous version of
child_process.execFile() that will block the Node.js event loop.

For certain use cases, such as automating shell scripts, the
synchronous counterparts may be more convenient. In many cases, however,
the synchronous methods can have significant impact on performance due to
stalling the event loop while spawned processes complete.

Asynchronous process creation#

The child_process.spawn(), child_process.fork(), child_process.exec(),
and child_process.execFile() methods all follow the idiomatic asynchronous
programming pattern typical of other Node.js APIs.

Each of the methods returns a ChildProcess instance. These objects
implement the Node.js EventEmitter API, allowing the parent process to
register listener functions that are called when certain events occur during
the life cycle of the child process.

The child_process.exec() and child_process.execFile() methods
additionally allow for an optional callback function to be specified that is
invoked when the child process terminates.

Spawning `.bat` and `.cmd` files on Windows#

The importance of the distinction between child_process.exec() and
child_process.execFile() can vary based on platform. On Unix-type
operating systems (Unix, Linux, macOS) child_process.execFile() can be
more efficient because it does not spawn a shell by default. On Windows,
however, .bat and .cmd files are not executable on their own without a
terminal, and therefore cannot be launched using child_process.execFile().
When running on Windows, .bat and .cmd files can be invoked using
child_process.spawn() with the shell option set, with
child_process.exec(), or by spawning cmd.exe and passing the .bat or
.cmd file as an argument (which is what the shell option and
child_process.exec() do). In any case, if the script filename contains
spaces it needs to be quoted.

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

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

// Script with spaces in the filename:
const bat = spawn('"my script.cmd" a b', { shell: true });
// or:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
});// OR...
import { exec, spawn } from 'node:child_process';

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

// Script with spaces in the filename:
const bat = spawn('"my script.cmd" a b', { shell: true });
// or:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
});

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

command <string> The command to run, with space-separated arguments.
options <Object>
- cwd <string> | <URL> Current working directory of the child process.
  Default: process.cwd().
- env <Object> Environment key-value pairs. Default: process.env.
- encoding <string> Default: 'utf8'
- shell <string> Shell to execute the command with. See
  Shell requirements and Default Windows shell. Default:
  '/bin/sh' on Unix, process.env.ComSpec on Windows.
- signal <AbortSignal> allows aborting the child process using an
  AbortSignal.
- timeout <number> Default: 0
- maxBuffer <number> Largest amount of data in bytes allowed on stdout or
  stderr. If exceeded, the child process is terminated and any output is
  truncated. See caveat at maxBuffer and Unicode.
  Default: 1024 * 1024.
- killSignal <string> | <integer> Default: 'SIGTERM'
- uid <number> Sets the user identity of the process (see setuid(2)).
- gid <number> Sets the group identity of the process (see setgid(2)).
- windowsHide <boolean> Hide the subprocess console window that would
  normally be created on Windows systems. Default: false.
callback <Function> called with the output when process terminates.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
Returns: <ChildProcess>

Spawns a shell then executes the command within that shell, buffering any
generated output. The command string passed to the exec function is processed
directly by the shell and special characters (vary based on
shell)
need to be dealt with accordingly:

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

exec('"/path/to/test file/test.sh" arg1 arg2');
// Double quotes are used so that the space in the path is not interpreted as
// a delimiter of multiple arguments.

exec('echo "The \\$HOME variable is $HOME"');
// The $HOME variable is escaped in the first instance, but not in the second.import { exec } from 'node:child_process';

exec('"/path/to/test file/test.sh" arg1 arg2');
// Double quotes are used so that the space in the path is not interpreted as
// a delimiter of multiple arguments.

exec('echo "The \\$HOME variable is $HOME"');
// The $HOME variable is escaped in the first instance, but not in the second.

Never pass unsanitized user input to this function. Any input containing shell
metacharacters may be used to trigger arbitrary command execution.

If a callback function is provided, it is called with the arguments
(error, stdout, stderr). On success, error will be null. On error,
error will be an instance of Error. The error.code property will be
the exit code of the process. By convention, any exit code other than 0
indicates an error. error.signal will be the signal that terminated the
process.

The stdout and stderr arguments passed to the callback will contain the
stdout and stderr output of the child process. By default, Node.js will decode
the output as UTF-8 and pass strings to the callback. The encoding option
can be used to specify the character encoding used to decode the stdout and
stderr output. If encoding is 'buffer', or an unrecognized character
encoding, Buffer objects will be passed to the callback instead.

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

If timeout is greater than 0, the parent process will send the signal
identified by the killSignal property (the default is 'SIGTERM') if the
child process runs longer than timeout milliseconds.

Unlike the exec(3) POSIX system call, child_process.exec() does not replace
the existing process and uses a shell to execute the command.

If this method is invoked as its util.promisify()ed version, it returns
a Promise for an Object with stdout and stderr properties. The returned
ChildProcess instance is attached to the Promise as a child property. In
case of an error (including any error resulting in an exit code other than 0), a
rejected promise is returned, with the same error object given in the
callback, but with two additional properties stdout and stderr.

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

async function lsExample() {
  const { stdout, stderr } = await exec('ls');
  console.log('stdout:', stdout);
  console.error('stderr:', stderr);
}
lsExample();import { promisify } from 'node:util';
import child_process from 'node:child_process';
const exec = promisify(child_process.exec);

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

If the signal option is enabled, calling .abort() on the corresponding
AbortController is similar to calling .kill() on the child process except
the error passed to the callback will be an AbortError:

const { exec } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();import { exec } from 'node:child_process';
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
  console.error(error); // an AbortError
});
controller.abort();

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

file <string> The name or path of the executable file to run.
args <string[]> List of string arguments.
options <Object>
- cwd <string> | <URL> Current working directory of the child process.
- env <Object> Environment key-value pairs. Default: process.env.
- encoding <string> Default: 'utf8'
- timeout <number> Default: 0
- maxBuffer <number> Largest amount of data in bytes allowed on stdout or
  stderr. If exceeded, the child process is terminated and any output is
  truncated. See caveat at maxBuffer and Unicode.
  Default: 1024 * 1024.
- killSignal <string> | <integer> Default: 'SIGTERM'
- uid <number> Sets the user identity of the process (see setuid(2)).
- gid <number> Sets the group identity of the process (see setgid(2)).
- windowsHide <boolean> Hide the subprocess console window that would
  normally be created on Windows systems. Default: false.
- windowsVerbatimArguments <boolean> No quoting or escaping of arguments is
  done on Windows. Ignored on Unix. Default: false.
- shell <boolean> | <string> If true, runs command inside of a shell. Uses
  '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different
  shell can be specified as a string. See Shell requirements and
  Default Windows shell. Default: false (no shell).
- signal <AbortSignal> allows aborting the child process using an
  AbortSignal.
callback <Function> Called with the output when process terminates.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
Returns: <ChildProcess>

The child_process.execFile() function is similar to child_process.exec()
except that it does not spawn a shell by default. Rather, the specified
executable file is spawned directly as a new process making it slightly more
efficient than child_process.exec().

The same options as child_process.exec() are supported. Since a shell is
not spawned, behaviors such as I/O redirection and file globbing are not
supported.

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

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

If the shell option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.

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

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

modulePath <string> | <URL> The module to run in the child.
args <string[]> List of string arguments.
options <Object>
- cwd <string> | <URL> Current working directory of the child process.
- detached <boolean> Prepare child process to run independently of its
  parent process. Specific behavior depends on the platform (see
  options.detached).
- env <Object> Environment key-value pairs. Default: process.env.
- execPath <string> Executable used to create the child process.
- execArgv <string[]> List of string arguments passed to the executable.
  Default: process.execArgv.
- gid <number> Sets the group identity of the process (see setgid(2)).
- serialization <string> Specify the kind of serialization used for sending
  messages between processes. Possible values are 'json' and 'advanced'.
  See Advanced serialization for more details. Default: 'json'.
- signal <AbortSignal> Allows closing the child process using an
  AbortSignal.
- killSignal <string> | <integer> The signal value to be used when the spawned
  process will be killed by timeout or abort signal. Default: 'SIGTERM'.
- silent <boolean> If true, stdin, stdout, and stderr of the child
  process will be piped to the parent process, otherwise they will be inherited
  from the parent process, see the 'pipe' and 'inherit' options for
  child_process.spawn()‘s stdio for more details.
  Default: false.
- stdio <Array> | <string> See child_process.spawn()‘s stdio.
  When this option is provided, it overrides silent. If the array variant
  is used, it must contain exactly one item with value 'ipc' or an error
  will be thrown. For instance [0, 1, 2, 'ipc'].
- uid <number> Sets the user identity of the process (see setuid(2)).
- windowsVerbatimArguments <boolean> No quoting or escaping of arguments is
  done on Windows. Ignored on Unix. Default: false.
- timeout <number> In milliseconds the maximum amount of time the process
  is allowed to run. Default: undefined.
Returns: <ChildProcess>

The child_process.fork() method is a special case of
child_process.spawn() used specifically to spawn new Node.js processes.
Like child_process.spawn(), a ChildProcess object is returned. The
returned ChildProcess will have an additional communication channel
built-in that allows messages to be passed back and forth between the parent and
child. See subprocess.send() for details.

Keep in mind that spawned Node.js child processes are
independent of the parent with exception of the IPC communication channel
that is established between the two. Each process has its own memory, with
their own V8 instances. Because of the additional resource allocations
required, spawning a large number of child Node.js processes is not
recommended.

By default, child_process.fork() will spawn new Node.js instances using the
process.execPath of the parent process. The execPath property in the
options object allows for an alternative execution path to be used.

Node.js processes launched with a custom execPath will communicate with the
parent process using the file descriptor (fd) identified using the
environment variable NODE_CHANNEL_FD on the child process.

Unlike the fork(2) POSIX system call, child_process.fork() does not clone the
current process.

The shell option available in child_process.spawn() is not supported by
child_process.fork() and will be ignored if set.

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

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`);
  }, 1_000);
} else {
  const controller = new AbortController();
  const { signal } = controller;
  const child = fork(__filename, ['child'], { signal });
  child.on('error', (err) => {
    // This will be called with err being an AbortError if the controller aborts
  });
  controller.abort(); // Stops the child process
}import { fork } from 'node:child_process';
import process from 'node:process';

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`);
  }, 1_000);
} else {
  const controller = new AbortController();
  const { signal } = controller;
  const child = fork(import.meta.url, ['child'], { signal });
  child.on('error', (err) => {
    // This will be called with err being an AbortError if the controller aborts
  });
  controller.abort(); // Stops the child process
}

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

command <string> The command to run.
args <string[]> List of string arguments.
options <Object>
- cwd <string> | <URL> Current working directory of the child process.
- env <Object> Environment key-value pairs. Default: process.env.
- argv0 <string> Explicitly set the value of argv[0] sent to the child
  process. This will be set to command if not specified.
- stdio <Array> | <string> Child’s stdio configuration (see
  options.stdio).
- detached <boolean> Prepare child process to run independently of
  its parent process. Specific behavior depends on the platform (see
  options.detached).
- uid <number> Sets the user identity of the process (see setuid(2)).
- gid <number> Sets the group identity of the process (see setgid(2)).
- serialization <string> Specify the kind of serialization used for sending
  messages between processes. Possible values are 'json' and 'advanced'.
  See Advanced serialization for more details. Default: 'json'.
- shell <boolean> | <string> If true, runs command inside of a shell. Uses
  '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different
  shell can be specified as a string. See Shell requirements and
  Default Windows shell. Default: false (no shell).
- windowsVerbatimArguments <boolean> No quoting or escaping of arguments is
  done on Windows. Ignored on Unix. This is set to true automatically
  when shell is specified and is CMD. Default: false.
- windowsHide <boolean> Hide the subprocess console window that would
  normally be created on Windows systems. Default: false.
- signal <AbortSignal> allows aborting the child process using an
  AbortSignal.
- timeout <number> In milliseconds the maximum amount of time the process
  is allowed to run. Default: undefined.
- killSignal <string> | <integer> The signal value to be used when the spawned
  process will be killed by timeout or abort signal. Default: 'SIGTERM'.
Returns: <ChildProcess>

The child_process.spawn() method spawns a new process using the given
command, with command-line arguments in args. If omitted, args defaults
to an empty array.

If the shell option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.

A third argument may be used to specify additional options, with these defaults:

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

Use cwd to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an ENOENT error
and exits immediately. ENOENT is also emitted when the command
does not exist.

Use env to specify environment variables that will be visible to the new
process, the default is process.env.

undefined values in env will be ignored.

Example of running ls -lh /usr, capturing stdout, stderr, and the
exit code:

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

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

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

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});import { spawn } from 'node:child_process';
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}`);
});

Example: A very elaborate way to run ps ax | grep ssh

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

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

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

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

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

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});import { spawn } from 'node:child_process';
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

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

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

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

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});

Example of checking for failed spawn:

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

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});import { spawn } from 'node:child_process';
const subprocess = spawn('bad_command');

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

Certain platforms (macOS, Linux) will use the value of argv[0] for the process
title while others (Windows, SunOS) will use command.

Node.js overwrites argv[0] with process.execPath on startup, so
process.argv[0] in a Node.js child process will not match the argv0
parameter passed to spawn from the parent. Retrieve it with the
process.argv0 property instead.

const { spawn } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const grep = spawn('grep', ['ssh'], { signal });
grep.on('error', (err) => {
  // This will be called with err being an AbortError if the controller aborts
});
controller.abort(); // Stops the child processimport { spawn } from 'node:child_process';
const controller = new AbortController();
const { signal } = controller;
const grep = spawn('grep', ['ssh'], { signal });
grep.on('error', (err) => {
  // This will be called with err being an AbortError if the controller aborts
});
controller.abort(); // Stops the child process

`options.detached`#

Added in: v0.7.10

On Windows, setting options.detached to true makes it possible for the
child process to continue running after the parent exits. The child process
will have its own console window. Once enabled for a child process,
it cannot be disabled.

On non-Windows platforms, if options.detached is set to true, the child
process will be made the leader of a new process group and session. Child
processes may continue running after the parent exits regardless of whether
they are detached or not. See setsid(2) for more information.

By default, the parent will wait for the detached child process to exit.
To prevent the parent process from waiting for a given subprocess to exit, use
the subprocess.unref() method. Doing so will cause the parent process’ event
loop to not include the child process in its reference count, allowing the
parent process to exit independently of the child process, unless there is an established
IPC channel between the child and the parent processes.

When using the detached option to start a long-running process, the process
will not stay running in the background after the parent exits unless it is
provided with a stdio configuration that is not connected to the parent.
If the parent process’ stdio is inherited, the child process will remain attached
to the controlling terminal.

Example of a long-running process, by detaching and also ignoring its parent
stdio file descriptors, in order to ignore the parent’s termination:

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

Alternatively one can redirect the child process’ output into files:

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`#

The options.stdio option is used to configure the pipes that are established
between the parent and child process. By default, the child’s stdin, stdout,
and stderr are redirected to corresponding subprocess.stdin,
subprocess.stdout, and subprocess.stderr streams on the
ChildProcess object. This is equivalent to setting the options.stdio
equal to ['pipe', 'pipe', 'pipe'].

For convenience, options.stdio may be one of the following strings:

'pipe': equivalent to ['pipe', 'pipe', 'pipe'] (the default)
'overlapped': equivalent to ['overlapped', 'overlapped', 'overlapped']
'ignore': equivalent to ['ignore', 'ignore', 'ignore']
'inherit': equivalent to ['inherit', 'inherit', 'inherit'] or [0, 1, 2]

Otherwise, the value of options.stdio is an array where each index corresponds
to an fd in the child. The fds 0, 1, and 2 correspond to stdin, stdout,
and stderr, respectively. Additional fds can be specified to create additional
pipes between the parent and child. The value is one of the following:

'pipe': Create a pipe between the child process and the parent process.
The parent end of the pipe is exposed to the parent as a property on the
child_process object as subprocess.stdio[fd]. Pipes
created for fds 0, 1, and 2 are also available as subprocess.stdin,
subprocess.stdout and subprocess.stderr, respectively.
These are not actual Unix pipes and therefore the child process
can not use them by their descriptor files,
e.g. /dev/fd/2 or /dev/stdout.
'overlapped': Same as 'pipe' except that the FILE_FLAG_OVERLAPPED flag
is set on the handle. This is necessary for overlapped I/O on the child
process’s stdio handles. See the
docs
for more details. This is exactly the same as 'pipe' on non-Windows
systems.
'ipc': Create an IPC channel for passing messages/file descriptors
between parent and child. A ChildProcess may have at most one IPC
stdio file descriptor. Setting this option enables the
subprocess.send() method. If the child process is a Node.js instance,
the presence of an IPC channel will enable process.send() and
process.disconnect() methods, as well as 'disconnect' and
'message' events within the child process.

Accessing the IPC channel fd in any way other than process.send()
or using the IPC channel with a child process that is not a Node.js instance
is not supported.
'ignore': Instructs Node.js to ignore the fd in the child. While Node.js
will always open fds 0, 1, and 2 for the processes it spawns, setting the fd
to 'ignore' will cause Node.js to open /dev/null and attach it to the
child’s fd.
'inherit': Pass through the corresponding stdio stream to/from the
parent process. In the first three positions, this is equivalent to
process.stdin, process.stdout, and process.stderr, respectively. In
any other position, equivalent to 'ignore'.
<Stream> object: Share a readable or writable stream that refers to a tty,
file, socket, or a pipe with the child process. The stream’s underlying
file descriptor is duplicated in the child process to the fd that
corresponds to the index in the stdio array. The stream must have an
underlying descriptor (file streams do not start until the 'open' event has
occurred).
NOTE: While it is technically possible to pass stdin as a writable or
stdout/stderr as readable, it is not recommended.
Readable and writable streams are designed with distinct behaviors, and using
them incorrectly (e.g., passing a readable stream where a writable stream is
expected) can lead to unexpected results or errors. This practice is discouraged
as it may result in undefined behavior or dropped callbacks if the stream
encounters errors. Always ensure that stdin is used as writable and
stdout/stderr as readable to maintain the intended flow of data between
the parent and child processes.
Positive integer: The integer value is interpreted as a file descriptor
that is open in the parent process. It is shared with the child
process, similar to how <Stream> objects can be shared. Passing sockets
is not supported on Windows.
null, undefined: Use default value. For stdio fds 0, 1, and 2 (in other
words, stdin, stdout, and stderr) a pipe is created. For fd 3 and up, the
default is 'ignore'.

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

// Child will use parent's stdios.
spawn('prg', [], { stdio: 'inherit' });

// Spawn child sharing only stderr.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });

// Open an extra fd=4, to interact with programs presenting a
// startd-style interface.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });import { spawn } from 'node:child_process';
import process from 'node:process';

// Child will use parent's stdios.
spawn('prg', [], { stdio: 'inherit' });

// Spawn child sharing only stderr.
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] });

// Open an extra fd=4, to interact with programs presenting a
// startd-style interface.
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] });

It is worth noting that when an IPC channel is established between the
parent and child processes, and the child process is a Node.js instance,
the child process is launched with the IPC channel unreferenced (using
unref()) until the child process registers an event handler for the
'disconnect' event or the 'message' event. This allows the
child process to exit normally without the process being held open by the
open IPC channel.
See also: child_process.exec() and child_process.fork().

Synchronous process creation#

The child_process.spawnSync(), child_process.execSync(), and
child_process.execFileSync() methods are synchronous and will block the
Node.js event loop, pausing execution of any additional code until the spawned
process exits.

Blocking calls like these are mostly useful for simplifying general-purpose
scripting tasks and for simplifying the loading/processing of application
configuration at startup.

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

file <string> The name or path of the executable file to run.
args <string[]> List of string arguments.
options <Object>
- cwd <string> | <URL> Current working directory of the child process.
- input <string> | <Buffer> | <TypedArray> | <DataView> The value which will be passed
  as stdin to the spawned process. If stdio[0] is set to 'pipe', Supplying
  this value will override stdio[0].
- stdio <string> | <Array> Child’s stdio configuration.
  See child_process.spawn()‘s stdio. stderr by default will
  be output to the parent process’ stderr unless stdio is specified.
  Default: 'pipe'.
- env <Object> Environment key-value pairs. Default: process.env.
- uid <number> Sets the user identity of the process (see setuid(2)).
- gid <number> Sets the group identity of the process (see setgid(2)).
- timeout <number> In milliseconds the maximum amount of time the process
  is allowed to run. Default: undefined.
- killSignal <string> | <integer> The signal value to be used when the spawned
  process will be killed. Default: 'SIGTERM'.
- maxBuffer <number> Largest amount of data in bytes allowed on stdout or
  stderr. If exceeded, the child process is terminated. See caveat at
  maxBuffer and Unicode. Default: 1024 * 1024.
- encoding <string> The encoding used for all stdio inputs and outputs.
  Default: 'buffer'.
- windowsHide <boolean> Hide the subprocess console window that would
  normally be created on Windows systems. Default: false.
- shell <boolean> | <string> If true, runs command inside of a shell. Uses
  '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different
  shell can be specified as a string. See Shell requirements and
  Default Windows shell. Default: false (no shell).
Returns: <Buffer> | <string> The stdout from the command.

The child_process.execFileSync() method is generally identical to
child_process.execFile() with the exception that the method will not
return until the child process has fully closed. When a timeout has been
encountered and killSignal is sent, the method won’t return until the process
has completely exited.

If the child process intercepts and handles the SIGTERM signal and
does not exit, the parent process will still wait until the child process has
exited.

If the process times out or has a non-zero exit code, this method will throw an
Error that will include the full result of the underlying
child_process.spawnSync().

If the shell option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.

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

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

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

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

    console.error({ stdout, stderr });
  }
}import { execFileSync } from 'node:child_process';

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

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

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

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

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

command <string> The command to run.
options <Object>
- cwd <string> | <URL> Current working directory of the child process.
- input <string> | <Buffer> | <TypedArray> | <DataView> The value which will be passed
  as stdin to the spawned process. If stdio[0] is set to 'pipe', Supplying
  this value will override stdio[0].
- stdio <string> | <Array> Child’s stdio configuration.
  See child_process.spawn()‘s stdio. stderr by default will
  be output to the parent process’ stderr unless stdio is specified.
  Default: 'pipe'.
- env <Object> Environment key-value pairs. Default: process.env.
- shell <string> Shell to execute the command with. See
  Shell requirements and Default Windows shell. Default:
  '/bin/sh' on Unix, process.env.ComSpec on Windows.
- uid <number> Sets the user identity of the process. (See setuid(2)).
- gid <number> Sets the group identity of the process. (See setgid(2)).
- timeout <number> In milliseconds the maximum amount of time the process
  is allowed to run. Default: undefined.
- killSignal <string> | <integer> The signal value to be used when the spawned
  process will be killed. Default: 'SIGTERM'.
- maxBuffer <number> Largest amount of data in bytes allowed on stdout or
  stderr. If exceeded, the child process is terminated and any output is
  truncated. See caveat at maxBuffer and Unicode.
  Default: 1024 * 1024.
- encoding <string> The encoding used for all stdio inputs and outputs.
  Default: 'buffer'.
- windowsHide <boolean> Hide the subprocess console window that would
  normally be created on Windows systems. Default: false.
Returns: <Buffer> | <string> The stdout from the command.

The child_process.execSync() method is generally identical to
child_process.exec() with the exception that the method will not return
until the child process has fully closed. When a timeout has been encountered
and killSignal is sent, the method won’t return until the process has
completely exited. If the child process intercepts and handles the SIGTERM
signal and doesn’t exit, the parent process will wait until the child process
has exited.

If the process times out or has a non-zero exit code, this method will throw.
The Error object will contain the entire result from
child_process.spawnSync().

Never pass unsanitized user input to this function. Any input containing shell
metacharacters may be used to trigger arbitrary command execution.

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

command <string> The command to run.
args <string[]> List of string arguments.
options <Object>
- cwd <string> | <URL> Current working directory of the child process.
- input <string> | <Buffer> | <TypedArray> | <DataView> The value which will be passed
  as stdin to the spawned process. If stdio[0] is set to 'pipe', Supplying
  this value will override stdio[0].
- argv0 <string> Explicitly set the value of argv[0] sent to the child
  process. This will be set to command if not specified.
- stdio <string> | <Array> Child’s stdio configuration.
  See child_process.spawn()‘s stdio. Default: 'pipe'.
- env <Object> Environment key-value pairs. Default: process.env.
- uid <number> Sets the user identity of the process (see setuid(2)).
- gid <number> Sets the group identity of the process (see setgid(2)).
- timeout <number> In milliseconds the maximum amount of time the process
  is allowed to run. Default: undefined.
- killSignal <string> | <integer> The signal value to be used when the spawned
  process will be killed. Default: 'SIGTERM'.
- maxBuffer <number> Largest amount of data in bytes allowed on stdout or
  stderr. If exceeded, the child process is terminated and any output is
  truncated. See caveat at maxBuffer and Unicode.
  Default: 1024 * 1024.
- encoding <string> The encoding used for all stdio inputs and outputs.
  Default: 'buffer'.
- shell <boolean> | <string> If true, runs command inside of a shell. Uses
  '/bin/sh' on Unix, and process.env.ComSpec on Windows. A different
  shell can be specified as a string. See Shell requirements and
  Default Windows shell. Default: false (no shell).
- windowsVerbatimArguments <boolean> No quoting or escaping of arguments is
  done on Windows. Ignored on Unix. This is set to true automatically
  when shell is specified and is CMD. Default: false.
- windowsHide <boolean> Hide the subprocess console window that would
  normally be created on Windows systems. Default: false.
Returns: <Object>
- pid <number> Pid of the child process.
- output <Array> Array of results from stdio output.
- stdout <Buffer> | <string> The contents of output[1].
- stderr <Buffer> | <string> The contents of output[2].
- status <number> | <null> The exit code of the subprocess, or null if the
  subprocess terminated due to a signal.
- signal <string> | <null> The signal used to kill the subprocess, or null if
  the subprocess did not terminate due to a signal.
- error <Error> The error object if the child process failed or timed out.

The child_process.spawnSync() method is generally identical to
child_process.spawn() with the exception that the function will not return
until the child process has fully closed. When a timeout has been encountered
and killSignal is sent, the method won’t return until the process has
completely exited. If the process intercepts and handles the SIGTERM signal
and doesn’t exit, the parent process will wait until the child process has
exited.

If the shell option is enabled, do not pass unsanitized user input to this
function. Any input containing shell metacharacters may be used to trigger
arbitrary command execution.

Class: `ChildProcess`#

Added in: v2.2.0

Extends: <EventEmitter>

Instances of the ChildProcess represent spawned child processes.

Instances of ChildProcess are not intended to be created directly. Rather,
use the child_process.spawn(), child_process.exec(),
child_process.execFile(), or child_process.fork() methods to create
instances of ChildProcess.

Event: `'close'`#

Added in: v0.7.7

code <number> The exit code if the child process exited on its own.
signal <string> The signal by which the child process was terminated.

The 'close' event is emitted after a process has ended and the stdio
streams of a child process have been closed. This is distinct from the
'exit' event, since multiple processes might share the same stdio
streams. The 'close' event will always emit after 'exit' was
already emitted, or 'error' if the child process failed to spawn.

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

Event: `'disconnect'`#

Added in: v0.7.2

The 'disconnect' event is emitted after calling the
subprocess.disconnect() method in parent process or
process.disconnect() in child process. After disconnecting it is no longer
possible to send or receive messages, and the subprocess.connected
property is false.

Event: `'error'`#

err <Error> The error.

The 'error' event is emitted whenever:

The process could not be spawned.
The process could not be killed.
Sending a message to the child process failed.
The child process was aborted via the signal option.

The 'exit' event may or may not fire after an error has occurred. When
listening to both the 'exit' and 'error' events, guard
against accidentally invoking handler functions multiple times.

See also subprocess.kill() and subprocess.send().

Event: `'exit'`#

Added in: v0.1.90

code <number> The exit code if the child process exited on its own.
signal <string> The signal by which the child process was terminated.

The 'exit' event is emitted after the child process ends. If the process
exited, code is the final exit code of the process, otherwise null. If the
process terminated due to receipt of a signal, signal is the string name of
the signal, otherwise null. One of the two will always be non-null.

When the 'exit' event is triggered, child process stdio streams might still be
open.

Node.js establishes signal handlers for SIGINT and SIGTERM and Node.js
processes will not terminate immediately due to receipt of those signals.
Rather, Node.js will perform a sequence of cleanup actions and then will
re-raise the handled signal.

See waitpid(2).

Event: `'message'`#

Added in: v0.5.9

message <Object> A parsed JSON object or primitive value.
sendHandle <Handle> | <undefined> undefined or a net.Socket,
net.Server, or dgram.Socket object.

The 'message' event is triggered when a child process uses
process.send() to send messages.

The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.

If the serialization option was set to 'advanced' used when spawning the
child process, the message argument can contain data that JSON is not able
to represent.
See Advanced serialization for more details.

Event: `'spawn'`#

Added in: v15.1.0, v14.17.0

The 'spawn' event is emitted once the child process has spawned successfully.
If the child process does not spawn successfully, the 'spawn' event is not
emitted and the 'error' event is emitted instead.

If emitted, the 'spawn' event comes before all other events and before any
data is received via stdout or stderr.

The 'spawn' event will fire regardless of whether an error occurs within
the spawned process. For example, if bash some-command spawns successfully,
the 'spawn' event will fire, though bash may fail to spawn some-command.
This caveat also applies when using { shell: true }.

`subprocess.channel`#

<Object> A pipe representing the IPC channel to the child process.

The subprocess.channel property is a reference to the child’s IPC channel. If
no IPC channel exists, this property is undefined.

`subprocess.channel.ref()`#

Added in: v7.1.0

This method makes the IPC channel keep the event loop of the parent process
running if .unref() has been called before.

`subprocess.channel.unref()`#

Added in: v7.1.0

This method makes the IPC channel not keep the event loop of the parent process
running, and lets it finish even while the channel is open.

`subprocess.connected`#

Added in: v0.7.2

<boolean> Set to false after subprocess.disconnect() is called.

The subprocess.connected property indicates whether it is still possible to
send and receive messages from a child process. When subprocess.connected is
false, it is no longer possible to send or receive messages.

`subprocess.disconnect()`#

Added in: v0.7.2

Closes the IPC channel between parent and child processes, allowing the child
process to exit gracefully once there are no other connections keeping it alive.
After calling this method the subprocess.connected and
process.connected properties in both the parent and child processes
(respectively) will be set to false, and it will be no longer possible
to pass messages between the processes.

The 'disconnect' event will be emitted when there are no messages in the
process of being received. This will most often be triggered immediately after
calling subprocess.disconnect().

When the child process is a Node.js instance (e.g. spawned using
child_process.fork()), the process.disconnect() method can be invoked
within the child process to close the IPC channel as well.

`subprocess.exitCode`#

<integer>

The subprocess.exitCode property indicates the exit code of the child process.
If the child process is still running, the field will be null.

`subprocess.kill([signal])`#

Added in: v0.1.90

signal <number> | <string>
Returns: <boolean>

The subprocess.kill() method sends a signal to the child process. If no
argument is given, the process will be sent the 'SIGTERM' signal. See
signal(7) for a list of available signals. This function returns true if
kill(2) succeeds, and false otherwise.

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

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');import { spawn } from 'node:child_process';
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');

The ChildProcess object may emit an 'error' event if the signal
cannot be delivered. Sending a signal to a child process that has already exited
is not an error but may have unforeseen consequences. Specifically, if the
process identifier (PID) has been reassigned to another process, the signal will
be delivered to that process instead which can have unexpected results.

While the function is called kill, the signal delivered to the child process
may not actually terminate the process.

See kill(2) for reference.

On Windows, where POSIX signals do not exist, the signal argument will be
ignored except for 'SIGKILL', 'SIGTERM', 'SIGINT' and 'SIGQUIT', and the
process will always be killed forcefully and abruptly (similar to 'SIGKILL').
See Signal Events for more details.

On Linux, child processes of child processes will not be terminated
when attempting to kill their parent. This is likely to happen when running a
new process in a shell or with the use of the shell option of ChildProcess:

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

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);import { spawn } from 'node:child_process';

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);

`subprocess[Symbol.dispose]()`#

Added in: v20.5.0, v18.18.0

Calls subprocess.kill() with 'SIGTERM'.

`subprocess.killed`#

Added in: v0.5.10

<boolean> Set to true after subprocess.kill() is used to successfully
send a signal to the child process.

The subprocess.killed property indicates whether the child process
successfully received a signal from subprocess.kill(). The killed property
does not indicate that the child process has been terminated.

`subprocess.pid`#

Added in: v0.1.90

<integer> | <undefined>

Returns the process identifier (PID) of the child process. If the child process
fails to spawn due to errors, then the value is undefined and error is
emitted.

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

Added in: v0.7.10

Calling subprocess.ref() after making a call to subprocess.unref() will
restore the removed reference count for the child process, forcing the parent
process to wait for the child process to exit before exiting itself.

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

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

subprocess.unref();
subprocess.ref();import { spawn } from 'node:child_process';
import process from 'node:process';

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

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

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

message <Object>
sendHandle <Handle> | <undefined> undefined, or a net.Socket,
net.Server, or dgram.Socket object.
options <Object> The options argument, if present, is an object used to
parameterize the sending of certain types of handles. options supports
the following properties:
- keepOpen <boolean> A value that can be used when passing instances of
  net.Socket. When true, the socket is kept open in the sending process.
  Default: false.
callback <Function>
Returns: <boolean>

When an IPC channel has been established between the parent and child processes
( i.e. when using child_process.fork()), the subprocess.send() method
can be used to send messages to the child process. When the child process is a
Node.js instance, these messages can be received via the 'message' event.

The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.

For example, in the parent script:

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

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

// Causes the child to print: CHILD got message: { hello: 'world' }
forkedProcess.send({ hello: 'world' });import { fork } from 'node:child_process';
const forkedProcess = fork(`${import.meta.dirname}/sub.js`);

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

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

And then the child script, 'sub.js' might look like this:

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

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

Child Node.js processes will have a process.send() method of their own
that allows the child process to send messages back to the parent process.

There is a special case when sending a {cmd: 'NODE_foo'} message. Messages
containing a NODE_ prefix in the cmd property are reserved for use within
Node.js core and will not be emitted in the child’s 'message'
event. Rather, such messages are emitted using the
'internalMessage' event and are consumed internally by Node.js.
Applications should avoid using such messages or listening for
'internalMessage' events as it is subject to change without notice.

The optional sendHandle argument that may be passed to subprocess.send() is
for passing a TCP server or socket object to the child process. The child process will
receive the object as the second argument passed to the callback function
registered on the 'message' event. Any data that is received
and buffered in the socket will not be sent to the child. Sending IPC sockets is
not supported on Windows.

The optional callback is a function that is invoked after the message is
sent but before the child process may have received it. The function is called with a
single argument: null on success, or an Error object on failure.

If no callback function is provided and the message cannot be sent, an
'error' event will be emitted by the ChildProcess object. This can
happen, for instance, when the child process has already exited.

subprocess.send() will return false if the channel has closed or when the
backlog of unsent messages exceeds a threshold that makes it unwise to send
more. Otherwise, the method returns true. The callback function can be
used to implement flow control.

Example: sending a server object#

The sendHandle argument can be used, for instance, to pass the handle of
a TCP server object to the child process as illustrated in the example below:

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

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

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

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

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

The child process would then receive the server object as:

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

Once the server is now shared between the parent and child, some connections
can be handled by the parent and some by the child.

While the example above uses a server created using the node:net module,
node:dgram module servers use exactly the same workflow with the exceptions of
listening on a 'message' event instead of 'connection' and using
server.bind() instead of server.listen(). This is, however, only
supported on Unix platforms.

Example: sending a socket object#

Similarly, the sendHandler argument can be used to pass the handle of a
socket to the child process. The example below spawns two children that each
handle connections with «normal» or «special» priority:

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

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

// Open up the server and send sockets to child. Use pauseOnConnect to prevent
// the sockets from being read before they are sent to the child process.
const server = createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {

  // If this is special priority...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket);
    return;
  }
  // This is normal priority.
  normal.send('socket', socket);
});
server.listen(1337);import { fork } from 'node:child_process';
import { createServer } from 'node:net';

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

// Open up the server and send sockets to child. Use pauseOnConnect to prevent
// the sockets from being read before they are sent to the child process.
const server = createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {

  // If this is special priority...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket);
    return;
  }
  // This is normal priority.
  normal.send('socket', socket);
});
server.listen(1337);

The subprocess.js would receive the socket handle as the second argument
passed to the event callback function:

process.on('message', (m, socket) => {
  if (m === 'socket') {
    if (socket) {
      // Check that the client socket exists.
      // It is possible for the socket to be closed between the time it is
      // sent and the time it is received in the child process.
      socket.end(`Request handled with ${process.argv[2]} priority`);
    }
  }
});

Do not use .maxConnections on a socket that has been passed to a subprocess.
The parent cannot track when the socket is destroyed.

Any 'message' handlers in the subprocess should verify that socket exists,
as the connection may have been closed during the time it takes to send the
connection to the child.

`subprocess.signalCode`#

<string> | <null>

The subprocess.signalCode property indicates the signal received by
the child process if any, else null.

`subprocess.spawnargs`#

<Array>

The subprocess.spawnargs property represents the full list of command-line
arguments the child process was launched with.

`subprocess.spawnfile`#

<string>

The subprocess.spawnfile property indicates the executable file name of
the child process that is launched.

For child_process.fork(), its value will be equal to
process.execPath.
For child_process.spawn(), its value will be the name of
the executable file.
For child_process.exec(), its value will be the name of the shell
in which the child process is launched.

`subprocess.stderr`#

Added in: v0.1.90

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

A Readable Stream that represents the child process’s stderr.

If the child process was spawned with stdio[2] set to anything other than 'pipe',
then this will be null.

subprocess.stderr is an alias for subprocess.stdio[2]. Both properties will
refer to the same value.

The subprocess.stderr property can be null or undefined
if the child process could not be successfully spawned.

`subprocess.stdin`#

Added in: v0.1.90

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

A Writable Stream that represents the child process’s stdin.

If a child process waits to read all of its input, the child process will not continue
until this stream has been closed via end().

If the child process was spawned with stdio[0] set to anything other than 'pipe',
then this will be null.

subprocess.stdin is an alias for subprocess.stdio[0]. Both properties will
refer to the same value.

The subprocess.stdin property can be null or undefined
if the child process could not be successfully spawned.

`subprocess.stdio`#

Added in: v0.7.10

<Array>

A sparse array of pipes to the child process, corresponding with positions in
the stdio option passed to child_process.spawn() that have been set
to the value 'pipe'. subprocess.stdio[0], subprocess.stdio[1], and
subprocess.stdio[2] are also available as subprocess.stdin,
subprocess.stdout, and subprocess.stderr, respectively.

In the following example, only the child’s fd 1 (stdout) is configured as a
pipe, so only the parent’s subprocess.stdio[1] is a stream, all other values
in the array are null.

const assert = require('node:assert');
const fs = require('node:fs');
const child_process = require('node:child_process');

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // Use parent's stdin for child.
    'pipe', // Pipe child's stdout to parent.
    fs.openSync('err.out', 'w'), // Direct child's stderr to a file.
  ],
});

assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);

assert(subprocess.stdout);
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);

assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);import assert from 'node:assert';
import fs from 'node:fs';
import child_process from 'node:child_process';

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // Use parent's stdin for child.
    'pipe', // Pipe child's stdout to parent.
    fs.openSync('err.out', 'w'), // Direct child's stderr to a file.
  ],
});

assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);

assert(subprocess.stdout);
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);

assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);

The subprocess.stdio property can be undefined if the child process could
not be successfully spawned.

`subprocess.stdout`#

Added in: v0.1.90

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

A Readable Stream that represents the child process’s stdout.

If the child process was spawned with stdio[1] set to anything other than 'pipe',
then this will be null.

subprocess.stdout is an alias for subprocess.stdio[1]. Both properties will
refer to the same value.

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

The subprocess.stdout property can be null or undefined
if the child process could not be successfully spawned.

`subprocess.unref()`#

Added in: v0.7.10

By default, the parent process will wait for the detached child process to exit.
To prevent the parent process from waiting for a given subprocess to exit, use the
subprocess.unref() method. Doing so will cause the parent’s event loop to not
include the child process in its reference count, allowing the parent to exit
independently of the child, unless there is an established IPC channel between
the child and the parent processes.

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` and Unicode#

The maxBuffer option specifies the largest number of bytes allowed on stdout
or stderr. If this value is exceeded, then the child process is terminated.
This impacts output that includes multibyte character encodings such as UTF-8 or
UTF-16. For instance, console.log('中文测试') will send 13 UTF-8 encoded bytes
to stdout although there are only 4 characters.

Shell requirements#

The shell should understand the -c switch. If the shell is 'cmd.exe', it
should understand the /d /s /c switches and command-line parsing should be
compatible.

Default Windows shell#

Although Microsoft specifies %COMSPEC% must contain the path to
'cmd.exe' in the root environment, child processes are not always subject to
the same requirement. Thus, in child_process functions where a shell can be
spawned, 'cmd.exe' is used as a fallback if process.env.ComSpec is
unavailable.

Advanced serialization#

Added in: v13.2.0, v12.16.0

Child processes support a serialization mechanism for IPC that is based on the
serialization API of the node:v8 module, based on the
HTML structured clone algorithm. This is generally more powerful and
supports more built-in JavaScript object types, such as BigInt, Map
and Set, ArrayBuffer and TypedArray, Buffer, Error, RegExp etc.

However, this format is not a full superset of JSON, and e.g. properties set on
objects of such built-in types will not be passed on through the serialization
step. Additionally, performance may not be equivalent to that of JSON, depending
on the structure of the passed data.
Therefore, this feature requires opting in by setting the
serialization option to 'advanced' when calling child_process.spawn()
or child_process.fork().

Источник

Дочерний процесс¶

v18.x.x

Стабильность: 2 – Стабильная

АПИ является удовлетворительным. Совместимость с NPM имеет высший приоритет и не будет нарушена кроме случаев явной необходимости.

Модуль node:child_process предоставляет возможность порождать подпроцессы способом, который похож, но не идентичен popen(3). Эта возможность в основном обеспечивается функцией child_process.spawn():

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(
        `детский процесс завершился с кодом ${code}`
    );
});

По умолчанию между родительским процессом Node.js и порожденным подпроцессом устанавливаются каналы для stdin, stdout и stderr. Эти каналы имеют ограниченную (и зависящую от платформы) пропускную способность. Если подпроцесс записывает в stdout больше этого лимита без перехвата вывода, подпроцесс блокируется, ожидая, пока буфер трубы примет больше данных. Это идентично поведению труб в оболочке. Используйте опцию { stdio: 'ignore' }, если вывод не будет потребляться.

Поиск команды выполняется с использованием переменной окружения options.env.PATH, если env находится в объекте options. В противном случае используется process.env.PATH. Если options.env задана без PATH, поиск на Unix выполняется по пути поиска по умолчанию /usr/bin:/bin (см. руководство вашей операционной системы по execvpe/execvp), на Windows используется переменная окружения текущих процессов PATH.

В Windows переменные окружения не чувствительны к регистру. Node.js лексикографически сортирует ключи env и использует первый, который нечувствителен к регистру. Только первая (в лексикографическом порядке) запись будет передана подпроцессу. Это может привести к проблемам в Windows при передаче в опцию env объектов, имеющих несколько вариантов одного и того же ключа, например, PATH и Path.

Метод child_process.spawn() порождает дочерний процесс асинхронно, не блокируя цикл событий Node.js. Функция child_process.spawnSync() обеспечивает эквивалентную функциональность в синхронном режиме, блокируя цикл событий до тех пор, пока порожденный процесс не выйдет или не завершится.

Для удобства модуль node:child_process предоставляет несколько синхронных и асинхронных альтернатив child_process.spawn() и child_process.spawnSync(). Каждая из этих альтернатив реализуется поверх child_process.spawn() или child_process.spawnSync().

child_process.exec(): порождает оболочку и выполняет команду внутри этой оболочки, передавая stdout и stderr в функцию обратного вызова после завершения.
child_process.execFile(): аналогичен child_process.exec(), за исключением того, что он порождает команду напрямую, без предварительного порождения оболочки по умолчанию.
child_process.fork(): порождает новый процесс Node.js и вызывает указанный модуль с установленным каналом связи IPC, который позволяет отправлять сообщения между родительским и дочерним процессами.
child_process.execSync(): синхронная версия child_process.exec(), которая будет блокировать цикл событий Node.js.
child_process.execFileSync(): синхронная версия child_process.execFile(), которая блокирует цикл событий Node.js.

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

Асинхронное создание процессов¶

Методы child_process.spawn(), child_process.fork(), child_process.exec() и child_process. execFile() методы следуют идиоматической схеме асинхронного программирования, характерной для других API Node.js.

Каждый из методов возвращает экземпляр ChildProcess. Эти объекты реализуют API Node.js EventEmitter, позволяя родительскому процессу регистрировать функции слушателей, которые вызываются при наступлении определенных событий в течение жизненного цикла дочернего процесса.

Методы child_process.exec() и child_process.execFile() дополнительно позволяют указать необязательную функцию callback, которая вызывается при завершении дочернего процесса.

Порождение файлов `.bat` и `.cmd` в Windows¶

Важность различия между child_process.exec() и child_process.execFile() может зависеть от платформы. В операционных системах типа Unix (Unix, Linux, macOS) child_process.execFile() может быть более эффективным, поскольку по умолчанию не порождает оболочку. Однако в Windows файлы .bat и .cmd не исполняются самостоятельно без терминала и поэтому не могут быть запущены с помощью child_process.execFile(). При работе под Windows файлы .bat и .cmd могут быть вызваны с помощью child_process.spawn() с установленной опцией shell, с child_process. exec(), или путем запуска cmd.exe и передачи файла .bat или .cmd в качестве аргумента (что и делают опция shell и child_process.exec()). В любом случае, если имя файла скрипта содержит пробелы, его необходимо заключить в кавычки.

// Только для Windows...
const { spawn } = require('node:child_process');
const bat = spawn('cmd.exe', ['/c', 'my.bat']);

bat.stdout.on('data', (data) => {
    console.log(data.toString());
});

bat.stderr.on('data', (data) => {
    console.error(data.toString());
});

bat.on('exit', (code) => {
    console.log(`Child exited with code ${code}`);
});

// ИЛИ...
const { exec, spawn } = require('node:child_process');
exec('my.bat', (err, stdout, stderr) => {
    if (err) {
        console.error(err);
        return;
    }
    console.log(stdout);
});

// Сценарий с пробелами в имени файла:
const bat = spawn('"my script.cmd"', ['a', 'b'], {
    shell: true,
});
// или:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
    // ...
});

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

команда <string> Команда для выполнения, с аргументами, разделенными пробелами.
options <Object>
- cwd <string> | <URL> Текущий рабочий каталог дочернего процесса. По умолчанию: process.cwd().
- env <Object> Пары ключ-значение окружения. По умолчанию: process.env.
- encoding <string> По умолчанию: 'utf8'.
- шелл <string> Оболочка для выполнения команды. По умолчанию: '/bin/sh' на Unix, process.env.ComSpec на Windows.
- signal <AbortSignal> позволяет прервать дочерний процесс с помощью сигнала AbortSignal.
- timeout <number> Default: 0
- maxBuffer <number> Наибольший объем данных в байтах, разрешенный для передачи на stdout или stderr. При превышении этого значения дочерний процесс завершается, а все выходные данные усекаются. См. предостережение в maxBuffer и Unicode. По умолчанию: 1024 * 1024.
- killSignal <string> | <integer> По умолчанию: `’SIGTERM«.
- uid <number> Задает идентификатор пользователя процесса (см. setuid(2)).
- gid <number> Устанавливает групповую принадлежность процесса (см. setgid(2)).
- windowsHide <boolean> Скрыть консольное окно подпроцесса, которое обычно создается в системах Windows. По умолчанию: false.
callback <Function> вызывается с выводом при завершении процесса.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
Возвращает: ChildProcess

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

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

exec('"/path/to/test file/test.sh" arg1 arg2');
// Double quotes are used so that the space in the path is not interpreted as
// a delimiter of multiple arguments.

exec('echo "The \\$HOME variable is $HOME"');
// The $HOME variable is escaped in the first instance, but not in the second.

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

Если предоставлена функция callback, она вызывается с аргументами (error, stdout, stderr). В случае успеха, error будет null. При ошибке error будет экземпляром Error. Свойство error.code будет кодом завершения процесса. По соглашению, любой код выхода, отличный от 0, означает ошибку. Свойство error.signal будет сигналом, который завершил процесс.

Аргументы stdout и stderr, передаваемые обратному вызову, будут содержать вывод stdout и stderr дочернего процесса. По умолчанию Node.js будет декодировать вывод как UTF-8 и передавать строки обратному вызову. Опция encoding может быть использована для указания кодировки символов, используемой для декодирования вывода stdout и stderr. Если encoding — это 'buffer' или нераспознанная кодировка, то вместо нее обратному вызову будут переданы объекты `Buffer».

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

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

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

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

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

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

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

const { exec } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = exec('grep ssh', { signal }, (error) => {
    console.error(error); // an AbortError
});
controller.abort();

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

file <string> Имя или путь исполняемого файла для запуска.
args <string[]> Список строковых аргументов.
options <Object>
- cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
- env <Object> Пары ключ-значение окружения. По умолчанию: process.env.
- encoding <string> По умолчанию: 'utf8'.
- timeout <number> По умолчанию: 0
- maxBuffer <number> Наибольший объем данных в байтах, разрешенный для вывода на stdout или stderr. При превышении этого значения дочерний процесс завершается, а все выходные данные усекаются. См. предостережение в maxBuffer и Unicode. По умолчанию: 1024 * 1024.
- killSignal <string> | <integer> По умолчанию: SIGTERM.
- uid <number> Задает идентификатор пользователя процесса (см. setuid(2)).
- gid <number> Устанавливает групповую принадлежность процесса (см. setgid(2)).
- windowsHide <boolean> Скрыть консольное окно подпроцесса, которое обычно создается в системах Windows. По умолчанию: false.
- windowsVerbatimArguments <boolean> Кавычки и экранирование аргументов не выполняются в Windows. Игнорируется на Unix. По умолчанию: false.
- shell <boolean> | <string> Если true, запускает команду внутри оболочки. Используется '/bin/sh' на Unix, и process.env.ComSpec на Windows. Другая оболочка может быть задана в виде строки. По умолчанию: false (нет оболочки).
- signal <AbortSignal> позволяет прервать дочерний процесс с помощью сигнала AbortSignal.
callback <Function> Вызывается с выводом при завершении процесса.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
Возвращает: ChildProcess

Функция child_process.execFile() аналогична child_process.exec() за исключением того, что она не порождает оболочку по умолчанию. Вместо этого, указанный исполняемый файл порождается непосредственно как новый процесс, что делает его немного более эффективным, чем child_process.exec().

Поддерживаются те же опции, что и в child_process.exec(). Так как оболочка не порождается, такие поведения, как перенаправление ввода/вывода и глоббинг файлов, не поддерживаются.

const { execFile } = require('node:child_process');
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
  if (error) {
    бросить ошибку;
  }
  console.log(stdout);
});

Аргументы stdout и stderr, передаваемые обратному вызову, будут содержать вывод stdout и stderr дочернего процесса. По умолчанию Node.js декодирует вывод как UTF-8 и передает строки обратному вызову. Опция encoding может быть использована для указания кодировки символов, используемой для декодирования вывода stdout и stderr. Если encoding — это 'buffer' или нераспознанная кодировка символов, то вместо нее обратному вызову будут переданы объекты `Buffer».

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

const util = require('node:util');
const execFile = util.promisify(
    require('node:child_process').execFile
);
async function getVersion() {
    const { stdout } = await execFile('node', [
        '--version',
    ]);
    console.log(stdout);
}
getVersion();

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

const { execFile } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const child = execFile(
    'node',
    ['--version'],
    { signal },
    (error) => {
        console.error(error); // ошибка AbortError
    }
);
controller.abort();

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

modulePath <string> | <URL> Модуль для запуска в дочернем процессе.
args <string[]> Список строковых аргументов.
options <Object>
- cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
- detached <boolean> Подготовить дочерний процесс к запуску независимо от родительского процесса. Конкретное поведение зависит от платформы, см. options.detached.
- env <Object> Пары ключей-значений окружения. По умолчанию: process.env.
- execPath <string> Исполняемый файл, используемый для создания дочернего процесса.
- execArgv <string[]> Список строковых аргументов, передаваемых исполняемому процессу. По умолчанию: process.execArgv.
- gid <number> Устанавливает групповую идентификацию процесса (см. setgid(2)).
- serialization <string> Укажите вид сериализации, используемой для отправки сообщений между процессами. Возможные значения: 'json' и 'advanced'. По умолчанию: 'json'.
- signal <AbortSignal> Позволяет закрыть дочерний процесс с помощью сигнала AbortSignal.
- killSignal <string> | <integer> Значение сигнала, который будет использоваться, когда порожденный процесс будет убит по таймауту или сигналу abort. По умолчанию: 'SIGTERM'.
- silent <boolean> Если true, stdin, stdout и stderr дочернего процесса будут передаваться по трубопроводу родительскому, иначе они будут наследоваться от родительского, подробнее см. опции 'pipe' и 'inherit' для child_process.spawn() в stdio. По умолчанию: false.
- stdio <Array> | <string> См. child_process.spawn() в stdio. Если указана эта опция, она отменяет silent. Если используется вариант массива, то он должен содержать ровно один элемент со значением 'ipc', иначе будет выдана ошибка. Например, [0, 1, 2, 'ipc'].
- uid <number> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
- windowsVerbatimArguments <boolean> В Windows аргументы не кавыряются и не экранируются. Игнорируется на Unix. По умолчанию: false.
- timeout <number> В миллисекундах максимальное время, в течение которого процесс будет выполняться. По умолчанию: undefined.
Возвращает: ChildProcess

Метод child_process.fork() является частным случаем child_process.spawn(), используемым специально для порождения новых процессов Node.js. Подобно child_process.spawn(), возвращается объект ChildProcess. Возвращаемый ChildProcess будет иметь встроенный дополнительный канал связи, который позволяет передавать сообщения туда и обратно между родительским и дочерним процессами. Подробности смотрите в subprocess.send().

Помните, что порожденные дочерние процессы Node.js не зависят от родительского, за исключением следующих случаев

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

команда <string> Команда для запуска.
args <string[]> Список строковых аргументов.
options <Object>
- cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
- env <Object> Пары ключ-значение окружения. По умолчанию: process.env.
- argv0 <string> Явно задает значение argv[0], передаваемое дочернему процессу. Если значение не указано, оно будет установлено в command.
- stdio <Array> | <string> Конфигурация stdio дочернего процесса (см. options.stdio).
- detached <boolean> Подготовить дочерний процесс к работе независимо от его родительского процесса. Конкретное поведение зависит от платформы, см. options.detached.
- uid <number> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
- gid <number> Устанавливает групповую принадлежность процесса (см. setgid(2)).
- serialization <string> Укажите вид сериализации, используемой для отправки сообщений между процессами. Возможные значения: json и advanced. По умолчанию: 'json'.
- shell <boolean> | <string> Если true, запускает команду внутри оболочки. Используется '/bin/sh' на Unix, и process.env.ComSpec на Windows. Другая оболочка может быть задана в виде строки. По умолчанию: false (нет оболочки).
- windowsVerbatimArguments <boolean> В Windows аргументы не кавыряются и не экранируются. Игнорируется на Unix. Это значение автоматически устанавливается в true, если указана hell и это CMD. По умолчанию: false.
- windowsHide <boolean> Скрыть консольное окно подпроцесса, которое обычно создается в системах Windows. По умолчанию: false.
- signal <AbortSignal> позволяет прервать дочерний процесс с помощью сигнала AbortSignal.
- timeout <number> В миллисекундах максимальное количество времени, которое разрешено процессу. По умолчанию: undefined.
- killSignal <string> | <integer> Значение сигнала, который будет использоваться, когда порожденный процесс будет убит по таймауту или сигналу прерывания. По умолчанию: 'SIGTERM'.
Возвращает: ChildProcess

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

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

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

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

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

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

Неопределенные значения в env будут проигнорированы.

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

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

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

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

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

Пример: Очень сложный способ выполнить команду ps ax | grep ssh.

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

ps.stdout.on('data', (data) => {
    grep.stdin.write(data);
});

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

ps.on('close', (code) => {
    if (code !== 0) {
        console.log(`ps process exited with code ${code}`);
    }
    grep.stdin.end();
});

grep.stdout.on('data', (data) => {
    console.log(data.toString());
});

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

grep.on('close', (code) => {
    if (code !== 0) {
        console.log(
            `grep process exited with code ${code}`
        );
    }
});

Пример проверки неудачного spawn:

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

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

Некоторые платформы (macOS, Linux) будут использовать значение argv[0] для названия процесса, в то время как другие (Windows, SunOS) будут использовать command.

Node.js перезаписывает argv[0] с process.execPath при запуске, поэтому process.argv[0] в дочернем процессе Node.js не будет соответствовать параметру argv0, переданному в spawn от родителя. Вместо этого получите его с помощью свойства process.argv0.

const { spawn } = require('node:child_process');
const controller = new AbortController();
const { signal } = controller;
const grep = spawn('grep', ['ssh'], { signal });
grep.on('error', (err) => {
    // This will be called with err being an AbortError if the controller aborts
});
controller.abort(); // Stops the child process

`options.detached`¶

В Windows установка options.detached в true позволяет дочернему процессу продолжить работу после завершения родительского. У дочернего процесса будет собственное консольное окно. После включения этого параметра для дочернего процесса его нельзя отключить.

На платформах, отличных от Windows, если options.detached имеет значение true, дочерний процесс становится лидером новой группы процессов и сессии. Дочерние процессы могут продолжать выполняться после завершения родительского, независимо от того, отсоединены они или нет. Дополнительную информацию см. в setsid(2).

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

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

Пример долго работающего процесса, отсоединяющего и также игнорирующего файловые дескрипторы своего родителя stdio, чтобы игнорировать завершение родителя:

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

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

subprocess.unref();

В качестве альтернативы можно перенаправить вывод дочернего процесса в файлы:

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

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

subprocess.unref();

`options.stdio`¶

Опция options.stdio используется для настройки каналов, которые устанавливаются между родительским и дочерним процессом. По умолчанию дочерние потоки stdin, stdout и stderr перенаправляются в соответствующие потоки subprocess.stdin, subprocess.stdout и subprocess.stderr объекта ChildProcess. Это эквивалентно установке options.stdio равным ['pipe', 'pipe', 'pipe'].

Для удобства, options.stdio может быть одной из следующих строк:

'pipe': равно ['pipe', 'pipe', 'pipe'] (по умолчанию)
'overlapped': эквивалентно ['overlapped', 'overlapped', 'overlapped']
'ignore': эквивалентно ['ignore', 'ignore', 'ignore']
'inherit': эквивалентно ['inherit', 'inherit', 'inherit'] или [0, 1, 2].

В противном случае, значение options.stdio представляет собой массив, где каждый индекс соответствует fd в дочерней системе. Fds 0, 1 и 2 соответствуют stdin, stdout и stderr, соответственно. Дополнительные fd могут быть указаны для создания дополнительных каналов между родительским и дочерним сервером. Значение является одним из следующих:

труба: Создать трубу между дочерним процессом и родительским процессом. Родительский конец трубы отображается для родителя как свойство объекта child_process в виде subprocess.stdio[fd]. Трубы, созданные для fds 0, 1 и 2, также доступны как subprocess.stdin, subprocess.stdout и subprocess.stderr, соответственно. Это не настоящие трубы Unix, и поэтому дочерний процесс не может использовать их через свои дескрипторные файлы, например, /dev/fd/2 или /dev/stdout.
перекрытые: То же самое, что и 'pipe', за исключением того, что на дескрипторе устанавливается флаг FILE_FLAG_OVERLAPPED. Это необходимо для перекрывающегося ввода/вывода на stdio хэндлах дочерних процессов. Более подробную информацию смотрите в docs. Это точно так же, как 'pipe' в системах, отличных от Windows.
IPC: Создайте IPC-канал для передачи сообщений/файловых дескрипторов между родительским и дочерним процессами. ChildProcess может иметь не более одного файлового дескриптора IPC stdio. Установка этой опции включает метод subprocess.send(). Если дочерний процесс является процессом Node.js, наличие IPC-канала включит process.send() и process. disconnect() методы, а также события 'disconnect' и 'message' в дочерней системе.

Доступ к IPC-каналу fd любым способом, кроме process.send() или использование IPC-канала с дочерним процессом, который не является экземпляром Node.js, не поддерживается.
игнорировать: Указывает Node.js игнорировать fd в дочернем процессе. Хотя Node.js всегда будет открывать fd 0, 1 и 2 для порождаемых им процессов, установка fd в 'ignore' заставит Node.js открыть /dev/null и прикрепить его к fd дочернего процесса.
наследовать: Передача соответствующего потока stdio в/из родительского процесса. В первых трех позициях это эквивалентно process.stdin, process.stdout и process.stderr, соответственно. В любой другой позиции эквивалентно 'ignore'.
Объект <Stream>: Разделять с дочерним процессом поток, доступный для чтения или записи, который ссылается на tty, файл, сокет или трубу. Дескриптор файла, лежащего в основе потока, дублируется в дочернем процессе на fd, соответствующий индексу в массиве stdio. Поток должен иметь базовый дескриптор (файловые потоки не имеют его до тех пор, пока не произойдет событие `’open»).
Положительное целое число: Целочисленное значение интерпретируется как дескриптор файла, который открыт в родительском процессе. Он передается дочернему процессу, аналогично тому, как могут передаваться объекты <Stream>. Передача сокетов не поддерживается в Windows.
null, undefined: Использовать значение по умолчанию. Для stdio fds 0, 1 и 2 (другими словами, stdin, stdout и stderr) создается труба. Для fd 3 и выше по умолчанию используется значение игнорировать.

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

// Child will use parent's stdios.
spawn('prg', [], { stdio: 'inherit' });

// Spawn child sharing only stderr.
spawn('prg', [], {
    stdio: ['pipe', 'pipe', process.stderr],
});

// Open an extra fd=4, to interact with programs presenting a
// startd-style interface.
spawn('prg', [], {
    stdio: ['pipe', null, null, null, 'pipe'],
});

Следует отметить, что когда между родительским и дочерним процессами установлен IPC-канал, и дочерний процесс является процессом Node.js, дочерний процесс запускается с IPC-каналом без ссылки (с помощью unref()), пока дочерний процесс не зарегистрирует обработчик событий для события 'disconnect' или 'message'. Это позволяет дочернему процессу нормально завершить работу, не удерживая процесс открытым IPC-каналом.

В Unix-подобных операционных системах метод child_process.spawn() выполняет операции с памятью синхронно перед отсоединением цикла событий от дочернего процесса. Приложения с большим объемом памяти могут счесть частые вызовы child_process.spawn() узким местом. Для получения дополнительной информации смотрите V8 issue 7381.

См. также: child_process.exec() и child_process.fork().

Синхронное создание процессов¶

Методы child_process.spawnSync(), child_process.execSync() и child_process. execFileSync() являются синхронными и блокируют цикл событий Node.js, приостанавливая выполнение любого дополнительного кода до выхода порожденного процесса.

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

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

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

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

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

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

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

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

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

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

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

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

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

команда <string> Команда для запуска.
args <string[]> Список строковых аргументов.
options <Object>
- cwd <string> | <URL> Текущий рабочий каталог дочернего процесса.
- input <string> | <Buffer> | <TypedArray> | <DataView> Значение, которое будет передано в качестве stdin порожденному процессу. Передача этого значения переопределит stdio[0].
- argv0 <string> Явно задает значение argv[0], передаваемое дочернему процессу. Если значение не указано, оно будет установлено в command.
- stdio <string> | <Array> Конфигурация stdio дочернего процесса.
- env <Object> Пары ключ-значение окружения. По умолчанию: process.env.
- uid <number> Устанавливает идентификатор пользователя процесса (см. setuid(2)).
- gid <number> Устанавливает групповую принадлежность процесса (см. setgid(2)).
- timeout <number> В миллисекундах максимальное количество времени, которое разрешено процессу. По умолчанию: undefined.
- killSignal <string> | <integer> Значение сигнала, который будет использоваться, когда порожденный процесс будет убит. По умолчанию: `’SIGTERM«.
- maxBuffer <number> Наибольший объем данных в байтах, разрешенный для передачи на stdout или stderr. При превышении этого значения дочерний процесс завершается, а все выходные данные усекаются. См. предостережение в maxBuffer и Unicode. По умолчанию: 1024 * 1024.
- encoding <string> Кодировка, используемая для всех входов и выходов stdio. По умолчанию: 'buffer'.
- shell <boolean> | <string> Если true, запускает команду внутри оболочки. Используется '/bin/sh' на Unix, и process.env.ComSpec на Windows. Другая оболочка может быть задана в виде строки. По умолчанию: false (нет оболочки).
- windowsVerbatimArguments <boolean> В Windows аргументы не кавыряются и не экранируются. Игнорируется на Unix. Устанавливается в true автоматически, если указана hell и это CMD. По умолчанию: false.
- windowsHide <boolean> Скрыть консольное окно подпроцесса, которое обычно создается в системах Windows. По умолчанию: false.
Возвращает: <Object>
- pid <number> Pid дочернего процесса.
- output <Array> Массив результатов вывода через stdio.
- stdout <Buffer> | <string> Содержимое output[1].
- stderr <Buffer> | <string> Содержимое output[2].
- status <number> | <null> Код завершения подпроцесса, или null, если подпроцесс завершился из-за сигнала.
- signal <string> | <null> Сигнал, используемый для завершения подпроцесса, или null, если подпроцесс не завершился из-за сигнала.
- error <Error> Объект ошибки, если дочерний процесс завершился неудачно или по таймеру.

Метод child_process.spawnSync() в целом идентичен child_process.spawn() за исключением того, что функция не возвращается до тех пор, пока дочерний процесс не будет полностью закрыт. Когда таймаут был встречен

Класс: `ChildProcess`¶

Расширяет: <EventEmitter>

Экземпляры ChildProcess представляют порожденные дочерние процессы.

Экземпляры ChildProcess не предназначены для прямого создания. Вместо этого используйте child_process.spawn(), child_process.exec(), child_process. execFile(), или child_process.fork() методы для создания экземпляров ChildProcess.

Событие: `'close'`¶

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

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

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(
        `детский процесс закрывает все stdio с кодом ${code}`
    );
});

ls.on('exit', (code) => {
    console.log(
        `детский процесс завершился с кодом ${code}`
    );
});

Событие: `disconnect`¶

Событие disconnect возникает после вызова метода subprocess.disconnect() в родительском процессе или process.disconnect() в дочернем процессе. После отключения невозможно отправлять или получать сообщения, а свойство subprocess.connected равно false.

Событие: `error`¶

err <Error> Ошибка.

Событие 'error' генерируется всякий раз, когда:

Процесс не может быть порожден.
Процесс не может быть завершен.
Отправка сообщения дочернему процессу не удалась.
Дочерний процесс был прерван через опцию signal.

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

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

Событие: `exit`¶

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

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

Когда срабатывает событие `’exit», потоки stdio дочерних процессов могут быть все еще открыты.

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

См. waitpid(2).

Событие: `message`¶

сообщение <Object> Разобранный объект JSON или примитивное значение.
sendHandle Handle Объект net.Socket или net.Server, или неопределено.

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

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

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

Событие: `spawn`¶

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

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

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

`subprocess.channel`¶

<Object> Труба, представляющая IPC-канал дочернего процесса.

Свойство subprocess.channel является ссылкой на IPC-канал дочернего процесса. Если IPC-канал не существует, это свойство не определено.

`subprocess.channel.ref()`¶

Этот метод заставляет IPC-канал поддерживать цикл событий родительского процесса, если до этого был вызван .unref().

`subprocess.channel.unref()`¶

Этот метод заставляет IPC-канал не поддерживать цикл событий родительского процесса и позволяет ему завершиться, даже если канал открыт.

`subprocess.connected`¶

<boolean> Устанавливается в false после вызова subprocess.disconnect().

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

`subprocess.disconnect()`¶

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

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

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

`subprocess.exitCode`¶

<integer>

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

`subprocess.kill([signal])`¶

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

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

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

grep.on('close', (code, signal) => {
    console.log(
        `детский процесс завершен из-за получения сигнала ${сигнал}`
    );
});

// Посылаем процессу сигнал SIGHUP.
grep.kill('SIGHUP');

Объект ChildProcess может выдать событие 'error', если сигнал не может быть доставлен. Отправка сигнала дочернему процессу, который уже завершился, не является ошибкой, но может иметь непредвиденные последствия. В частности, если идентификатор процесса (PID) был переназначен другому процессу, сигнал будет доставлен этому процессу, что может привести к неожиданным результатам.

Хотя функция называется kill, сигнал, переданный дочернему процессу, может не завершить процесс.

Для справки см. kill(2).

В Windows, где POSIX-сигналы не существуют, аргумент signal будет проигнорирован, и процесс будет убит принудительно и внезапно (аналогично 'SIGKILL'). Более подробную информацию смотрите в Signal Events.

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

'use strict';
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(); // Не завершает процесс Node.js в оболочке.
}, 2000);

`subprocess.killed`¶

<boolean> Устанавливается в true после того, как subprocess.kill() успешно отправил сигнал дочернему процессу.

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

`subprocess.pid`¶

<integer> | <undefined>

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

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

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

`subprocess.ref()`¶

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

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

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

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

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

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

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

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

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

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

n.on('message', (m) => {
    console.log('PARENT получил сообщение:', m);
});

// Вызывает печать для ребенка: CHILD got message: { hello: 'world' }
n.send({ hello: 'world' });

И тогда дочерний скрипт, 'sub.js', может выглядеть следующим образом:

process.on('message', (m) => {
    console.log('CHILD получил сообщение:', m);
});

// Вызывает печать родителя: PARENT got message: { foo: 'bar', baz: null }
process.send({ foo: 'bar', baz: NaN });

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

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

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

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

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

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

Пример: передача объекта сервера¶

Аргумент sendHandle можно использовать, например, для передачи дочернему процессу хэндла объекта TCP-сервера, как показано в примере ниже:

const subprocess = require('node:child_process').fork(
    'subprocess.js'
);

// Открываем объект сервера и передаем хэндл.
const server = require('node:net').createServer();
server.on('connection', (socket) => {
    socket.end('handled by parent');
});
server.listen(1337, () => {
    subprocess.send('server', server);
});

Тогда дочерняя программа получит объект сервера в виде:

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

После того, как сервер стал общим для родителя и ребенка, некоторые соединения могут обрабатываться родителем, а некоторые — ребенком.

Хотя в приведенном примере используется сервер, созданный с помощью модуля node:net, серверы модуля node:dgram используют точно такой же рабочий процесс, за исключением того, что вместо соединения используется событие 'message' и вместо server.bind() используется server.listen(). Однако это поддерживается только на платформах Unix.

Пример: отправка объекта сокета¶

Аналогично, аргумент sendHandler можно использовать для передачи хэндла сокета дочернему процессу. Пример ниже порождает два дочерних процесса, каждый из которых обрабатывает соединения с «обычным» или «специальным» приоритетом:

const { fork } = require('node:child_process');
const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);

// Открываем сервер и посылаем сокеты дочернему серверу. Используйте pauseOnConnect, чтобы предотвратить.
// чтения сокетов до того, как они будут отправлены дочернему процессу.
const server = require('node:net').createServer({
    pauseOnConnect: true,
});
server.on('connection', (socket) => {
    // Если это специальный приоритет...
    if (socket.remoteAddress === '74.125.127.100') {
        special.send('socket', socket);
        return;
    }
    // Это обычный приоритет.
    normal.send('socket', socket);
});
server.listen(1337);

subprocess.js будет получать хэндл сокета в качестве второго аргумента, передаваемого в функцию обратного вызова события:

process.on('message', (m, socket) => {
    if (m === 'socket') {
        if (socket) {
            // Проверяем, существует ли клиентский сокет.
            // Возможно, что сокет будет закрыт между моментом отправки и моментом получения сообщения.
            // отправки и получения в дочернем процессе.
            socket.end(
                `Request handled with ${process.argv[2]} priority`
            );
        }
    }
});

Не используйте .maxConnections для сокета, который был передан подпроцессу. Родитель не сможет отследить, когда сокет будет уничтожен.

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

`subprocess.signalCode`¶

<string> | <null>

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

`subprocess.spawnargs`¶

<Array>

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

`subprocess.spawnfile`¶

<string>

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

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

`subprocess.stderr`¶

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

Читаемый поток, представляющий stderr дочернего процесса.

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

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

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

`subprocess.stdin`¶

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

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

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

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

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

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

`subprocess.stdio`¶

<Array>

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

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

const assert = require('node:assert');
const fs = require('node:fs');
const child_process = require('node:child_process');

const subprocess = child_process.spawn('ls', {
    stdio: [
        0, // Использовать родительский stdin для дочернего.
        'pipe', // Передавать stdout ребенка родителю.
        fs.openSync('err.out', 'w'), // Направлять stderr ребенка в файл.
    ],
});

assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);

assert(subprocess.stdout);
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);

assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);

Свойство subprocess.stdio может быть «неопределенным», если дочерний процесс не может быть успешно порожден.

`subprocess.stdout`¶

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

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

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

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

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

const subprocess = spawn('ls');

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

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

`subprocess.unref()`¶

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

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

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

subprocess.unref();

`maxBuffer` и Юникод¶

Опция maxBuffer определяет наибольшее количество байт, разрешенное для передачи на stdout или stderr. Если это значение превышено, то дочерний процесс завершается. Это влияет на вывод, который включает многобайтовые кодировки символов, такие как UTF-8 или UTF-16. Например, console.log('中文测试') отправит 13 байт в кодировке UTF-8 на stdout, хотя там всего 4 символа.

Требования к оболочке¶

Оболочка должна понимать переключатель -c. Если оболочка — cmd.exe, она должна понимать переключатели /d /s /c, и разбор командной строки должен быть совместим.

Оболочка Windows по умолчанию¶

Хотя Microsoft указывает, что %COMSPEC% должен содержать путь к 'cmd.exe' в корневом окружении, дочерние процессы не всегда подчиняются этому требованию. Таким образом, в функциях child_process, где может быть порождена оболочка, 'cmd.exe' используется как запасной вариант, если process.env.ComSpec недоступен.

Расширенная сериализация¶

Дочерние процессы поддерживают механизм сериализации для IPC, который основан на serialization API модуля node:v8, основанном на HTML structured clone algorithm. Он в целом более мощный и поддерживает больше встроенных типов объектов JavaScript, таких как BigInt, Map и Set, ArrayBuffer и TypedArray, Buffer, Error, RegExp и др.

Однако этот формат не является полным супермножеством JSON, и, например, свойства, установленные на объектах таких встроенных типов, не будут передаваться через шаг сериализации. Кроме того, производительность может быть не эквивалентна производительности JSON, в зависимости от структуры передаваемых данных. Поэтому эта возможность требует выбора, установив опцию serialization в advanced при вызове child_process.spawn() или child_process.fork().

Источник

A child process is a process created by a parent process. Node allows us to run a system command within a child process and listen in on its input/output. This includes being able to pass arguments to the command, and even pipe the results of one command to another.

We can create a child process in four different ways:

spawn
fork
exec
execFile

Windows and Linux operating systems use different commands, the examples demonstrated here use Unix commands which may not work in a Windows OS.

We can overcome this problem by identifying the Operating System and alternate which command to execute. For example:

const {platform} = require('os'),
osType = platform();
let command;
if (osType == 'win32')
 command = 'cls';
else
 command = 'clear';

child_process.spawn (command[, argsArray][, optionsObject])

spawn is the most common function, it launches a command in a new process which accepts command arguments. Pipes are established between the parent application and the child process for stdin, stdout, and stderr. It is an efficient way to execute commands as it does not create a shell to execute the commands (not true for Windows, you must set shell option to true).

The child_process.stdout and child_process.stderr events captured on the child process, if no error occurs, the output from the command is transmitted to the stdout and a data event fires on the parent process. If an error occurs the error event fires and the child process exited with a code of 1, when no error occurs, the child process exits with a code of 0. The close event triggered when when child process exits.

In the following, we create a child process to call the dir command to print the directory contents.

spawn a child process in Linux OS

let {spawn} = require ('child_process'),
dir = spawn('dir');

dir.stdout.on('data', (data) => {
 console.log(data.toString());
})
dir.stderr.on('data', (data) => {
 console.log('Error: '+data);
})
dir.on('close', (code) => {
 console.log('Process exit code: '+code);
})

spawn a child process in Windows OS

We’ll receive the ENOENT error when try to spawn commands in Windows. To prevent this error you must set the shell option to true, see following code:

let {spawn} = require ('child_process'),
dir = spawn('dir',[],{shell:true});

dir.stdout.on('data', (data) => {
 console.log(data.toString());
})
dir.stderr.on('data', (data) => {
 console.log('Error: '+data);
})
dir.on('close', (code) => {
 console.log('Process exit code: '+code);
})

spawn a cross platform child process

const {spawn} = require('child_process'),
{platform} = require('os'),
osType = platform();

let command = 'ls',
       args = [],
    options = {};

if (osType == 'win32') {
 command = 'dir';
 options.shell = true;
}

dir = spawn(command,args,options);

dir.stdout.on('data', (data) => {
 console.log(data.toString());
})
dir.stderr.on('data', (data) => {
 console.log('Error: '+data);
})
dir.on('close', (code) => {
 console.log('Process exit code: '+code);
})

exec

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

It is useful for when you want to invoke a command, and you only care about the final result, not about accessing the data from a child’s stdio streams as they come.

The difference between spawn and exec is that the spawn method will return all the data as a stream, whereas the exec method returns data as a buffer.

//child_process.exec(command[, options][, callback])
const {exec} = require ('child_process');
let command = 'dir',
options = {encoding:'utf8'};

//exec(command,(err,stdout,stderr)=>{
exec(command,options,(err,stdout,stderr)=>{
 if (err){
  console.log(err);
  console.log(stderr);
 } else {
  console.log(stdout);
 }
});

Above code also can written as follows:

const {exec} = require ('child_process');
let command = 'dir',
options = {encoding:'utf8'},

dir = exec(command,options);
//dir = exec(command);

dir.stdout.on('data', (data) => {
 console.log(data);
})
dir.stderr.on('data', (data) => {
 console.log('Error: '+data);
})
dir.on('close', (code) => {
 console.log('Process exit code: '+code);
})

execFile

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

Use execFile if you want to execute a file without using a shell (apart from Windows where some files, such as .bat and .cmd, cannot be executed). The difference is that exec spawns a shell, whereas the execFile function does not.

For Linux based platforms, create a file, file.sh, and write the following code and save it:

#!/bin/sh
echo "Hello world"

Now execute this file using execFile method:

const {execFile} = require('child_process');

let file = 'file.sh',
args = [],
options = {};

execFile(file,args,options,(err,stdout,stderr)=>{
 if (err){
  console.log(err);
  console.log(stderr);
 } else {
  console.log(stdout);
 }
});

How to use execFile in Windows

On Windows bat and cmd files are not executable on their own without a terminal i.e. cmd, and therefore cannot be launched using child_process.execFile.

Instead of execFile we can use spawn and exec methods to run batch files on Windows os.

Create a file.bat file and write the following code and save:

echo Showing content of this dir
dir

Executing a bat file using Node `child_process.spawn()`

let {spawn} = require ('child_process'),
file = 'file.bat',
fileExec = spawn(file,[],{shell:true});

fileExec.stdout.on('data', (data) => {
 console.log(data.toString());
})
fileExec.stderr.on('data', (data) => {
 console.log('Error: '+data);
})
fileExec.on('close', (code) => {
 console.log('Process exit code: '+code);
})

Executing a bat file using Node `child_process.exec()`

let {exec} = require ('child_process'),
file = 'file.bat',
fileExec = exec(file);

fileExec.stdout.on('data', (data) => {
 console.log(data.toString());
})
fileExec.stderr.on('data', (data) => {
 console.log('Error: '+data);
})
fileExec.on('close', (code) => {
 console.log('Process exit code: '+code);
})

fork

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

It is a special way to create child processes of Node itself, with a special IPC channel built in, called fork. It is a variation of spawn, the difference is that it invokes a specified Node module/file with an established communication channel that allows messages to be passed back and forth between parent and child.

One use of child_process.fork() is to spin off functionality to completely separate Node instances. In next tutorial we’ll use fork to communicate with our File Walker module to improve performance by integrating it as a second Node instance.

The first argument passed to fork is a path to a Node module to execute. Like spawnthe fork returns a ChildProcess object, the major difference is IPC channel:

the child process has a child.send(message) function
and the script being invoked by fork can listen for process on('message') events.

Lets create parent.js:

//parent.js
const cp = require('child_process');
let child = cp.fork('./child.js');

child.on('message', (message) =>{
 console.log('Parent got message: '+message);
 //this script got a message from child.js
});

child.send('Parent sent a message to child.js');
//send a message to child.js

Now create the child.js file:

//child.js

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

//send a message back to parent
process.send('A message from child.js');

Now execute the parent.js:

D:\>node parent
Parent got message: A message from child.js
Parent sent a message to child.js

In the next lesson, I will tell you how we will use child_process.fork() in our Duplicate File Finder application so that our application’s GUI is not blocked and we can easily pause and resume the application without blocking event loop.

by updated Sep 13, 2018

Источник

Node.js Child Processes: Everything you need to know

By Samer Buna

How to use spawn(), exec(), execFile(), and fork()

Update: This article is now part of my book “Node.js Beyond The Basics”.

Read the updated version of this content and more about Node at jscomplete.com/node-beyond-basics.

Single-threaded, non-blocking performance in Node.js works great for a single process. But eventually, one process in one CPU is not going to be enough to handle the increasing workload of your application.

No matter how powerful your server may be, a single thread can only support a limited load.

The fact that Node.js runs in a single thread does not mean that we can’t take advantage of multiple processes and, of course, multiple machines as well.

Using multiple processes is the best way to scale a Node application. Node.js is designed for building distributed applications with many nodes. This is why it’s named Node. Scalability is baked into the platform and it’s not something you start thinking about later in the lifetime of an application.

This article is a write-up of part of my Pluralsight course about Node.js. I cover similar content in video format there.

Please note that you’ll need a good understanding of Node.js events and streams before you read this article. If you haven’t already, I recommend that you read these two other articles before you read this one:

Understanding Node.js Event-Driven Architecture
Most of Node’s objects — like HTTP requests, responses, and streams — implement the EventEmitter module so they can…

Streams: Everything you need to know
Node.js streams have a reputation for being hard to work with, and even harder to understand. Well I’ve got good news…

The Child Processes Module

We can easily spin a child process using Node’s child_process module and those child processes can easily communicate with each other with a messaging system.

The child_process module enables us to access Operating System functionalities by running any system command inside a, well, child process.

We can control that child process input stream, and listen to its output stream. We can also control the arguments to be passed to the underlying OS command, and we can do whatever we want with that command’s output. We can, for example, pipe the output of one command as the input to another (just like we do in Linux) as all inputs and outputs of these commands can be presented to us using Node.js streams.

Note that examples I’ll be using in this article are all Linux-based. On Windows, you need to switch the commands I use with their Windows alternatives.

There are four different ways to create a child process in Node: spawn(), fork(), exec(), and execFile().

We’re going to see the differences between these four functions and when to use each.

Spawned Child Processes

The spawn function launches a command in a new process and we can use it to pass that command any arguments. For example, here’s code to spawn a new process that will execute the pwd command.

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

const child = spawn('pwd');

We simply destructure the spawn function out of the child_process module and execute it with the OS command as the first argument.

The result of executing the spawn function (the child object above) is a ChildProcess instance, which implements the EventEmitter API. This means we can register handlers for events on this child object directly. For example, we can do something when the child process exits by registering a handler for the exit event:

child.on('exit', function (code, signal) {
  console.log('child process exited with ' +
              `code ${code} and signal ${signal}`);
});

The handler above gives us the exit code for the child process and the signal, if any, that was used to terminate the child process. This signal variable is null when the child process exits normally.

The other events that we can register handlers for with the ChildProcess instances are disconnect, error, close, and message.

The disconnect event is emitted when the parent process manually calls the child.disconnect function.
The error event is emitted if the process could not be spawned or killed.
The close event is emitted when the stdio streams of a child process get closed.
The message event is the most important one. It’s emitted when the child process uses the process.send() function to send messages. This is how parent/child processes can communicate with each other. We’ll see an example of this below.

Every child process also gets the three standard stdio streams, which we can access using child.stdin, child.stdout, and child.stderr.

When those streams get closed, the child process that was using them will emit the close event. This close event is different than the exit event because multiple child processes might share the same stdio streams and so one child process exiting does not mean that the streams got closed.

Since all streams are event emitters, we can listen to different events on those stdio streams that are attached to every child process. Unlike in a normal process though, in a child process, the stdout/stderr streams are readable streams while the stdin stream is a writable one. This is basically the inverse of those types as found in a main process. The events we can use for those streams are the standard ones. Most importantly, on the readable streams, we can listen to the data event, which will have the output of the command or any error encountered while executing the command:

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

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

The two handlers above will log both cases to the main process stdout and stderr. When we execute the spawn function above, the output of the pwd command gets printed and the child process exits with code 0, which means no error occurred.

We can pass arguments to the command that’s executed by the spawn function using the second argument of the spawn function, which is an array of all the arguments to be passed to the command. For example, to execute the find command on the current directory with a -type f argument (to list files only), we can do:

const child = spawn('find', ['.', '-type', 'f']);

If an error occurs during the execution of the command, for example, if we give find an invalid destination above, the child.stderr data event handler will be triggered and the exit event handler will report an exit code of 1, which signifies that an error has occurred. The error values actually depend on the host OS and the type of error.

A child process stdin is a writable stream. We can use it to send a command some input. Just like any writable stream, the easiest way to consume it is using the pipe function. We simply pipe a readable stream into a writable stream. Since the main process stdin is a readable stream, we can pipe that into a child process stdin stream. For example:

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

const child = spawn('wc');

process.stdin.pipe(child.stdin)

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

In the example above, the child process invokes the wc command, which counts lines, words, and characters in Linux. We then pipe the main process stdin (which is a readable stream) into the child process stdin (which is a writable stream). The result of this combination is that we get a standard input mode where we can type something and when we hit Ctrl+D, what we typed will be used as the input of the wc command.

Gif captured from my Pluralsight course — Advanced Node.js

We can also pipe the standard input/output of multiple processes on each other, just like we can do with Linux commands. For example, we can pipe the stdout of the find command to the stdin of the wc command to count all the files in the current directory:

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

const find = spawn('find', ['.', '-type', 'f']);
const wc = spawn('wc', ['-l']);

find.stdout.pipe(wc.stdin);

wc.stdout.on('data', (data) => {
  console.log(`Number of files ${data}`);
});

I added the -l argument to the wc command to make it count only the lines. When executed, the code above will output a count of all files in all directories under the current one.

Shell Syntax and the exec function

By default, the spawn function does not create a shell to execute the command we pass into it. This makes it slightly more efficient than the exec function, which does create a shell. The exec function has one other major difference. It buffers the command’s generated output and passes the whole output value to a callback function (instead of using streams, which is what spawn does).

Here’s the previous find | wc example implemented with an exec function.

const { exec } = require('child_process');

exec('find . -type f | wc -l', (err, stdout, stderr) => {
  if (err) {
    console.error(`exec error: ${err}`);
    return;
  }

  console.log(`Number of files ${stdout}`);
});

Since the exec function uses a shell to execute the command, we can use the shell syntax directly here making use of the shell pipe feature.

Note that using the shell syntax comes at a security risk if you’re executing any kind of dynamic input provided externally. A user can simply do a command injection attack using shell syntax characters like ; and $ (for example, command + ’; rm -rf ~’ )

The exec function buffers the output and passes it to the callback function (the second argument to exec) as the stdout argument there. This stdout argument is the command’s output that we want to print out.

The exec function is a good choice if you need to use the shell syntax and if the size of the data expected from the command is small. (Remember, exec will buffer the whole data in memory before returning it.)

The spawn function is a much better choice when the size of the data expected from the command is large, because that data will be streamed with the standard IO objects.

We can make the spawned child process inherit the standard IO objects of its parents if we want to, but also, more importantly, we can make the spawn function use the shell syntax as well. Here’s the same find | wc command implemented with the spawn function:

const child = spawn('find . -type f | wc -l', {
  stdio: 'inherit',
  shell: true
});

Because of the stdio: 'inherit' option above, when we execute the code, the child process inherits the main process stdin, stdout, and stderr. This causes the child process data events handlers to be triggered on the main process.stdout stream, making the script output the result right away.

Because of the shell: true option above, we were able to use the shell syntax in the passed command, just like we did with exec. But with this code, we still get the advantage of the streaming of data that the spawn function gives us. This is really the best of both worlds.

There are a few other good options we can use in the last argument to the child_process functions besides shell and stdio. We can, for example, use the cwd option to change the working directory of the script. For example, here’s the same count-all-files example done with a spawn function using a shell and with a working directory set to my Downloads folder. The cwd option here will make the script count all files I have in ~/Downloads:

const child = spawn('find . -type f | wc -l', {
  stdio: 'inherit',
  shell: true,
  cwd: '/Users/samer/Downloads'
});

Another option we can use is the env option to specify the environment variables that will be visible to the new child process. The default for this option is process.env which gives any command access to the current process environment. If we want to override that behavior, we can simply pass an empty object as the env option or new values there to be considered as the only environment variables:

const child = spawn('echo $ANSWER', {
  stdio: 'inherit',
  shell: true,
  env: { ANSWER: 42 },
});

The echo command above does not have access to the parent process’s environment variables. It can’t, for example, access $HOME, but it can access $ANSWER because it was passed as a custom environment variable through the env option.

One last important child process option to explain here is the detached option, which makes the child process run independently of its parent process.

Assuming we have a file timer.js that keeps the event loop busy:

setTimeout(() => {  
  // keep the event loop busy
}, 20000);

We can execute it in the background using the detached option:

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

const child = spawn('node', ['timer.js'], {
  detached: true,
  stdio: 'ignore'
});

child.unref();

The exact behavior of detached child processes depends on the OS. On Windows, the detached child process will have its own console window while on Linux the detached child process will be made the leader of a new process group and session.

If the unref function is called on the detached process, the parent process can exit independently of the child. This can be useful if the child is executing a long-running process, but to keep it running in the background the child’s stdio configurations also have to be independent of the parent.

The example above will run a node script (timer.js) in the background by detaching and also ignoring its parent stdio file descriptors so that the parent can terminate while the child keeps running in the background.

Gif captured from my Pluralsight course — Advanced Node.js

The execFile function

If you need to execute a file without using a shell, the execFile function is what you need. It behaves exactly like the exec function, but does not use a shell, which makes it a bit more efficient. On Windows, some files cannot be executed on their own, like .bat or .cmd files. Those files cannot be executed with execFile and either exec or spawn with shell set to true is required to execute them.

The *Sync function

The functions spawn, exec, and execFile from the child_process module also have synchronous blocking versions that will wait until the child process exits.

const { 
  spawnSync, 
  execSync, 
  execFileSync,
} = require('child_process');

Those synchronous versions are potentially useful when trying to simplify scripting tasks or any startup processing tasks, but they should be avoided otherwise.

The fork() function

The fork function is a variation of the spawn function for spawning node processes. The biggest difference between spawn and fork is that a communication channel is established to the child process when using fork, so we can use the send function on the forked process along with the global process object itself to exchange messages between the parent and forked processes. We do this through the EventEmitter module interface. Here’s an example:

The parent file, parent.js:

const { fork } = require('child_process');

const forked = fork('child.js');

forked.on('message', (msg) => {
  console.log('Message from child', msg);
});

forked.send({ hello: 'world' });

The child file, child.js:

process.on('message', (msg) => {
  console.log('Message from parent:', msg);
});

let counter = 0;

setInterval(() => {
  process.send({ counter: counter++ });
}, 1000);

In the parent file above, we fork child.js (which will execute the file with the node command) and then we listen for the message event. The message event will be emitted whenever the child uses process.send, which we’re doing every second.

To pass down messages from the parent to the child, we can execute the send function on the forked object itself, and then, in the child script, we can listen to the message event on the global process object.

When executing the parent.js file above, it’ll first send down the { hello: 'world' } object to be printed by the forked child process and then the forked child process will send an incremented counter value every second to be printed by the parent process.

Screenshot captured from my Pluralsight course — Advanced Node.js

Let’s do a more practical example about the fork function.

Let’s say we have an http server that handles two endpoints. One of these endpoints (/compute below) is computationally expensive and will take a few seconds to complete. We can use a long for loop to simulate that:

const http = require('http');

const longComputation = () => {
  let sum = 0;
  for (let i = 0; i < 1e9; i++) {
    sum += i;
  };
  return sum;
};

const server = http.createServer();

server.on('request', (req, res) => {
  if (req.url === '/compute') {
    const sum = longComputation();
    return res.end(`Sum is ${sum}`);
  } else {
    res.end('Ok')
  }
});

server.listen(3000);

This program has a big problem; when the the /compute endpoint is requested, the server will not be able to handle any other requests because the event loop is busy with the long for loop operation.

There are a few ways with which we can solve this problem depending on the nature of the long operation but one solution that works for all operations is to just move the computational operation into another process using fork.

We first move the whole longComputation function into its own file and make it invoke that function when instructed via a message from the main process:

In a new compute.js file:

const longComputation = () => {
  let sum = 0;
  for (let i = 0; i < 1e9; i++) {
    sum += i;
  };
  return sum;
};

process.on('message', (msg) => {
  const sum = longComputation();
  process.send(sum);
});

Now, instead of doing the long operation in the main process event loop, we can fork the compute.js file and use the messages interface to communicate messages between the server and the forked process.

const http = require('http');
const { fork } = require('child_process');

const server = http.createServer();

server.on('request', (req, res) => {
  if (req.url === '/compute') {
    const compute = fork('compute.js');
    compute.send('start');
    compute.on('message', sum => {
      res.end(`Sum is ${sum}`);
    });
  } else {
    res.end('Ok')
  }
});

server.listen(3000);

When a request to /compute happens now with the above code, we simply send a message to the forked process to start executing the long operation. The main process’s event loop will not be blocked.

Once the forked process is done with that long operation, it can send its result back to the parent process using process.send.

In the parent process, we listen to the message event on the forked child process itself. When we get that event, we’ll have a sum value ready for us to send to the requesting user over http.

The code above is, of course, limited by the number of processes we can fork, but when we execute it and request the long computation endpoint over http, the main server is not blocked at all and can take further requests.

Node’s cluster module, which is the topic of my next article, is based on this idea of child process forking and load balancing the requests among the many forks that we can create on any system.

That’s all I have for this topic. Thanks for reading! Until next time!

Learning React or Node? Checkout my books:

Learn React.js by Building Games
Node.js Beyond the Basics

Learn to code for free. freeCodeCamp’s open source curriculum has helped more than 40,000 people get jobs as developers. Get started

Источник

Пройдите тест, узнайте какой профессии подходите

Работать самостоятельно и не зависеть от других

Работать в команде и рассчитывать на помощь коллег

Организовывать и контролировать процесс работы

Быстрый ответ

Чтобы запустить исполняемый файл из командной строки в Node.js, вам понадобится модуль child_process. Если речь идёт о задачах, ресурсоёмкость которых высока, spawn станет наилучшим выбором. В тех случаях, когда результат должен быть доступен непосредственно, используйте exec:

Просто замените 'имя-вашего-исполняемого-файла' на имя файла, который вы собираетесь запустить.

Кинга Идем в IT: пошаговый план для смены профессии

Принципы выбора метода запуска

Асинхронное выполнение с использованием Promises

С целью упрощения обработки ошибок и управления множеством асинхронных операций, функции с callback в Node.js можно превратить в promises с помощью util.promisify.

Непосредственный запуск файлов с помощью `execFile`

Запуск исполняемых файлов при помощи execFile происходит непосредственно, что более безопасно, т.к. не создается дополнительно оболочка shell.

Задайте и замените 'путь/к/вашему-исполняемому-файлу' на реальный путь и определите аргументы командной строки в виде массива.

Управление потоками данных и ошибками

Получение потока данных с помощью `spawn`

Для работы с процессами, которые выдают большой или непрерывный поток данных, используйте child_process.spawn. Он предоставляет потоки данных для считывания и записи данных.

Синхронное выполнение и его последствия

При использовании execSync и spawnSync результат получается непосредственно, но это может негативно сказаться на цикле обработки событий в Node.js.

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

Забота о совместимости

Совместимость операционной среды

В различных операционных системах исполняемые файлы командной строки могут вести себя по-разному. Проведите детальное тестирование, чтобы избежать неожиданностей.

Корректность синтаксиса команд

Команды для исполняемых файлов должны быть корректно оформлены для оболочки, с которой вы работаете. Учитывайте контекст.

Визуализация

Node.js может рассматриваться как дирижёр оркестра двоичных файлов:

В данной аналогии каждый «инструмент» представляет собой исполняемый файл, которым управляет Node.js:

Каждый бинарный файл вносит свою ноту в общую симфонию результатов.

Работа с потоками и циклами

Обновление языковых возможностей

Node.js постоянно развивается, важно отслеживать изменения, чтобы быть в курсе обновлений модуля child_process и других ключевых API.

Надёжные источники для работы

Для глубокого понимания всех методов модуля child_process обращайтесь к официальной документации Node.js.

Особое внимание к деталям

Сложные сценарии

Модуль child_process предоставляет разнообразные настройки для управления сложными задачами, связанными с запуском процессов.

Обработка ошибок и кодов завершения

Следите за ошибками и кодами завершения процессов, чтобы корректно реагировать на возникающие проблемы.

Полезные материалы

Дочерние процессы в Node.js: Всё, что вам нужно знать.
Дочерний процесс | Документация Node.js v21.6.1.
Выполнение команд оболочки с Node.js.
Понимание execFile, spawn, exec и fork в Node.js – DZone.
Необработанные отказы выполнения обещаний в Node.js | www.thecodebarbarian.com.

Источник

Asynchronous process creation#

Spawning .bat and .cmd files on 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#

Synchronous process creation#

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

child_process.execSync(command[, options])#

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

Class: ChildProcess#

Event: 'close'#

Event: 'disconnect'#

Event: 'error'#

Event: 'exit'#

Event: 'message'#

Event: '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])#

Example: sending a server object#

Example: sending a socket object#

subprocess.signalCode#

subprocess.spawnargs#

subprocess.spawnfile#

subprocess.stderr#

subprocess.stdin#

subprocess.stdio#

subprocess.stdout#

subprocess.unref()#

maxBuffer and Unicode#

Shell requirements#

Default Windows shell#

Advanced serialization#

Дочерний процесс¶

Асинхронное создание процессов¶

Порождение файлов .bat и .cmd в 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¶

Синхронное создание процессов¶

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

child_process.execSync(command[, options])¶

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

Класс: ChildProcess¶

Событие: 'close'¶

Событие: disconnect¶

Событие: error¶

Событие: exit¶

Событие: message¶

Событие: spawn¶

subprocess.channel¶

subprocess.channel.ref()¶

subprocess.channel.unref()¶

subprocess.connected¶

subprocess.disconnect()¶

subprocess.exitCode¶

subprocess.kill([signal])¶

subprocess.killed¶

subprocess.pid¶

subprocess.ref()¶

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

Пример: передача объекта сервера¶

Пример: отправка объекта сокета¶

subprocess.signalCode¶

subprocess.spawnargs¶

Spawning `.bat` and `.cmd` files on 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`#

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

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

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

Class: `ChildProcess`#

Event: `'close'`#

Event: `'disconnect'`#

Event: `'error'`#

Event: `'exit'`#

Event: `'message'`#

Event: `'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])`#

`subprocess.signalCode`#

`subprocess.spawnargs`#

`subprocess.spawnfile`#

`subprocess.stderr`#

`subprocess.stdin`#

`subprocess.stdio`#

`subprocess.stdout`#

`subprocess.unref()`#

`maxBuffer` and Unicode#

Порождение файлов `.bat` и `.cmd` в 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`¶

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

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

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

Класс: `ChildProcess`¶

Событие: `'close'`¶

Событие: `disconnect`¶

Событие: `error`¶

Событие: `exit`¶

Событие: `message`¶

Событие: `spawn`¶

`subprocess.channel`¶

`subprocess.channel.ref()`¶

`subprocess.channel.unref()`¶

`subprocess.connected`¶

`subprocess.disconnect()`¶

`subprocess.exitCode`¶

`subprocess.kill([signal])`¶

`subprocess.killed`¶

`subprocess.pid`¶

`subprocess.ref()`¶

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

`subprocess.signalCode`¶

`subprocess.spawnargs`¶

`subprocess.spawnfile`¶

`subprocess.stderr`¶

`subprocess.stdin`¶

`subprocess.stdio`¶

`subprocess.stdout`¶

`subprocess.unref()`¶

`maxBuffer` и Юникод¶

Executing a bat file using Node `child_process.spawn()`

Executing a bat file using Node `child_process.exec()`

Непосредственный запуск файлов с помощью `execFile`

Получение потока данных с помощью `spawn`