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

版本历史

版本	变更
v8.8.0	The `windowsHide` option is supported now.
v0.1.91	新增于: v0.1.91

file <string> 要运行的可执行文件的名称或路径。
args <string[]> 字符串参数的列表。
options <Object>
- cwd <string> 子进程的当前工作目录。
- 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，则在 shell 中运行 command。在 Unix 上使用 '/bin/sh'，在 Windows 上使用 process.env.ComSpec。可以将不同的 shell 指定为字符串。参阅 shell 的要求与 Windows 默认的 shell。 默认值: false（没有 shell）。
callback <Function> 当进程终止时调用并带上输出。
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
返回: <ChildProcess>

child_process.execFile() 函数类似于 child_process.exec()，但默认情况下不会衍生 shell。相反，指定的可执行文件 file 会作为新进程直接地衍生，使其比 child_process.exec() 稍微更高效。

支持与 child_process.exec() 相同的选项。由于没有衍生 shell，因此不支持 I/O 重定向和文件通配等行为。

const { execFile } = require('child_process');
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
  if (error) {
    throw error;
  }
  console.log(stdout);
});

传给回调的 stdout 和 stderr 参数将会包含子进程的 stdout 和 stderr 输出。默认情况下，Node.js 会将输出解码为 UTF-8 并将字符串传给回调。 encoding 选项可用于指定用于解码 stdout 和 stderr 输出的字符编码。如果 encoding 是 'buffer' 或无法识别的字符编码，则传给回调的将会是 Buffer 对象。

如果调用此方法的 util.promisify() 版本，则返回的 Promise 会返回具有 stdout 属性和 stderr 属性的 Object。返回的 ChildProcess 实例会作为 child 属性附加到该 Promise。如果出现错误（包括导致退出码不是 0 的任何错误），则返回被拒绝的 Promise，并带上与回调中相同的 error 对象，但是还有两个另外的属性 stdout 和 stderr。

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

如果启用了 shell 选项，则不要将未经过处理的用户输入传给此函数。包含 shell 元字符的任何输入都可用于触发任意命令的执行。

History

Version	Changes
v8.8.0	The `windowsHide` option is supported now.
v0.1.91	Added in: v0.1.91

file <string> The name or path of the executable file to run.
args <string[]> List of string arguments.
options <Object>
- cwd <string> 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).
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('child_process');
const child = execFile('node', ['--version'], (error, stdout, stderr) => {
  if (error) {
    throw error;
  }
  console.log(stdout);
});

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.

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('util');
const execFile = util.promisify(require('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.