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

• file <string> 要运行的可执行文件的名称或路径。

  ¥file <string> The name or path of the executable file to run.

• args <string[]> 字符串参数列表。

  ¥args <string[]> List of string arguments.

• options <Object>

  • cwd <string> | <URL> 子进程的当前工作目录。

    ¥cwd <string> | <URL> Current working directory of the child process.

  • env <Object> 环境变量键值对。默认值：process.env。

    ¥env <Object> Environment key-value pairs. Default: process.env.

  • encoding <string> 默认值：'utf8'

    ¥encoding <string> Default: 'utf8'

  • timeout <number> 默认值：0

    ¥timeout <number> Default: 0

  • maxBuffer <number> 标准输出或标准错误上允许的最大数据量（以字节为单位）。如果超过，则子进程将终止并截断任何输出。请参阅 maxBuffer 和 Unicode 的警告。默认值：1024 * 1024。

    ¥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> 默认值：'SIGTERM'

    ¥killSignal <string> | <integer> Default: 'SIGTERM'

  • uid <number> 设置进程的用户身份（请参阅 setuid(2)）。

    ¥uid <number> Sets the user identity of the process (see setuid(2)).

  • gid <number> 设置进程的组标识（请参阅 setgid(2)）。

    ¥gid <number> Sets the group identity of the process (see setgid(2)).

  • windowsHide <boolean> 隐藏通常在 Windows 系统上创建的子进程控制台窗口。默认值：false。

    ¥windowsHide <boolean> Hide the subprocess console window that would normally be created on Windows systems. Default: false.

  • windowsVerbatimArguments <boolean> 在 Windows 上不为参数加上引号或转义。在 Unix 上被忽略。默认值：false。

    ¥windowsVerbatimArguments <boolean> No quoting or escaping of arguments is done on Windows. Ignored on Unix. Default: false.

  • shell <boolean> | <string> 如果是 true，则在 shell 内运行 command。在 Unix 上使用 '/bin/sh'，在 Windows 上使用 process.env.ComSpec。可以将不同的 shell 指定为字符串。参见 Shell 要求 和 默认 Windows shell。默认值：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> 允许使用 AbortSignal 中止子进程。

    ¥signal <AbortSignal> allows aborting the child process using an AbortSignal.

• callback <Function> 进程终止时使用输出调用。

  ¥callback <Function> Called with the output when process terminates.

  • error <Error>

  • stdout <string> | <Buffer>

  • stderr <string> | <Buffer>

• 返回：<ChildProcess>

  ¥Returns: <ChildProcess>

child_process.execFile() 函数与 child_process.exec() 类似，不同之处在于它默认不衍生 shell。而是，指定的可执行文件 file 直接作为新进程衍生，使其比 child_process.exec() 略有效率。

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

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

¥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);
});拷贝

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

¥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.

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

¥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 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();拷贝

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

¥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.

如果启用了 signal 选项，则在相应的 AbortController 上调用 .abort() 与在子进程上调用 .kill() 类似，只是传给回调的错误将是 AbortError：

¥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 { 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();拷贝