Node.js child_process.execFile(file[, args][, options][, callback])用法及代碼示例

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 ，在 shell 內運行 command。在 Unix 上使用 '/bin/sh'，在 Windows 上使用 process.env.ComSpec。可以將不同的 shell 指定為字符串。請參閱 Shell requirements 和 Default Windows shell 。 默認： false(無 shell )。
  • signal <AbortSignal> 允許使用 AbortSignal 中止子進程。
• 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('node: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() ed 版本調用，它會為具有 stdout 和 stderr 屬性的 Object 返回 Promise。返回的ChildProcess 實例作為child 屬性附加到Promise。如果發生錯誤(包括導致退出代碼不是 0 的任何錯誤)，將返回一個被拒絕的 promise，並在回調中給出相同的 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 選項，請不要將未經處理的用戶輸入傳遞給此函數。任何包含 shell 元字符的輸入都可用於觸發任意命令執行。

如果啟用了 signal 選項，則在相應的 AbortController 上調用 .abort() 與在子進程上調用 .kill() 類似，隻是傳遞給回調的錯誤將是 AbortError ：

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