Node.js v14.20.0 文档


目录

child_process 子进程#

中英对照

child_process 模块提供了以与 popen(3) 类似但不完全相同的方式衍生子进程的能力。 此功能主要由 child_process.spawn() 函数提供:


    异步进程的创建#

    中英对照

    child_process.spawn()child_process.fork()child_process.exec()child_process.execFile() 方法都遵循其他 Node.js API 典型的惯用异步编程模式。

    在 Windows 上衍生 .bat 和 .cmd 文件#

    中英对照

    child_process.exec()child_process.execFile() 之间区别的重要性可能因平台而异。 在 Unix 类型的操作系统(Unix、Linux、macOS)上,child_process.execFile() 可以更高效,因为它默认不衍生 shell。 但是,在 Windows 上,.bat.cmd 文件在没有终端的情况下无法自行执行,因此无法使用 child_process.execFile() 启动。 在 Windows 上运行时,.bat.cmd 文件可以使用具有 shell 选项集的 child_process.spawn()、使用 child_process.exec()、或通过衍生 cmd.exe 并将 .bat.cmd 文件作为参数传入(这也是 shell 选项和 child_process.exec() 所做的)来调用。 在任何情况下,如果脚本文件名包含空格,则需要加上引号。

    
    
    
    

    child_process.exec(command[, options][, callback])#

    中英对照

      衍生 shell,然后在该 shell 中执行 command,缓冲任何生成的输出。 传给执行函数的 command 字符串由 shell 直接处理,特殊字符(因 shell 而异)需要进行相应处理:

      
      

      
      

      
      

      
      

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

      中英对照

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

        
        

        
        

        
        

        child_process.fork(modulePath[, args][, options])#

        中英对照

          child_process.fork() 方法是 child_process.spawn() 的特例,专门用于衍生新的 Node.js 进程。 与 child_process.spawn() 一样,返回 ChildProcess 对象。 返回的 ChildProcess 将有额外的内置通信通道,允许消息在父进程和子进程之间来回传递。 详见 subprocess.send()

          
          

          child_process.spawn(command[, args][, options])#

          中英对照

            child_process.spawn() 方法使用给定的 commandargs 中的命令行参数衍生新进程。 如果省略,args 默认为空数组。

            
            

            
            

            
            

            
            

            
            
            options.detached#

            中英对照

            在 Windows 上,将 options.detached 设置为 true 可以让子进程在父进程退出后继续运行。 子进程将有自己的控制台窗口。 一旦为子进程启用,则它就不能被禁用。

            
            

            
            
            options.stdio#

            中英对照

            options.stdio 选项用于配置在父进程和子进程之间建立的管道。 默认情况下,子进程的标准输入、标准输出和标准错误被重定向到 ChildProcess 对象上相应的 subprocess.stdinsubprocess.stdoutsubprocess.stderr 流。 这相当于将 options.stdio 设置为等于 ['pipe', 'pipe', 'pipe']

                
                

                同步进程的创建#

                中英对照

                child_process.spawnSync()child_process.execSync()child_process.execFileSync() 方法是同步的,将阻塞 Node.js 事件循环,暂停任何其他代码的执行,直到衍生的进程退出。

                child_process.execFileSync(file[, args][, options])#

                中英对照

                  child_process.execFileSync() 方法通常与 child_process.execFile() 相同,不同之处在于该方法在子进程完全关闭之前不会返回。 当遇到超时并发送 killSignal 时,该方法在进程完全退出之前不会返回。

                  child_process.execSync(command[, options])#

                  中英对照

                    child_process.execSync() 方法通常与 child_process.exec() 相同,不同之处在于该方法在子进程完全关闭之前不会返回。 当遇到超时并发送 killSignal 时,该方法在进程完全退出之前不会返回。 如果子进程拦截并处理了 SIGTERM 信号且没有退出,则父进程会一直等到子进程退出。

                    child_process.spawnSync(command[, args][, options])#

                    中英对照

                      child_process.spawnSync() 方法通常与 child_process.spawn() 相同,不同之处在于该函数在子进程完全关闭之前不会返回。 当遇到超时并发送 killSignal 时,该方法在进程完全退出之前不会返回。 如果进程拦截并处理了 SIGTERM 信号并且没有退出,则父进程会一直等到子进程退出。

                      ChildProcess#

                      中英对照

                        ChildProcess 的实例,表示衍生的子进程。

                        'close' 事件#

                        中英对照

                          在进程已结束并且子进程的标准输入输出流已关闭之后,则触发 'close' 事件。 这与 'exit' 事件不同,因为多个进程可能共享相同的标准输入输出流。 'close' 事件将始终在 'exit''error'(如果子进程衍生失败)已经触发之后触发。

                          
                          

                          'disconnect' 事件#

                          中英对照

                          调用父进程中的 subprocess.disconnect() 方法或子进程中的 process.disconnect() 方法后会触发 'disconnect' 事件。 断开连接后就不能再发送或接收消息,且 subprocess.connected 属性为 false

                          'error' 事件#

                          中英对照

                            'error' 事件在以下情况下触发:

                              'exit' 事件#

                              中英对照

                                'exit' 事件在子进程结束后触发。 如果进程退出,则 code 为最终的进程退出码,否则为 null。 如果进程因收到信号而终止,则 signal 是信号的字符串名称,否则为 null。 两者之一将始终是非 null

                                'message' 事件#

                                中英对照

                                  当子进程使用 process.send() 发送消息时,则触发 'message' 事件。

                                  'spawn' 事件#

                                  中英对照

                                  一旦子进程衍生成功,则会触发 'spawn' 事件。 如果子进程没有衍生成功,则不会触发 'spawn' 事件,而是触发 'error' 事件。

                                  subprocess.channel#

                                  中英对照

                                    subprocess.channel 属性是对子进程的 IPC 通道的引用。 如果当前不存在 IPC 通道,则此属性为 undefined

                                    subprocess.channel.ref()#

                                    中英对照

                                    如果之前已调用过 .unref(),则此方法使 IPC 通道保持父进程的事件循环运行。

                                    subprocess.channel.unref()#

                                    中英对照

                                    此方法使 IPC 通道不保持父进程的事件循环运行,并且即使在通道打开时也让其结束。

                                    subprocess.connected#

                                    中英对照

                                      subprocess.connected 属性指示是否仍然可以从子进程发送和接收消息。 当 subprocess.connectedfalse 时,不再可能发送或接收消息。

                                      subprocess.disconnect()#

                                      中英对照

                                      关闭父进程和子进程之间的 IPC 通道,一旦没有其他连接使其保持活动状态,则允许子进程正常退出。 调用此方法后,父子进程中的 subprocess.connectedprocess.connected 属性(分别)将设置为 false,进程之间将无法再传递消息。

                                      subprocess.exitCode#

                                      中英对照

                                        subprocess.exitCode 属性表示子进程的退出码。 如果子进程仍在运行,则该字段将为 null

                                        subprocess.kill([signal])#

                                        中英对照

                                          subprocess.kill() 方法向子进程发送信号。 如果没有给定参数,则进程将被发送 'SIGTERM' 信号。 有关可用信号的列表,请参阅 signal(7)。 如果 kill(2) 成功,则此函数返回 true,否则返回 false

                                          
                                          

                                          
                                          

                                          subprocess.killed#

                                          中英对照

                                            subprocess.killed 属性指示子进程是否成功接收到来自 subprocess.kill() 的信号。 killed 属性并不表示子进程已终止。

                                            subprocess.pid#

                                            中英对照

                                              返回子进程的进程标识符 (PID)。 如果子进程由于错误而无法衍生,则该值为 undefined 并触发 error

                                              
                                              

                                              subprocess.ref()#

                                              中英对照

                                              在调用 subprocess.unref() 后调用 subprocess.ref() 将为子进程恢复删除的引用计数,迫使父进程在退出之前等待子进程退出。

                                              
                                              

                                              subprocess.send(message[, sendHandle[, options]][, callback])#

                                              中英对照

                                                当父进程和子进程之间建立了 IPC 通道时(即当使用 child_process.fork() 时),可以使用 subprocess.send() 方法向子进程发送消息。 当子进程是 Node.js 实例时,可以通过 'message' 事件接收这些消息。

                                                
                                                

                                                
                                                

                                                示例:发送服务器对象#

                                                中英对照

                                                例如,可以使用 sendHandle 参数将 TCP 服务器对象的句柄传给子进程,如下例所示:

                                                
                                                

                                                
                                                

                                                示例:发送套接字对象#

                                                中英对照

                                                同样,sendHandler 参数可用于将套接字的句柄传给子进程。 下面的例子产生了两个子进程,每个子进程都处理具有“normal”或“special”优先级的连接:

                                                
                                                

                                                
                                                

                                                subprocess.signalCode#

                                                中英对照

                                                  subprocess.signalCode 属性表示子进程接收到的信号(如果有),否则为 null

                                                  subprocess.spawnargs#

                                                  中英对照

                                                    subprocess.spawnargs 属性表示子进程启动时使用的命令行参数的完整列表。

                                                    subprocess.spawnfile#

                                                    中英对照

                                                      subprocess.spawnfile 属性表示启动的子进程的可执行文件名。

                                                      subprocess.stderr#

                                                      中英对照

                                                        代表子进程的 stderrReadable Stream

                                                        subprocess.stdin#

                                                        中英对照

                                                          代表子进程的 stdinWritable Stream

                                                          subprocess.stdio#

                                                          中英对照

                                                            到子进程的稀疏管道数组,对应于传给 child_process.spawn()stdio 选项中的位置,这些位置已设置为值 'pipe'subprocess.stdio[0]subprocess.stdio[1]subprocess.stdio[2] 也可分别用作 subprocess.stdinsubprocess.stdoutsubprocess.stderr

                                                            
                                                            

                                                            subprocess.stdout#

                                                            中英对照

                                                              代表子进程的 stdoutReadable Stream

                                                              
                                                              

                                                              subprocess.unref()#

                                                              中英对照

                                                              默认情况下,父进程将等待分离的子进程退出。 为了防止父进程等待给定的 subprocess 退出,则使用 subprocess.unref() 方法。 这样做会使父进程的事件循环不将子进程包括在其引用计数中,从而允许父进程独立于子进程退出,除非在子进程和父进程之间建立了 IPC 通道。

                                                              
                                                              

                                                              maxBuffer 和 Unicode#

                                                              中英对照

                                                              maxBuffer 选项指定 stdoutstderr 上允许的最大字节数。 如果超过此值,则终止子进程。 这会影响包含多字节字符编码(例如 UTF-8 或 UTF-16)的输出。 例如,console.log('中文测试') 将向 stdout 发送 13 个 UTF-8 编码字节,尽管只有 4 个字符。

                                                              shell 的要求#

                                                              中英对照

                                                              shell 应该理解 -c 开关。 如果 shell 是 'cmd.exe',则应该理解 /d /s /c 开关,并且命令行解析应该是兼容的。

                                                              默认的 Windows shell#

                                                              中英对照

                                                              尽管微软指定 %COMSPEC% 必须包含根环境中到 'cmd.exe' 的路径,但子进程并不总是受到相同的要求。 因此,在可以衍生 shell 的 child_process 函数中,如果 process.env.ComSpec 不可用,则使用 'cmd.exe' 作为后备。

                                                              高级序列化#

                                                              中英对照

                                                              子进程支持 IPC 的序列化机制,该机制基于 v8 模块的序列化 API,基于 HTML 结构化克隆算法。 这通常功能更强大,支持更多内置的 JavaScript 对象类型,例如 BigIntMapSetArrayBufferTypedArrayBufferErrorRegExp 等。

                                                              返回顶部