Node.js child_process.exec(command[, options][, callback])用法及代码示例

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

参数

• command <string> 要运行的命令，参数以空格分隔。
• options <Object>
  • cwd <string> | <URL> 子进程的当前工作目录。 默认： process.cwd() 。
  • env <Object> 环境键值对。 默认： process.env 。
  • encoding <string> 默认： 'utf8'
  • shell <string> Shell 用来执行命令。请参阅 Shell requirements 和 Default Windows shell 。 默认： '/bin/sh' 在 Unix 上，process.env.ComSpec 在 Windows 上。
  • signal <AbortSignal> 允许使用 AbortSignal 中止子进程。
  • timeout <number> 默认： 0
  • maxBuffer <number>stdout 或 stderr 上允许的最大数据量(以字节为单位)。如果超过，则终止子进程并截断任何输出。请参阅警告maxBuffer 和 Unicode.默认： 1024 * 1024.
  • killSignal <string> | <integer> 默认： 'SIGTERM'
  • uid <number> 设置进程的用户身份(参见 setuid(2) )。
  • gid <number> 设置进程的组标识(参见 setgid(2) )。
  • windowsHide <boolean> 隐藏通常在 Windows 系统上创建的子进程控制台窗口。 默认： false 。
• callback <Function>进程终止时使用输出调用。
  • error <Error>
  • stdout <string> | <Buffer>
  • stderr <string> | <Buffer>
• 返回： <ChildProcess>

生成一个 shell，然后在该 shell 中执行 command，缓冲任何生成的输出。传递给 exec 函数的 command 字符串由 shell 直接处理，特殊字符(根据 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.

切勿将未经处理的用户输入传递给此函数。任何包含 shell 元字符的输入都可用于触发任意命令执行。

如果提供了 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 ，如果孩子运行时间超过 timeout 毫秒，则父母将发送由 killSignal 属性标识的信号(默认为 'SIGTERM' )。

与 exec(3) POSIX 系统调用不同，child_process.exec() 不会替换现有进程，而是使用 shell 来执行命令。

如果此方法作为其 util.promisify() ed 版本调用，它会为具有 stdout 和 stderr 属性的 Object 返回 Promise。返回的ChildProcess 实例作为child 属性附加到Promise。如果发生错误(包括导致退出代码不是 0 的任何错误)，将返回一个被拒绝的 promise，并在回调中给出相同的 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 选项，则在相应的 AbortController 上调用 .abort() 与在子进程上调用 .kill() 类似，只是传递给回调的错误将是 AbortError ：

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