模組child_process

子行程管理模組

引用方式：

1
2
var child_process = require("child_process");
var child = child_process.spawn("ls");

在建立子進程時，options.stdio 選項用於配置在父進程和子進程之間建立的管道。預設情況下，子程序的stdin、 stdout 和stderr 會被重新導向到ChildProcess物件上對應的stdin、stdout 和stderr 流。這相當於將options.stdio 設定為['pipe', 'pipe', 'pipe']。

為方便起見， options.stdio 可以是以下字串之一：

'pipe'：相當於['pipe', 'pipe', 'pipe']（預設值）。
'ignore'：相當於['ignore', 'ignore', 'ignore']。
'inherit'：相當於['inherit', 'inherit', 'inherit'] 或[0, 1, 2]。
'pty'：相當於['pty', 'pty', 'pty']。不支援Windows。

否則， options.stdio 的值需是陣列（其中每個索引對應於子進程中的檔案描述子）。檔案描述符0、1 和2 分別對應於stdin、stdout 和stderr。其他的檔案描述符可以被指定用於在父進程和子進程之間建立其他的管道。值可以是以下之一：

'pipe'：在子進程和父進程之間建立管道。管道的父端作為child_process 物件上的stdio[fd] 屬性暴露給父進程。為檔案描述子0、1 和2 所建立的管道也可分別作為stdin、stdout 和stderr 使用。
'ignore'：指示fibjs 忽略子程序中的檔案描述子。雖然fibjs 將會始終為其衍生的進程開啟檔案描述符0、1 和2，但將檔案描述符設為'ignore' 可以使fibjs 開啟/dev/null 並將其附加到子進程的檔案描述符。
'inherit'：將對應的stdio 流傳給父進程或從父進程傳入。在前三個位置中，這分別相當於process.stdin、process.stdout和process.stderr。在任何其他位置中，則相當於'ignore'。
'pty'：在子進程將在虛擬終端中執行。此時只有stdin 和stdout 有效。
正整數：整數值會被解釋為目前在父行程中開啟的檔案描述子。它與子進程共享，類似於共享<Stream> 物件的方式。在Windows 上不支援傳入socket。
null 或undefined：使用預設值。對於stdio 的檔案描述子0、1 和2（換句話說，stdin、stdout 和stderr），將會建立管道。對於文件描述符3 及更大的值，則預設為'ignore'。

1
2
3
4
5
6
7
8
9
10
11
12
13
const {
    spawn
} = require('child_process');

// child process uses parent's stdio
spawn('prg', [], {
    stdio: 'inherit'
});

// child process uses parent's stderr
spawn('prg', [], {
    stdio: ['pipe', 'pipe', process.stderr]
});

對於同時使用nodejs 的使用者, 需注意

fibjs 的child_process.exec(command, args)和nodejs 的同名api 功能類似, 但在windows 上, 並不會自動將cmd.exe 作為command 參數的執行環境;
fibjs 的child_process.[spawn|exec|execFile|run] 是同步/回呼一體的async 風格函數:
- 如果最後一個參數不是函數, 則是同步的
- 如果傳遞了函數作為最後一個參數, 則是異步的;
fibjs 的child_process.[exec|execFile] 的回傳結果是一個物件, 該物件和nodejs 同名api 傳回的物件完全不相同
fibjs 的child_process.run在nodejs 中沒有對應API

靜態函數

spawn

用給定的命令發布一個子進程

1
2
3
static ChildProcess child_process.spawn(String command,
    Array args,
    Object options = {});

呼叫參數:

command: String, 指定要執行的命令
args: Array, 指定字串參數列表
options: Object, 指定建立參數

回傳結果:

ChildProcess, 傳回子進程對象

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // configure the group identity of the process
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

用給定的命令發布一個子進程

1
2
static ChildProcess child_process.spawn(String command,
    Object options = {});

呼叫參數:

command: String, 指定要執行的命令
options: Object, 指定建立參數

回傳結果:

ChildProcess, 傳回子進程對象

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

exec

在shell 中執行一個命令並緩衝輸出，當以回調方式執行時，函數將返回子進程對象

1
2
static (Variant stdout, Variant stderr) child_process.exec(String command,
    Object options = {}) async;

呼叫參數:

command: String, 指定要執行的命令
options: Object, 指定建立參數

回傳結果:

