child_process.execFile(file[, args][, options][, callback])
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> 当进程终止时调用并传入输出。- 返回: <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 的任何错误),则返回 reject 的 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 元字符的任何输入都可用于触发任意命令的执行。
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 atmaxBuffer
and Unicode. Default:1024 * 1024
.killSignal
<string> | <integer> Default:'SIGTERM'
uid
<number> Sets the user identity of the process (seesetuid(2)
).gid
<number> Sets the group identity of the process (seesetgid(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> Iftrue
, runscommand
inside of a shell. Uses'/bin/sh'
on Unix, andprocess.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.- 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.