(Variant stdout, Variant stderr), 傳回子程序的stdio 輸出內容

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "encoding": "utf8", // specify the character encoding used to decode the stdout and stderr output
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

execFile

直接執行所指定的檔案並緩衝輸出，當以回調方式執行時，函數將傳回子進程對象

1
2
3
static (Variant stdout, Variant stderr) child_process.execFile(String command,
    Array args,
    Object options = {}) async;

呼叫參數:

command: String, 指定要執行的命令
args: Array, 指定字串參數列表
options: Object, 指定建立參數

回傳結果:

(Variant stdout, Variant stderr), 傳回子程序的stdio 輸出內容

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "encoding": "utf8", // specify the character encoding used to decode the stdout and stderr output
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

直接執行所指定的檔案並緩衝輸出，當以回調方式執行時，函數將傳回子進程對象

1
2
static (Variant stdout, Variant stderr) child_process.execFile(String command,
    Object options = {}) async;

呼叫參數:

command: String, 指定要執行的命令
options: Object, 指定建立參數

回傳結果:

(Variant stdout, Variant stderr), 傳回子程序的stdio 輸出內容

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "encoding": "utf8", // specify the character encoding used to decode the stdout and stderr output
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

spawnSync

用給定的命令發布一個子進程

1
2
3
static (Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error) child_process.spawnSync(String command,
    Array args,
    Object options = {}) async;

呼叫參數:

command: String, 指定要執行的命令
args: Array, 指定字串參數列表
options: Object, 指定建立參數

回傳結果:

(Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error), 返回子進程運行結果

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // configure the group identity of the process
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

用給定的命令發布一個子進程

1
2
static (Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error) child_process.spawnSync(String command,
    Object options = {}) async;

呼叫參數:

command: String, 指定要執行的命令
options: Object, 指定建立參數

回傳結果:

(Integer pid, NArray output, Variant stdout, Variant stderr, Integer status, Variant error), 返回子進程運行結果

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

fork

在子進程中執行一個模組

1
2
3
static ChildProcess child_process.fork(String module,
    Array args,
    Object options = {});

呼叫參數:

module: String, 指定要執行的命令
args: Array, 指定字串參數列表
options: Object, 指定建立參數

回傳結果:

ChildProcess, 傳回子進程對象

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

在子進程中執行一個模組

1
2
static ChildProcess child_process.fork(String module,
    Object options = {});

呼叫參數:

module: String, 指定要執行的命令
options: Object, 指定建立參數

回傳結果:

ChildProcess, 傳回子進程對象

options 支援的內容如下：

1
2
3
4
5
6
7
8
9
10{
    "cwd": "", // working directory of the child process, default to current directory
    "stdio": Array | String, // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

run

直接執行所指定的檔案並傳回exitCode，當以回調方式執行時，函數將傳回子進程對象

1
2
3
static Integer child_process.run(String command,
    Array args,
    Object options = {}) async;

呼叫參數:

command: String, 指定要執行的命令
args: Array, 指定字串參數列表
options: Object, 指定建立參數

回傳結果:

Integer, 傳回子進程的exitCode

options 支援的內容如下：

1
2
3
4
5
6
7
8
9{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

直接執行所指定的檔案並傳回exitCode，當以回調方式執行時，函數將傳回子進程對象

1
2
static Integer child_process.run(String command,
    Object options = {}) async;

呼叫參數:

command: String, 指定要執行的命令
options: Object, 指定建立參數

回傳結果:

Integer, 傳回子進程的exitCode

options 支援的內容如下：

1
2
3
4
5
6
7
8
9{
    "cwd": "", // working directory of the child process, default to current directory
    "env": {}, // key-value pairs of environment variables to add to the child's environment
    "detached": false, // child process will be a leader of a new process group, default to false
    "uid": 0, // configure the user identity of the process
    "gid": 0, // con
    "windowsVerbatimArguments": false, // do not execute any quote or escape processing on Windows. Ignored on Unix. When specified, the command line string is passed directly to the underlying operating system shell without any processing whatsoever. This is set to true automatically when the shell option is specified and is CMD.
    "windowsHide": false // hide the subprocess console window that would normally be created on Windows systems. This option has no effect on non-Windows systems.
}

開發指南

基礎模組

內建對象

社群模組

模組child_process

靜態函數

spawn

exec

execFile

spawnSync

fork

run