하위 프로세스

[Stable: 2 - Stable]

node:child_process 모듈은 popen(3)과 유사하지만 동일하지 않은 방식으로 하위 프로세스를 생성하는 기능을 제공합니다. 이 기능은 주로 child_process.spawn() 함수를 통해 제공됩니다.

CJSESM

const { spawn } = require('node:child_process')
const ls = spawn('ls', ['-lh', '/usr'])

ls.stdout.on('data', data => {
  console.log(`stdout: ${data}`)
})

ls.stderr.on('data', data => {
  console.error(`stderr: ${data}`)
})

ls.on('close', code => {
  console.log(`child process exited with code ${code}`)
})

import { spawn } from 'node:child_process'
const ls = spawn('ls', ['-lh', '/usr'])

ls.stdout.on('data', data => {
  console.log(`stdout: ${data}`)
})

ls.stderr.on('data', data => {
  console.error(`stderr: ${data}`)
})

ls.on('close', code => {
  console.log(`child process exited with code ${code}`)
})

기본적으로 stdin, stdout, stderr에 대한 파이프는 상위 Node.js 프로세스와 생성된 하위 프로세스 간에 설정됩니다. 이러한 파이프는 용량이 제한적이며(플랫폼별로 다름) 출력이 캡처되지 않으면 하위 프로세스가 파이프 버퍼가 더 많은 데이터를 수용할 때까지 대기하여 차단됩니다. 이는 셸의 파이프 동작과 동일합니다. 출력을 사용하지 않는 경우 { stdio: 'ignore' } 옵션을 사용하십시오.

options 객체에 env가 있는 경우 명령어 조회는 options.env.PATH 환경 변수를 사용하여 수행됩니다. 그렇지 않으면 process.env.PATH가 사용됩니다. options.env가 PATH 없이 설정된 경우 Unix에서는 /usr/bin:/bin의 기본 검색 경로에서 조회가 수행되고(execvpe/execvp에 대한 운영 체제 설명서 참조) Windows에서는 현재 프로세스의 환경 변수 PATH가 사용됩니다.

Windows에서는 환경 변수가 대소문자를 구분하지 않습니다. Node.js는 env 키를 사전순으로 정렬하고 대소문자를 구분하지 않고 일치하는 첫 번째 키를 사용합니다. 첫 번째(사전순) 항목만 하위 프로세스에 전달됩니다. 이로 인해 PATH 및 Path와 같이 동일한 키의 여러 변형이 있는 객체를 env 옵션에 전달할 때 Windows에서 문제가 발생할 수 있습니다.

child_process.spawn() 메서드는 Node.js 이벤트 루프를 차단하지 않고 비동기적으로 하위 프로세스를 생성합니다. child_process.spawnSync() 함수는 생성된 프로세스가 종료되거나 종료될 때까지 이벤트 루프를 차단하는 동기적 방식으로 동등한 기능을 제공합니다.

편의를 위해 node:child_process 모듈은 child_process.spawn() 및 child_process.spawnSync()에 대한 여러 개의 동기 및 비동기 대안을 제공합니다. 이러한 대안은 각각 child_process.spawn() 또는 child_process.spawnSync()를 기반으로 구현됩니다.

child_process.exec(): 셸을 생성하고 해당 셸 내에서 명령을 실행하며 완료되면 stdout 및 stderr를 콜백 함수에 전달합니다.
child_process.execFile(): 기본적으로 셸을 먼저 생성하지 않고 명령을 직접 생성한다는 점을 제외하고는 child_process.exec()과 유사합니다.
child_process.fork(): 새로운 Node.js 프로세스를 생성하고 지정된 모듈을 호출하며 상위 및 하위 간에 메시지를 전송할 수 있는 IPC 통신 채널을 설정합니다.
child_process.execSync(): Node.js 이벤트 루프를 차단하는 child_process.exec()의 동기 버전입니다.
child_process.execFileSync(): Node.js 이벤트 루프를 차단하는 child_process.execFile()의 동기 버전입니다.

셸 스크립트 자동화와 같이 특정한 용도의 경우 동기적 대응 함수가 더 편리할 수 있습니다. 그러나 많은 경우 동기적 메서드는 생성된 프로세스가 완료될 때까지 이벤트 루프를 정지시키기 때문에 성능에 상당한 영향을 미칠 수 있습니다.

비동기 프로세스 생성

child_process.spawn(), child_process.fork(), child_process.exec() 및 child_process.execFile() 메서드는 모두 다른 Node.js API의 일반적인 관용적인 비동기 프로그래밍 패턴을 따릅니다.

각 메서드는 ChildProcess 인스턴스를 반환합니다. 이러한 객체는 Node.js EventEmitter API를 구현하여 상위 프로세스가 자식 프로세스의 수명 주기 동안 특정 이벤트가 발생할 때 호출되는 리스너 함수를 등록할 수 있도록 합니다.

child_process.exec() 및 child_process.execFile() 메서드는 자식 프로세스가 종료될 때 호출되는 선택적 callback 함수를 지정할 수도 있습니다.

Windows에서 `.bat` 및 `.cmd` 파일 생성

child_process.exec()과 child_process.execFile()의 차이점의 중요성은 플랫폼에 따라 다를 수 있습니다. Unix 계열 운영 체제(Unix, Linux, macOS)에서는 기본적으로 셸을 생성하지 않으므로 child_process.execFile()이 더 효율적일 수 있습니다. 그러나 Windows에서는 .bat 및 .cmd 파일은 단독으로 터미널 없이 실행할 수 없으므로 child_process.execFile()을 사용하여 시작할 수 없습니다. Windows에서 실행하는 경우 .bat 및 .cmd 파일은 shell 옵션이 설정된 child_process.spawn()을 사용하거나, child_process.exec()을 사용하거나, cmd.exe를 생성하고 .bat 또는 .cmd 파일을 인수로 전달하여 호출할 수 있습니다(shell 옵션과 child_process.exec()이 수행하는 작업). 어떤 경우든 스크립트 파일 이름에 공백이 포함된 경우 따옴표로 묶어야 합니다.

CJSESM

// 또는...
const { exec, spawn } = require('node:child_process')

exec('my.bat', (err, stdout, stderr) => {
  if (err) {
    console.error(err)
    return
  }
  console.log(stdout)
})

// 파일 이름에 공백이 있는 스크립트:
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true })
// 또는:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
})

// 또는...
import { exec, spawn } from 'node:child_process'

exec('my.bat', (err, stdout, stderr) => {
  if (err) {
    console.error(err)
    return
  }
  console.log(stdout)
})

// 파일 이름에 공백이 있는 스크립트:
const bat = spawn('"my script.cmd"', ['a', 'b'], { shell: true })
// 또는:
exec('"my script.cmd" a b', (err, stdout, stderr) => {
  // ...
})

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

[히스토리]

버전	변경 사항
v15.4.0	AbortSignal 지원 추가
v16.4.0, v14.18.0	`cwd` 옵션에서 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체 사용 가능
v8.8.0	`windowsHide` 옵션 지원 시작
v0.1.90	추가됨: v0.1.90

command <string> 실행할 명령어(띄어쓰기로 구분된 인수 포함).
options <Object>
- cwd <string> | <URL> 하위 프로세스의 현재 작업 디렉토리. 기본값: process.cwd().
- env <Object> 환경 키-값 쌍. 기본값: process.env.
- encoding <string> 기본값: 'utf8'
- shell <string> 명령어를 실행할 셸. 셸 요구 사항 및 기본 Windows 셸 참조. 기본값: Unix의 경우 '/bin/sh', Windows의 경우 process.env.ComSpec.
- signal <AbortSignal> AbortSignal을 사용하여 하위 프로세스 중단 허용.
- timeout <number> 기본값: 0
- maxBuffer <number> stdout 또는 stderr에서 허용되는 최대 데이터 크기(바이트). 이를 초과하면 하위 프로세스가 종료되고 출력이 잘립니다. maxBuffer 및 유니코드의 주의 사항을 참조하십시오. 기본값: 1024 * 1024.
- killSignal <string> | <integer> 기본값: 'SIGTERM'
- uid <number> 프로세스의 사용자 ID 설정(setuid(2) 참조).
- gid <number> 프로세스의 그룹 ID 설정(setgid(2) 참조).
- windowsHide <boolean> Windows 시스템에서 일반적으로 생성되는 하위 프로세스 콘솔 창 숨기기. 기본값: false.
callback <Function> 프로세스가 종료될 때 출력과 함께 호출됨.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
반환값: <ChildProcess>

셸을 생성한 다음 해당 셸 내에서 command를 실행하고 생성된 출력을 버퍼링합니다. exec 함수에 전달되는 command 문자열은 셸에 의해 직접 처리되며 특수 문자(셸에 따라 다름)는 그에 따라 처리해야 합니다.

CJSESM

const { exec } = require('node:child_process')

exec('"/path/to/test file/test.sh" arg1 arg2')
// 경로의 공백이 여러 인수의 구분 기호로 해석되지 않도록 큰따옴표를 사용합니다.

exec('echo "The \\$HOME variable is $HOME"')
// 첫 번째 인스턴스에서는 $HOME 변수가 이스케이프되지만 두 번째 인스턴스에서는 이스케이프되지 않습니다.

import { exec } from 'node:child_process'

exec('"/path/to/test file/test.sh" arg1 arg2')
// 경로의 공백이 여러 인수의 구분 기호로 해석되지 않도록 큰따옴표를 사용합니다.

exec('echo "The \\$HOME variable is $HOME"')
// 첫 번째 인스턴스에서는 $HOME 변수가 이스케이프되지만 두 번째 인스턴스에서는 이스케이프되지 않습니다.

절대 이 함수에 검증되지 않은 사용자 입력을 전달하지 마십시오. 셸 메타 문자가 포함된 모든 입력은 임의 명령 실행을 트리거하는 데 사용될 수 있습니다.

callback 함수가 제공되면 (error, stdout, stderr) 인수를 사용하여 호출됩니다. 성공 시 error는 null이 됩니다. 오류 발생 시 error는 Error의 인스턴스가 됩니다. error.code 속성은 프로세스의 종료 코드가 됩니다. 관례적으로 0이 아닌 종료 코드는 오류를 나타냅니다. error.signal은 프로세스를 종료한 신호가 됩니다.

콜백에 전달되는 stdout 및 stderr 인수에는 하위 프로세스의 stdout 및 stderr 출력이 포함됩니다. 기본적으로 Node.js는 UTF-8로 출력을 디코딩하고 문자열을 콜백에 전달합니다. encoding 옵션을 사용하여 stdout 및 stderr 출력을 디코딩하는 데 사용되는 문자 인코딩을 지정할 수 있습니다. encoding이 'buffer'이거나 인식할 수 없는 문자 인코딩인 경우 Buffer 객체가 대신 콜백에 전달됩니다.

CJSESM

const { exec } = require('node:child_process')
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`)
    return
  }
  console.log(`stdout: ${stdout}`)
  console.error(`stderr: ${stderr}`)
})

import { exec } from 'node:child_process'
exec('cat *.js missing_file | wc -l', (error, stdout, stderr) => {
  if (error) {
    console.error(`exec error: ${error}`)
    return
  }
  console.log(`stdout: ${stdout}`)
  console.error(`stderr: ${stderr}`)
})

timeout이 0보다 크면 하위 프로세스가 timeout밀리초보다 오래 실행되는 경우 상위 프로세스는 killSignal 속성(기본값은 'SIGTERM')으로 식별된 신호를 보냅니다.

exec(3) POSIX 시스템 호출과 달리 child_process.exec()은 기존 프로세스를 대체하지 않고 셸을 사용하여 명령을 실행합니다.

이 메서드가 util.promisify()된 버전으로 호출되는 경우 stdout 및 stderr 속성이 있는 Object에 대한 Promise를 반환합니다. 반환된 ChildProcess 인스턴스는 child 속성으로 Promise에 연결됩니다. 오류가 발생하는 경우(0이 아닌 종료 코드로 인한 오류 포함) 거부된 약속이 반환되며, 콜백에서 제공된 것과 동일한 error 객체이지만 stdout 및 stderr라는 두 개의 추가 속성이 있습니다.

CJSESM

const util = require('node:util')
const exec = util.promisify(require('node:child_process').exec)

async function lsExample() {
  const { stdout, stderr } = await exec('ls')
  console.log('stdout:', stdout)
  console.error('stderr:', stderr)
}
lsExample()

import { promisify } from 'node:util'
import child_process from 'node:child_process'
const exec = promisify(child_process.exec)

async function lsExample() {
  const { stdout, stderr } = await exec('ls')
  console.log('stdout:', stdout)
  console.error('stderr:', stderr)
}
lsExample()

signal 옵션이 활성화된 경우 해당 AbortController에서 .abort()를 호출하는 것은 .kill()을 하위 프로세스에 호출하는 것과 유사하지만 콜백에 전달되는 오류는 AbortError가 됩니다.

CJSESM

const { exec } = require('node:child_process')
const controller = new AbortController()
const { signal } = controller
const child = exec('grep ssh', { signal }, error => {
  console.error(error) // AbortError
})
controller.abort()

import { exec } from 'node:child_process'
const controller = new AbortController()
const { signal } = controller
const child = exec('grep ssh', { signal }, error => {
  console.error(error) // AbortError
})
controller.abort()

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

[이력]

버전	변경 사항
v16.4.0, v14.18.0	`cwd` 옵션은 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체가 될 수 있습니다.
v15.4.0, v14.17.0	AbortSignal 지원이 추가되었습니다.
v8.8.0	`windowsHide` 옵션이 지원됩니다.
v0.1.91	추가됨: v0.1.91

file <string> 실행할 실행 파일의 이름 또는 경로입니다.
args <string[]> 문자열 인수 목록입니다.
options <Object>
- cwd <string> | <URL> 하위 프로세스의 현재 작업 디렉토리입니다.
- env <Object> 환경 키-값 쌍입니다. 기본값: process.env.
- encoding <string> 기본값: 'utf8'
- timeout <number> 기본값: 0
- maxBuffer <number> stdout 또는 stderr에서 허용되는 최대 데이터 크기(바이트)입니다. 이를 초과하면 하위 프로세스가 종료되고 출력이 잘립니다. maxBuffer 및 유니코드에서 주의 사항을 참조하십시오. 기본값: 1024 * 1024.
- killSignal <string> | <integer> 기본값: 'SIGTERM'
- uid <number> 프로세스의 사용자 ID를 설정합니다(setuid(2) 참조).
- gid <number> 프로세스의 그룹 ID를 설정합니다(setgid(2) 참조).
- windowsHide <boolean> 일반적으로 Windows 시스템에서 생성되는 하위 프로세스 콘솔 창을 숨깁니다. 기본값: false.
- windowsVerbatimArguments <boolean> Windows에서 인수의 따옴표나 이스케이프 처리를 수행하지 않습니다. Unix에서는 무시됩니다. 기본값: false.
- shell <boolean> | <string> true이면 셸 내에서 command를 실행합니다. Unix에서는 '/bin/sh'를, Windows에서는 process.env.ComSpec을 사용합니다. 문자열로 다른 셸을 지정할 수 있습니다. 셸 요구 사항 및 기본 Windows 셸을 참조하십시오. 기본값: false (셸 없음).
- signal <AbortSignal> AbortSignal을 사용하여 하위 프로세스를 중단할 수 있습니다.
callback <Function> 프로세스가 종료될 때 출력과 함께 호출됩니다.
- error <Error>
- stdout <string> | <Buffer>
- stderr <string> | <Buffer>
반환값: <ChildProcess>

child_process.execFile() 함수는 child_process.exec()과 유사하지만 기본적으로 셸을 생성하지 않습니다. 지정된 실행 파일 file이 새 프로세스로 직접 생성되므로 child_process.exec()보다 약간 더 효율적입니다.

child_process.exec()과 동일한 옵션이 지원됩니다. 셸이 생성되지 않으므로 I/O 리디렉션 및 파일 글로빙과 같은 동작은 지원되지 않습니다.

CJSESM

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 인수에는 하위 프로세스의 stdout 및 stderr 출력이 포함됩니다. 기본적으로 Node.js는 출력을 UTF-8로 디코딩하고 문자열을 콜백에 전달합니다. encoding 옵션을 사용하여 stdout 및 stderr 출력을 디코딩하는 데 사용되는 문자 인코딩을 지정할 수 있습니다. encoding이 'buffer'이거나 인식할 수 없는 문자 인코딩인 경우 대신 Buffer 객체가 콜백에 전달됩니다.

이 메서드가 util.promisify()된 버전으로 호출되는 경우 stdout 및 stderr 속성이 있는 Object에 대한 Promise를 반환합니다. 반환된 ChildProcess 인스턴스는 child 속성으로 Promise에 연결됩니다. 오류가 발생하는 경우(0이 아닌 종료 코드로 인한 오류 포함) 거부된 약속이 반환되고 콜백에 제공된 것과 동일한 error 객체가 제공되지만 두 개의 추가 속성 stdout 및 stderr가 있습니다.

CJSESM

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 옵션이 활성화된 경우 이 함수에 위생 처리되지 않은 사용자 입력을 전달하지 마십시오. 셸 메타 문자가 포함된 모든 입력은 임의 명령 실행을 트리거하는 데 사용될 수 있습니다.

signal 옵션이 활성화된 경우 해당 AbortController에서 .abort()를 호출하는 것은 하위 프로세스에서 .kill()을 호출하는 것과 유사하지만 콜백에 전달되는 오류는 AbortError입니다.

CJSESM

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

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

[히스토리]

버전	변경 사항
v17.4.0, v16.14.0	`modulePath` 매개변수는 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체가 될 수 있습니다.
v16.4.0, v14.18.0	`cwd` 옵션은 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체가 될 수 있습니다.
v15.13.0, v14.18.0	timeout이 추가되었습니다.
v15.11.0, v14.18.0	AbortSignal에 대한 killSignal이 추가되었습니다.
v15.6.0, v14.17.0	AbortSignal 지원이 추가되었습니다.
v13.2.0, v12.16.0	`serialization` 옵션이 지원됩니다.
v8.0.0	`stdio` 옵션이 문자열이 될 수 있습니다.
v6.4.0	`stdio` 옵션이 지원됩니다.
v0.5.0	추가됨: v0.5.0

modulePath <문자열> | <URL> 자식 프로세스에서 실행할 모듈.
args <문자열[]> 문자열 인수 목록.
options <객체>
- cwd <문자열> | <URL> 자식 프로세스의 현재 작업 디렉토리.
- detached <부울> 자식 프로세스가 상위 프로세스와 독립적으로 실행되도록 준비합니다. 특정 동작은 플랫폼에 따라 다릅니다. options.detached) 참조.
- env <객체> 환경 키-값 쌍. 기본값: process.env.
- execPath <문자열> 자식 프로세스를 생성하는 데 사용되는 실행 파일.
- execArgv <문자열[]> 실행 파일에 전달되는 문자열 인수 목록. 기본값: process.execArgv.
- gid <숫자> 프로세스의 그룹 ID를 설정합니다(setgid(2) 참조).
- serialization <문자열> 프로세스 간 메시지 전송에 사용되는 직렬화 종류를 지정합니다. 가능한 값은 'json'과 'advanced'입니다. 자세한 내용은 고급 직렬화를 참조하십시오. 기본값: 'json'.
- signal <AbortSignal> AbortSignal을 사용하여 자식 프로세스를 닫을 수 있습니다.
- killSignal <문자열> | <정수> 생성된 프로세스가 시간 초과 또는 중단 신호로 종료될 때 사용할 신호 값입니다. 기본값: 'SIGTERM'.
- silent <부울> true이면 자식 프로세스의 stdin, stdout 및 stderr이 상위 프로세스로 파이프됩니다. 그렇지 않으면 상위 프로세스에서 상속됩니다. 자세한 내용은 child_process.spawn()의 stdio에 대한 'pipe' 및 'inherit' 옵션을 참조하십시오. 기본값: false.
- stdio <배열> | <문자열> child_process.spawn()의 stdio를 참조하십시오. 이 옵션이 제공되면 silent를 재정의합니다. 배열 변형을 사용하는 경우 'ipc' 값을 가진 항목이 정확히 하나 있어야 하며, 그렇지 않으면 오류가 발생합니다. 예를 들어 [0, 1, 2, 'ipc']입니다.
- uid <숫자> 프로세스의 사용자 ID를 설정합니다(setuid(2) 참조).
- windowsVerbatimArguments <부울> Windows에서 인수의 따옴표나 이스케이프가 수행되지 않습니다. Unix에서는 무시됩니다. 기본값: false.
- timeout <숫자> 밀리초 단위로 프로세스가 실행될 수 있는 최대 시간입니다. 기본값: undefined.
반환값: <ChildProcess>

child_process.fork() 메서드는 새로운 Node.js 프로세스를 생성하는 데 특별히 사용되는 child_process.spawn()의 특수한 경우입니다. child_process.spawn()과 마찬가지로 ChildProcess 객체가 반환됩니다. 반환된 ChildProcess에는 상위 및 자식 프로세스 간에 메시지를 주고받을 수 있는 추가 통신 채널이 내장되어 있습니다. 자세한 내용은 subprocess.send()를 참조하십시오.

생성된 Node.js 자식 프로세스는 두 프로세스 간에 설정된 IPC 통신 채널을 제외하고는 상위 프로세스와 독립적이라는 점을 명심하십시오. 각 프로세스는 자체 메모리와 자체 V8 인스턴스를 갖습니다. 필요한 추가 리소스 할당으로 인해 많은 수의 자식 Node.js 프로세스를 생성하는 것은 권장하지 않습니다.

기본적으로 child_process.fork()는 상위 프로세스의 process.execPath를 사용하여 새로운 Node.js 인스턴스를 생성합니다. options 객체의 execPath 속성을 사용하면 대체 실행 경로를 사용할 수 있습니다.

사용자 지정 execPath로 시작된 Node.js 프로세스는 자식 프로세스의 환경 변수 NODE_CHANNEL_FD를 사용하여 식별된 파일 디스크립터(fd)를 사용하여 상위 프로세스와 통신합니다.

fork(2) POSIX 시스템 호출과 달리 child_process.fork()는 현재 프로세스를 복제하지 않습니다.

child_process.spawn()에서 사용할 수 있는 shell 옵션은 child_process.fork()에서 지원되지 않으며 설정된 경우 무시됩니다.

signal 옵션이 활성화된 경우 해당 AbortController에서 .abort()를 호출하는 것은 자식 프로세스에서 .kill()을 호출하는 것과 유사하지만 콜백에 전달되는 오류는 AbortError가 됩니다.

CJSESM

const { fork } = require('node:child_process')
const process = require('node:process')

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`)
  }, 1_000)
} else {
  const controller = new AbortController()
  const { signal } = controller
  const child = fork(__filename, ['child'], { signal })
  child.on('error', err => {
    // 이것은 컨트롤러가 중단되면 err이 AbortError가 되어 호출됩니다.
  })
  controller.abort() // 자식 프로세스 중지
}

import { fork } from 'node:child_process'
import process from 'node:process'

if (process.argv[2] === 'child') {
  setTimeout(() => {
    console.log(`Hello from ${process.argv[2]}!`)
  }, 1_000)
} else {
  const controller = new AbortController()
  const { signal } = controller
  const child = fork(import.meta.url, ['child'], { signal })
  child.on('error', err => {
    // 이것은 컨트롤러가 중단되면 err이 AbortError가 되어 호출됩니다.
  })
  controller.abort() // 자식 프로세스 중지
}

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

[이력]

버전	변경 사항
v16.4.0, v14.18.0	`cwd` 옵션은 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체가 될 수 있습니다.
v15.13.0, v14.18.0	timeout이 추가되었습니다.
v15.11.0, v14.18.0	AbortSignal에 대한 killSignal이 추가되었습니다.
v15.5.0, v14.17.0	AbortSignal 지원이 추가되었습니다.
v13.2.0, v12.16.0	`serialization` 옵션이 지원됩니다.
v8.8.0	`windowsHide` 옵션이 지원됩니다.
v6.4.0	`argv0` 옵션이 지원됩니다.
v5.7.0	`shell` 옵션이 지원됩니다.
v0.1.90	추가됨: v0.1.90

command <string> 실행할 명령어.
args <string[]> 문자열 인수 목록.
options <Object>
- cwd <string> | <URL> 하위 프로세스의 현재 작업 디렉토리.
- env <Object> 환경 키-값 쌍. 기본값: process.env.
- argv0 <string> 하위 프로세스에 전달되는 argv[0]의 값을 명시적으로 설정합니다. 지정하지 않으면 command로 설정됩니다.
- stdio <Array> | <string> 하위 프로세스의 stdio 구성 (options.stdio 참조).
- detached <boolean> 하위 프로세스가 상위 프로세스와 독립적으로 실행되도록 준비합니다. 특정 동작은 플랫폼에 따라 다릅니다. options.detached 참조).
- uid <number> 프로세스의 사용자 ID를 설정합니다(setuid(2) 참조).
- gid <number> 프로세스의 그룹 ID를 설정합니다(setgid(2) 참조).
- serialization <string> 프로세스 간 메시지 전송에 사용되는 직렬화 종류를 지정합니다. 가능한 값은 'json' 및 'advanced'입니다. 자세한 내용은 고급 직렬화를 참조하십시오. 기본값: 'json'.
- shell <boolean> | <string> true이면 셸 내에서 command를 실행합니다. Unix에서는 '/bin/sh'를 사용하고 Windows에서는 process.env.ComSpec을 사용합니다. 문자열로 다른 셸을 지정할 수 있습니다. 셸 요구 사항 및 기본 Windows 셸을 참조하십시오. 기본값: false (셸 없음).
- windowsVerbatimArguments <boolean> Windows에서 인수의 따옴표 또는 이스케이프 처리를 수행하지 않습니다. Unix에서는 무시됩니다. shell이 지정되고 CMD인 경우 자동으로 true로 설정됩니다. 기본값: false.
- windowsHide <boolean> 일반적으로 Windows 시스템에서 생성되는 하위 프로세스 콘솔 창을 숨깁니다. 기본값: false.
- signal <AbortSignal> AbortSignal을 사용하여 하위 프로세스를 중단할 수 있습니다.
- timeout <number> 프로세스가 실행될 수 있는 최대 시간(밀리초). 기본값: undefined.
- killSignal <string> | <integer> 타임아웃 또는 중단 신호에 의해 생성된 프로세스가 종료될 때 사용할 신호 값입니다. 기본값: 'SIGTERM'.
반환값: <ChildProcess>

child_process.spawn() 메서드는 지정된 command를 사용하여 새 프로세스를 생성하고, args에 명령줄 인수를 사용합니다. 생략하면 args는 빈 배열로 기본 설정됩니다.

shell 옵션이 활성화된 경우, 이 함수에 검증되지 않은 사용자 입력을 전달하지 마십시오. 셸 메타 문자가 포함된 모든 입력은 임의 명령 실행을 트리거하는 데 사용될 수 있습니다.

세 번째 인수는 추가 옵션을 지정하는 데 사용할 수 있으며, 기본값은 다음과 같습니다.

const defaults = {
  cwd: undefined,
  env: process.env,
}

cwd를 사용하여 프로세스가 생성되는 작업 디렉토리를 지정합니다. 지정하지 않으면 현재 작업 디렉토리를 상속합니다. 지정했지만 경로가 존재하지 않으면 하위 프로세스는 ENOENT 오류를 내고 즉시 종료됩니다. 명령어가 존재하지 않는 경우에도 ENOENT가 발생합니다.

env를 사용하여 새 프로세스에 표시될 환경 변수를 지정합니다. 기본값은 process.env입니다.

env의 undefined 값은 무시됩니다.

ls -lh /usr을 실행하고 stdout, stderr 및 종료 코드를 캡처하는 예:

CJSESM

const { spawn } = require('node:child_process')
const ls = spawn('ls', ['-lh', '/usr'])

ls.stdout.on('data', data => {
  console.log(`stdout: ${data}`)
})

ls.stderr.on('data', data => {
  console.error(`stderr: ${data}`)
})

ls.on('close', code => {
  console.log(`child process exited with code ${code}`)
})

import { spawn } from 'node:child_process'
const ls = spawn('ls', ['-lh', '/usr'])

ls.stdout.on('data', data => {
  console.log(`stdout: ${data}`)
})

ls.stderr.on('data', data => {
  console.error(`stderr: ${data}`)
})

ls.on('close', code => {
  console.log(`child process exited with code ${code}`)
})

예: ps ax | grep ssh를 실행하는 매우 복잡한 방법

CJSESM

const { spawn } = require('node:child_process')
const ps = spawn('ps', ['ax'])
const grep = spawn('grep', ['ssh'])

ps.stdout.on('data', data => {
  grep.stdin.write(data)
})

ps.stderr.on('data', data => {
  console.error(`ps stderr: ${data}`)
})

ps.on('close', code => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`)
  }
  grep.stdin.end()
})

grep.stdout.on('data', data => {
  console.log(data.toString())
})

grep.stderr.on('data', data => {
  console.error(`grep stderr: ${data}`)
})

grep.on('close', code => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`)
  }
})

import { spawn } from 'node:child_process'
const ps = spawn('ps', ['ax'])
const grep = spawn('grep', ['ssh'])

ps.stdout.on('data', data => {
  grep.stdin.write(data)
})

ps.stderr.on('data', data => {
  console.error(`ps stderr: ${data}`)
})

ps.on('close', code => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`)
  }
  grep.stdin.end()
})

grep.stdout.on('data', data => {
  console.log(data.toString())
})

grep.stderr.on('data', data => {
  console.error(`grep stderr: ${data}`)
})

grep.on('close', code => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`)
  }
})

실패한 spawn 확인 예:

CJSESM

const { spawn } = require('node:child_process')
const subprocess = spawn('bad_command')

subprocess.on('error', err => {
  console.error('Failed to start subprocess.')
})

import { spawn } from 'node:child_process'
const subprocess = spawn('bad_command')

subprocess.on('error', err => {
  console.error('Failed to start subprocess.')
})

특정 플랫폼(macOS, Linux)은 프로세스 제목에 argv[0]의 값을 사용하는 반면 다른 플랫폼(Windows, SunOS)은 command를 사용합니다.

Node.js는 시작 시 argv[0]을 process.execPath로 덮어쓰므로 Node.js 하위 프로세스의 process.argv[0]은 상위에서 spawn에 전달된 argv0 매개변수와 일치하지 않습니다. 대신 process.argv0 속성을 사용하여 가져옵니다.

signal 옵션이 활성화된 경우 해당 AbortController에 대해 .abort()를 호출하는 것은 하위 프로세스에 대해 .kill()을 호출하는 것과 유사하지만 콜백에 전달되는 오류는 AbortError입니다.

CJSESM

const { spawn } = require('node:child_process')
const controller = new AbortController()
const { signal } = controller
const grep = spawn('grep', ['ssh'], { signal })
grep.on('error', err => {
  // 컨트롤러가 중단되면 AbortError가 있는 err로 호출됩니다.
})
controller.abort() // 하위 프로세스를 중지합니다.

import { spawn } from 'node:child_process'
const controller = new AbortController()
const { signal } = controller
const grep = spawn('grep', ['ssh'], { signal })
grep.on('error', err => {
  // 컨트롤러가 중단되면 AbortError가 있는 err로 호출됩니다.
})
controller.abort() // 하위 프로세스를 중지합니다.

`options.detached`

추가됨: v0.7.10

Windows에서 options.detached를 true로 설정하면 상위 프로세스가 종료된 후에도 하위 프로세스가 계속 실행될 수 있습니다. 하위 프로세스는 자체 콘솔 창을 갖게 됩니다. 하위 프로세스에 대해 활성화되면 비활성화할 수 없습니다.

Windows 이외의 플랫폼에서는 options.detached가 true로 설정되면 하위 프로세스는 새 프로세스 그룹 및 세션의 리더가 됩니다. 하위 프로세스는 분리되었는지 여부에 관계없이 상위 프로세스가 종료된 후에도 계속 실행될 수 있습니다. 자세한 내용은 setsid(2)를 참조하십시오.

기본적으로 상위 프로세스는 분리된 하위 프로세스가 종료될 때까지 기다립니다. 지정된 subprocess가 종료될 때까지 상위 프로세스가 기다리지 않도록 하려면 subprocess.unref() 메서드를 사용하십시오. 이렇게 하면 상위 프로세스의 이벤트 루프가 참조 카운트에 하위 프로세스를 포함하지 않게 되어 하위 프로세스와 상위 프로세스 간에 설정된 IPC 채널이 없는 한 상위 프로세스가 하위 프로세스와 독립적으로 종료될 수 있습니다.

장시간 실행 프로세스를 시작하는 데 detached 옵션을 사용하는 경우 상위 프로세스가 종료된 후에도 상위 프로세스에 연결되지 않은 stdio 구성이 제공되지 않으면 백그라운드에서 프로세스가 계속 실행되지 않습니다. 상위 프로세스의 stdio가 상속되면 하위 프로세스는 제어 터미널에 연결된 상태로 유지됩니다.

상위 프로세스의 종료를 무시하기 위해 분리하고 상위 stdio 파일 디스크립터를 무시함으로써 장시간 실행 프로세스의 예:

CJSESM

const { spawn } = require('node:child_process')
const process = require('node:process')

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
})

subprocess.unref()

import { spawn } from 'node:child_process'
import process from 'node:process'

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
})

subprocess.unref()

또는 하위 프로세스의 출력을 파일로 리디렉션할 수 있습니다.

CJSESM

const { openSync } = require('node:fs')
const { spawn } = require('node:child_process')
const out = openSync('./out.log', 'a')
const err = openSync('./out.log', 'a')

const subprocess = spawn('prg', [], {
  detached: true,
  stdio: ['ignore', out, err],
})

subprocess.unref()

import { openSync } from 'node:fs'
import { spawn } from 'node:child_process'
const out = openSync('./out.log', 'a')
const err = openSync('./out.log', 'a')

const subprocess = spawn('prg', [], {
  detached: true,
  stdio: ['ignore', out, err],
})

subprocess.unref()

`options.stdio`

[히스토리]

버전	변경 사항
v15.6.0, v14.18.0	`overlapped` stdio 플래그 추가
v3.3.1	값 `0`이 파일 디스크립터로 허용됨
v0.7.10	추가됨: v0.7.10

options.stdio 옵션은 부모 프로세스와 자식 프로세스 간에 설정되는 파이프를 구성하는 데 사용됩니다. 기본적으로 자식의 stdin, stdout 및 stderr은 ChildProcess 객체의 해당 subprocess.stdin, subprocess.stdout 및 subprocess.stderr 스트림으로 리다이렉트됩니다. 이는 options.stdio를 ['pipe', 'pipe', 'pipe']로 설정하는 것과 같습니다.

편의를 위해 options.stdio는 다음 문자열 중 하나일 수 있습니다.

'pipe': ['pipe', 'pipe', 'pipe']와 동일 (기본값)
'overlapped': ['overlapped', 'overlapped', 'overlapped']와 동일
'ignore': ['ignore', 'ignore', 'ignore']와 동일
'inherit': ['inherit', 'inherit', 'inherit'] 또는 [0, 1, 2]와 동일

그렇지 않으면 options.stdio의 값은 각 인덱스가 자식의 fd에 해당하는 배열입니다. fd 0, 1 및 2는 각각 stdin, stdout 및 stderr에 해당합니다. 부모와 자식 간에 추가 파이프를 만들려면 추가 fd를 지정할 수 있습니다. 값은 다음 중 하나입니다.

CJSESM

const { spawn } = require('node:child_process')
const process = require('node:process')

// 자식은 부모의 stdios를 사용합니다.
spawn('prg', [], { stdio: 'inherit' })

// stderr만 공유하는 자식 생성
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] })

// startd 스타일 인터페이스를 제공하는 프로그램과 상호 작용하기 위해 추가 fd=4 열기
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] })

import { spawn } from 'node:child_process'
import process from 'node:process'

// 자식은 부모의 stdios를 사용합니다.
spawn('prg', [], { stdio: 'inherit' })

// stderr만 공유하는 자식 생성
spawn('prg', [], { stdio: ['pipe', 'pipe', process.stderr] })

// startd 스타일 인터페이스를 제공하는 프로그램과 상호 작용하기 위해 추가 fd=4 열기
spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] })

부모 프로세스와 자식 프로세스 간에 IPC 채널이 설정되고 자식 프로세스가 Node.js 인스턴스인 경우 자식 프로세스는 자식 프로세스가 'disconnect' 이벤트 또는 'message' 이벤트에 대한 이벤트 핸들러를 등록할 때까지 IPC 채널을 참조 해제하지 않고 (unref() 사용) 시작됩니다. 이를 통해 열린 IPC 채널이 프로세스를 열린 상태로 유지하지 않고 자식 프로세스가 정상적으로 종료될 수 있습니다. child_process.exec() 및 child_process.fork()도 참조하십시오.

동기 프로세스 생성

child_process.spawnSync(), child_process.execSync(), 및 child_process.execFileSync() 메서드는 동기적이며 Node.js 이벤트 루프를 차단하여 생성된 프로세스가 종료될 때까지 추가 코드의 실행을 일시 중지합니다.

이러한 차단 호출은 주로 범용 스크립팅 작업을 단순화하고 시작 시 애플리케이션 구성의 로드/처리를 단순화하는 데 유용합니다.

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

[히스토리]

버전	변경 사항
v16.4.0, v14.18.0	`cwd` 옵션은 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체가 될 수 있습니다.
v10.10.0	`input` 옵션은 이제 모든 `TypedArray` 또는 `DataView`가 될 수 있습니다.
v8.8.0	`windowsHide` 옵션이 지원됩니다.
v8.0.0	`input` 옵션은 이제 `Uint8Array`가 될 수 있습니다.
v6.2.1, v4.5.0	`encoding` 옵션을 명시적으로 `buffer`로 설정할 수 있습니다.
v0.11.12	추가됨: v0.11.12

file <string> 실행할 실행 파일의 이름 또는 경로입니다.
args <string[]> 문자열 인수 목록입니다.
options <Object>
- cwd <string> | <URL> 자식 프로세스의 현재 작업 디렉토리입니다.
- input <string> | <Buffer> | <TypedArray> | <DataView> 생성된 프로세스에 stdin으로 전달될 값입니다. stdio[0]이 'pipe'로 설정된 경우 이 값을 제공하면 stdio[0]을 재정의합니다.
- stdio <string> | <Array> 자식의 stdio 구성입니다. child_process.spawn()의 stdio를 참조하십시오. stdio가 지정되지 않은 경우 기본적으로 stderr은 상위 프로세스의 stderr로 출력됩니다. 기본값: 'pipe'.
- env <Object> 환경 키-값 쌍입니다. 기본값: process.env.
- uid <number> 프로세스의 사용자 ID를 설정합니다(setuid(2) 참조).
- gid <number> 프로세스의 그룹 ID를 설정합니다(setgid(2) 참조).
- timeout <number> 밀리초 단위로 프로세스가 실행될 수 있는 최대 시간입니다. 기본값: undefined.
- killSignal <string> | <integer> 생성된 프로세스가 종료될 때 사용할 신호 값입니다. 기본값: 'SIGTERM'.
- maxBuffer <number> stdout 또는 stderr에서 허용되는 최대 데이터 크기(바이트)입니다. 이를 초과하면 자식 프로세스가 종료됩니다. maxBuffer 및 유니코드에서 주의 사항을 참조하십시오. 기본값: 1024 * 1024.
- encoding <string> 모든 stdio 입력 및 출력에 사용되는 인코딩입니다. 기본값: 'buffer'.
- windowsHide <boolean> 일반적으로 Windows 시스템에서 생성되는 하위 프로세스 콘솔 창을 숨깁니다. 기본값: false.
- shell <boolean> | <string> true이면 쉘 내에서 command를 실행합니다. Unix에서는 '/bin/sh'를, Windows에서는 process.env.ComSpec을 사용합니다. 문자열로 다른 쉘을 지정할 수 있습니다. 쉘 요구 사항 및 기본 Windows 쉘을 참조하십시오. 기본값: false (쉘 없음).
반환값: <Buffer> | <string> 명령어의 stdout입니다.

child_process.execFileSync() 메서드는 일반적으로 자식 프로세스가 완전히 닫힐 때까지 반환되지 않는다는 점을 제외하고는 child_process.execFile()과 동일합니다. 제한 시간이 발생하고 killSignal이 전송되면 프로세스가 완전히 종료될 때까지 메서드가 반환되지 않습니다.

자식 프로세스가 SIGTERM 신호를 가로채고 처리하지만 종료되지 않는 경우 상위 프로세스는 자식 프로세스가 종료될 때까지 계속 기다립니다.

프로세스 시간이 초과되거나 0이 아닌 종료 코드가 있는 경우 이 메서드는 기본 child_process.spawnSync()의 전체 결과를 포함하는 Error를 throw합니다.

shell 옵션을 사용하는 경우, 위생 처리되지 않은 사용자 입력을 이 함수에 전달하지 마십시오. 쉘 메타 문자가 포함된 모든 입력은 임의의 명령 실행을 트리거하는 데 사용될 수 있습니다.

CJSESM

const { execFileSync } = require('node:child_process')

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // 자식 프로세스의 stdout 및 stderr을 캡처합니다. 자식 stderr을 상위 stderr로 스트리밍하는 기본 동작을 재정의합니다.
    stdio: 'pipe',

    // stdio 파이프에 utf8 인코딩을 사용합니다.
    encoding: 'utf8',
  })

  console.log(stdout)
} catch (err) {
  if (err.code) {
    // 자식 프로세스 생성에 실패했습니다.
    console.error(err.code)
  } else {
    // 자식 프로세스가 생성되었지만 0이 아닌 종료 코드로 종료되었습니다.
    // 오류에는 자식의 stdout 및 stderr이 포함됩니다.
    const { stdout, stderr } = err

    console.error({ stdout, stderr })
  }
}

import { execFileSync } from 'node:child_process'

try {
  const stdout = execFileSync('my-script.sh', ['my-arg'], {
    // 자식 프로세스의 stdout 및 stderr을 캡처합니다. 자식 stderr을 상위 stderr로 스트리밍하는 기본 동작을 재정의합니다.
    stdio: 'pipe',

    // stdio 파이프에 utf8 인코딩을 사용합니다.
    encoding: 'utf8',
  })

  console.log(stdout)
} catch (err) {
  if (err.code) {
    // 자식 프로세스 생성에 실패했습니다.
    console.error(err.code)
  } else {
    // 자식 프로세스가 생성되었지만 0이 아닌 종료 코드로 종료되었습니다.
    // 오류에는 자식의 stdout 및 stderr이 포함됩니다.
    const { stdout, stderr } = err

    console.error({ stdout, stderr })
  }
}

`child_process.execSync(command[, options])`

[이력]

버전	변경 사항
v16.4.0, v14.18.0	`cwd` 옵션에 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체를 사용할 수 있습니다.
v10.10.0	`input` 옵션에 모든 `TypedArray` 또는 `DataView`를 사용할 수 있습니다.
v8.8.0	`windowsHide` 옵션이 지원됩니다.
v8.0.0	`input` 옵션에 `Uint8Array`를 사용할 수 있습니다.
v0.11.12	추가됨: v0.11.12

command <문자열> 실행할 명령어.
options <객체>
- cwd <문자열> | <URL> 하위 프로세스의 현재 작업 디렉토리.
- input <문자열> | <Buffer> | <TypedArray> | <DataView> 생성된 프로세스에 stdin으로 전달될 값. stdio[0]이 'pipe'로 설정된 경우, 이 값을 제공하면 stdio[0]을 재정의합니다.
- stdio <문자열> | <배열> 하위 프로세스의 stdio 구성. child_process.spawn()의 stdio를 참조하십시오. stdio가 지정되지 않은 경우 stderr는 기본적으로 상위 프로세스의 stderr로 출력됩니다. 기본값: 'pipe'.
- env <객체> 환경 키-값 쌍. 기본값: process.env.
- shell <문자열> 명령어를 실행할 셸. 셸 요구 사항 및 기본 Windows 셸을 참조하십시오. 기본값: Unix에서는 '/bin/sh', Windows에서는 process.env.ComSpec.
- uid <숫자> 프로세스의 사용자 ID를 설정합니다. (setuid(2) 참조).
- gid <숫자> 프로세스의 그룹 ID를 설정합니다. (setgid(2) 참조).
- timeout <숫자> 밀리초 단위로 프로세스가 실행될 수 있는 최대 시간. 기본값: undefined.
- killSignal <문자열> | <정수> 생성된 프로세스가 종료될 때 사용할 신호 값. 기본값: 'SIGTERM'.
- maxBuffer <숫자> stdout 또는 stderr에서 허용되는 최대 데이터 크기(바이트). 이를 초과하면 하위 프로세스가 종료되고 출력이 잘립니다. maxBuffer 및 유니코드의 주의 사항을 참조하십시오. 기본값: 1024 * 1024.
- encoding <문자열> 모든 stdio 입력 및 출력에 사용되는 인코딩. 기본값: 'buffer'.
- windowsHide <불리언> 일반적으로 Windows 시스템에서 생성되는 하위 프로세스 콘솔 창을 숨깁니다. 기본값: false.
반환값: <Buffer> | <문자열> 명령어의 stdout.

child_process.execSync() 메서드는 일반적으로 child_process.exec()과 동일하지만, 하위 프로세스가 완전히 종료될 때까지 반환하지 않는다는 점이 다릅니다. 제한 시간이 발생하고 killSignal이 전송되면 프로세스가 완전히 종료될 때까지 메서드가 반환되지 않습니다. 하위 프로세스가 SIGTERM 신호를 가로채고 처리하여 종료되지 않으면 상위 프로세스는 하위 프로세스가 종료될 때까지 기다립니다.

프로세스가 시간 초과되거나 0이 아닌 종료 코드를 가지면 이 메서드는 예외를 throw합니다. Error 객체에는 child_process.spawnSync()의 전체 결과가 포함됩니다.

절대로 검증되지 않은 사용자 입력을 이 함수에 전달하지 마십시오. 셸 메타 문자가 포함된 모든 입력은 임의의 명령 실행을 트리거하는 데 사용될 수 있습니다.

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

[히스토리]

버전	변경 사항
v16.4.0, v14.18.0	`cwd` 옵션에 `file:` 프로토콜을 사용하는 WHATWG `URL` 객체를 사용할 수 있습니다.
v10.10.0	`input` 옵션에 이제 모든 `TypedArray` 또는 `DataView`를 사용할 수 있습니다.
v8.8.0	`windowsHide` 옵션이 지원됩니다.
v8.0.0	`input` 옵션에 이제 `Uint8Array`를 사용할 수 있습니다.
v5.7.0	`shell` 옵션이 지원됩니다.
v6.2.1, v4.5.0	`encoding` 옵션을 `buffer`로 명시적으로 설정할 수 있습니다.
v0.11.12	추가됨: v0.11.12

command <string> 실행할 명령어.
args <string[]> 문자열 인수 목록.
options <Object>
- cwd <string> | <URL> 하위 프로세스의 현재 작업 디렉토리.
- input <string> | <Buffer> | <TypedArray> | <DataView> 생성된 프로세스에 stdin으로 전달될 값. stdio[0]이 'pipe'로 설정된 경우, 이 값을 제공하면 stdio[0]을 재정의합니다.
- argv0 <string> 하위 프로세스에 전달되는 argv[0]의 값을 명시적으로 설정합니다. 지정하지 않으면 command로 설정됩니다.
- stdio <string> | <Array> 하위 프로세스의 stdio 구성. child_process.spawn()의 stdio를 참조하십시오. 기본값: 'pipe'.
- env <Object> 환경 키-값 쌍. 기본값: process.env.
- uid <number> 프로세스의 사용자 ID를 설정합니다 ( setuid(2) 참조).
- gid <number> 프로세스의 그룹 ID를 설정합니다 ( setgid(2) 참조).
- timeout <number> 밀리초 단위로 프로세스가 실행될 수 있는 최대 시간. 기본값: undefined.
- killSignal <string> | <integer> 생성된 프로세스가 종료될 때 사용할 신호 값. 기본값: 'SIGTERM'.
- maxBuffer <number> stdout 또는 stderr에서 허용되는 최대 데이터 크기(바이트). 이를 초과하면 하위 프로세스가 종료되고 출력이 잘립니다. maxBuffer 및 유니코드의 주의 사항을 참조하십시오. 기본값: 1024 * 1024.
- encoding <string> 모든 stdio 입력 및 출력에 사용되는 인코딩. 기본값: 'buffer'.
- shell <boolean> | <string> true이면 쉘 내에서 command를 실행합니다. Unix에서는 '/bin/sh'를 사용하고 Windows에서는 process.env.ComSpec을 사용합니다. 다른 쉘을 문자열로 지정할 수 있습니다. 쉘 요구 사항 및 기본 Windows 쉘을 참조하십시오. 기본값: false (쉘 없음).
- windowsVerbatimArguments <boolean> Windows에서 인수의 따옴표나 이스케이핑을 수행하지 않습니다. Unix에서는 무시됩니다. shell이 지정되고 CMD인 경우 자동으로 true로 설정됩니다. 기본값: false.
- windowsHide <boolean> 일반적으로 Windows 시스템에서 생성되는 하위 프로세스 콘솔 창을 숨깁니다. 기본값: false.
반환값: <Object>
- pid <number> 하위 프로세스의 PID.
- output <Array> stdio 출력의 결과 배열.
- stdout <Buffer> | <string> output[1]의 내용.
- stderr <Buffer> | <string> output[2]의 내용.
- status <number> | <null> 하위 프로세스의 종료 코드 또는 하위 프로세스가 신호로 인해 종료된 경우 null.
- signal <string> | <null> 하위 프로세스를 종료하는 데 사용된 신호 또는 하위 프로세스가 신호로 인해 종료되지 않은 경우 null.
- error <Error> 하위 프로세스가 실패하거나 시간 초과된 경우의 오류 객체.

child_process.spawnSync() 메서드는 일반적으로 child_process.spawn()과 동일하지만, 하위 프로세스가 완전히 닫힐 때까지 반환되지 않는다는 점이 다릅니다. 시간 초과가 발생하고 killSignal이 전송되면 프로세스가 완전히 종료될 때까지 메서드가 반환되지 않습니다. 프로세스가 SIGTERM 신호를 가로채고 처리하지만 종료되지 않으면 상위 프로세스는 하위 프로세스가 종료될 때까지 대기합니다.

shell 옵션이 활성화된 경우, 이 함수에 위생 처리되지 않은 사용자 입력을 전달하지 마십시오. 쉘 메타 문자가 포함된 입력은 임의의 명령 실행을 트리거하는 데 사용될 수 있습니다.

클래스: `ChildProcess`

추가됨: v2.2.0

상속: <EventEmitter>

ChildProcess의 인스턴스는 생성된 자식 프로세스를 나타냅니다.

ChildProcess의 인스턴스는 직접 생성되지 않습니다. 대신 child_process.spawn(), child_process.exec(), child_process.execFile(), 또는 child_process.fork() 메서드를 사용하여 ChildProcess의 인스턴스를 생성합니다.

이벤트: `'close'`

추가됨: v0.7.7

code <number> 자식 프로세스가 자체적으로 종료된 경우 종료 코드입니다.
signal <string> 자식 프로세스가 종료된 신호입니다.

'close' 이벤트는 프로세스가 종료되고 자식 프로세스의 stdio 스트림이 닫힌 후에 발생합니다. 여러 프로세스가 동일한 stdio 스트림을 공유할 수 있으므로 'exit' 이벤트와는 다릅니다. 'close' 이벤트는 항상 'exit' 이벤트가 이미 발생한 후 또는 자식 프로세스가 생성되지 못한 경우 'error' 이벤트 후에 발생합니다.

CJSESM

const { spawn } = require('node:child_process')
const ls = spawn('ls', ['-lh', '/usr'])

ls.stdout.on('data', data => {
  console.log(`stdout: ${data}`)
})

ls.on('close', code => {
  console.log(`child process close all stdio with code ${code}`)
})

ls.on('exit', code => {
  console.log(`child process exited with code ${code}`)
})

import { spawn } from 'node:child_process'
const ls = spawn('ls', ['-lh', '/usr'])

ls.stdout.on('data', data => {
  console.log(`stdout: ${data}`)
})

ls.on('close', code => {
  console.log(`child process close all stdio with code ${code}`)
})

ls.on('exit', code => {
  console.log(`child process exited with code ${code}`)
})

이벤트: `'disconnect'`

추가됨: v0.7.2

'disconnect' 이벤트는 부모 프로세스에서 subprocess.disconnect() 메서드 또는 자식 프로세스에서 process.disconnect() 메서드를 호출한 후 발생합니다. 연결이 끊긴 후에는 더 이상 메시지를 보내거나 받을 수 없으며 subprocess.connected 속성은 false가 됩니다.

이벤트: `'error'`

err <Error> 오류.

'error' 이벤트는 다음과 같은 경우 발생합니다.

프로세스를 생성할 수 없는 경우.
프로세스를 종료할 수 없는 경우.
자식 프로세스에 메시지를 보내는 데 실패한 경우.
signal 옵션을 통해 자식 프로세스가 중단된 경우.

'error' 이벤트 발생 후 'exit' 이벤트가 발생할 수도 있고 발생하지 않을 수도 있습니다. 'exit' 이벤트와 'error' 이벤트를 모두 수신하는 경우 핸들러 함수가 여러 번 실수로 호출되지 않도록 주의하십시오.

subprocess.kill() 및 subprocess.send()도 참조하십시오.

이벤트: `'exit'`

추가됨: v0.1.90

code <number> 자식 프로세스가 자체적으로 종료된 경우 종료 코드입니다.
signal <string> 자식 프로세스가 종료된 신호입니다.

'exit' 이벤트는 자식 프로세스가 종료된 후 발생합니다. 프로세스가 종료된 경우 code는 프로세스의 최종 종료 코드이고, 그렇지 않으면 null입니다. 프로세스가 신호 수신으로 인해 종료된 경우 signal은 신호의 문자열 이름이고, 그렇지 않으면 null입니다. 두 값 중 하나는 항상 null이 아닙니다.

'exit' 이벤트가 트리거되면 자식 프로세스의 stdio 스트림이 여전히 열려 있을 수 있습니다.

Node.js는 SIGINT 및 SIGTERM에 대한 신호 핸들러를 설정하며 Node.js 프로세스는 해당 신호를 수신한다고 해서 즉시 종료되지 않습니다. 대신 Node.js는 일련의 정리 작업을 수행한 다음 처리된 신호를 다시 발생시킵니다.

waitpid(2) 참조.

이벤트: `'message'`

추가됨: v0.5.9

message <Object> 구문 분석된 JSON 객체 또는 원시 값.
sendHandle <Handle> | <undefined> undefined 또는 net.Socket, net.Server, 또는 dgram.Socket 객체.

'message' 이벤트는 자식 프로세스가 process.send()를 사용하여 메시지를 보낼 때 트리거됩니다.

메시지는 직렬화 및 구문 분석 과정을 거칩니다. 결과 메시지는 원래 전송된 메시지와 다를 수 있습니다.

자식 프로세스 생성 시 serialization 옵션이 'advanced'로 설정된 경우 message 인수에는 JSON이 표현할 수 없는 데이터가 포함될 수 있습니다. 자세한 내용은 고급 직렬화를 참조하십시오.

이벤트: `'spawn'`

추가됨: v15.1.0, v14.17.0

'spawn' 이벤트는 자식 프로세스가 성공적으로 생성된 후 한 번 방출됩니다. 자식 프로세스가 성공적으로 생성되지 않으면 'spawn' 이벤트는 방출되지 않고 대신 'error' 이벤트가 방출됩니다.

방출되는 경우 'spawn' 이벤트는 다른 모든 이벤트와 stdout 또는 stderr를 통해 데이터를 수신하기 전에 발생합니다.

'spawn' 이벤트는 생성된 프로세스 내부에서 오류가 발생하더라도 발생합니다. 예를 들어, bash some-command가 성공적으로 생성되면 'spawn' 이벤트가 발생하지만 bash가 some-command를 생성하지 못할 수도 있습니다. 이러한 주의 사항은 { shell: true }를 사용하는 경우에도 적용됩니다.

`subprocess.channel`

[이력]

버전	변경 사항
v14.0.0	더 이상 객체가 실수로 네이티브 C++ 바인딩을 노출하지 않습니다.
v7.1.0	추가됨: v7.1.0

<Object> 자식 프로세스에 대한 IPC 채널을 나타내는 파이프.

subprocess.channel 속성은 자식의 IPC 채널에 대한 참조입니다. IPC 채널이 없으면 이 속성은 undefined입니다.

`subprocess.channel.ref()`

추가됨: v7.1.0

이 메서드는 .unref()가 이전에 호출된 경우 IPC 채널이 상위 프로세스의 이벤트 루프를 계속 실행하도록 합니다.

`subprocess.channel.unref()`

추가됨: v7.1.0

이 메서드는 IPC 채널이 상위 프로세스의 이벤트 루프를 유지하지 않도록 하며, 채널이 열려 있는 동안에도 완료될 수 있도록 합니다.

`subprocess.connected`

추가됨: v0.7.2

<boolean> subprocess.disconnect()가 호출된 후 false로 설정됩니다.

subprocess.connected 속성은 하위 프로세스로부터 메시지를 주고받을 수 있는지 여부를 나타냅니다. subprocess.connected가 false이면 더 이상 메시지를 주고받을 수 없습니다.

`subprocess.disconnect()`

추가됨: v0.7.2

상위 및 하위 프로세스 간의 IPC 채널을 닫아 다른 연결이 하위 프로세스를 유지하지 않는 경우 하위 프로세스가 정상적으로 종료될 수 있도록 합니다. 이 메서드를 호출한 후 상위 및 하위 프로세스(각각)의 subprocess.connected 및 process.connected 속성은 false로 설정되며 더 이상 프로세스 간에 메시지를 전달할 수 없습니다.

'disconnect' 이벤트는 수신 중인 메시지가 없을 때 발생합니다. 이는 대부분 subprocess.disconnect()를 호출한 직후에 트리거됩니다.

하위 프로세스가 Node.js 인스턴스인 경우(예: child_process.fork()를 사용하여 생성됨), 하위 프로세스 내에서 process.disconnect() 메서드를 호출하여 IPC 채널을 닫을 수도 있습니다.

`subprocess.exitCode`

<integer>

subprocess.exitCode 속성은 하위 프로세스의 종료 코드를 나타냅니다. 하위 프로세스가 여전히 실행 중인 경우 이 필드는 null입니다.

`subprocess.kill([signal])`

추가됨: v0.1.90

signal <number> | <string>
반환값: <boolean>

subprocess.kill() 메서드는 하위 프로세스에 신호를 보냅니다. 인수가 지정되지 않으면 프로세스에 'SIGTERM' 신호가 전송됩니다. 사용 가능한 신호 목록은 signal(7)을 참조하십시오. 이 함수는 kill(2)가 성공하면 true를, 그렇지 않으면 false를 반환합니다.

CJSESM

const { spawn } = require('node:child_process')
const grep = spawn('grep', ['ssh'])

grep.on('close', (code, signal) => {
  console.log(`child process terminated due to receipt of signal ${signal}`)
})

// 프로세스에 SIGHUP 전송.
grep.kill('SIGHUP')

import { spawn } from 'node:child_process'
const grep = spawn('grep', ['ssh'])

grep.on('close', (code, signal) => {
  console.log(`child process terminated due to receipt of signal ${signal}`)
})

// 프로세스에 SIGHUP 전송.
grep.kill('SIGHUP')

신호를 전달할 수 없는 경우 ChildProcess 객체는 'error' 이벤트를 발생시킬 수 있습니다. 이미 종료된 하위 프로세스에 신호를 보내는 것은 오류가 아니지만 예측할 수 없는 결과를 초래할 수 있습니다. 특히 프로세스 식별자(PID)가 다른 프로세스에 다시 할당된 경우 신호는 해당 프로세스에 전달되며 예기치 않은 결과를 초래할 수 있습니다.

함수가 kill로 호출되지만 하위 프로세스에 전달되는 신호가 실제로 프로세스를 종료하지 않을 수 있습니다.

kill(2)를 참조하십시오.

POSIX 신호가 존재하지 않는 Windows에서는 'SIGKILL', 'SIGTERM', 'SIGINT' 및 'SIGQUIT'을 제외한 signal 인수는 무시되며 프로세스는 항상 강제로 갑자기 종료됩니다('SIGKILL'과 유사). 자세한 내용은 신호 이벤트를 참조하십시오.

Linux에서 부모 프로세스를 종료하려고 할 때 부모 프로세스의 하위 프로세스는 종료되지 않습니다. 이는 셸에서 새 프로세스를 실행하거나 ChildProcess의 shell 옵션을 사용할 때 발생할 수 있습니다.

CJSESM

const { spawn } = require('node:child_process')

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ],
  {
    stdio: ['inherit', 'inherit', 'inherit'],
  }
)

setTimeout(() => {
  subprocess.kill() // 셸의 Node.js 프로세스를 종료하지 않습니다.
}, 2000)

import { spawn } from 'node:child_process'

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ],
  {
    stdio: ['inherit', 'inherit', 'inherit'],
  }
)

setTimeout(() => {
  subprocess.kill() // 셸의 Node.js 프로세스를 종료하지 않습니다.
}, 2000)

`subprocess[Symbol.dispose]()`

추가됨: v20.5.0, v18.18.0

[Stable: 1 - Experimental]

Stable: 1 Stability: 1 - Experimental

'SIGTERM'을 사용하여 subprocess.kill()을 호출합니다.

`subprocess.killed`

추가됨: v0.5.10

<boolean> subprocess.kill()이 자식 프로세스에 신호를 성공적으로 보낸 후 true로 설정됩니다.

subprocess.killed 속성은 자식 프로세스가 subprocess.kill()로부터 신호를 성공적으로 수신했는지 여부를 나타냅니다. killed 속성은 자식 프로세스가 종료되었음을 나타내지는 않습니다.

`subprocess.pid`

추가됨: v0.1.90

<integer> | <undefined>

자식 프로세스의 프로세스 식별자(PID)를 반환합니다. 오류로 인해 자식 프로세스 생성에 실패하면 값은 undefined이고 error 이벤트가 발생합니다.

CJSESM

const { spawn } = require('node:child_process')
const grep = spawn('grep', ['ssh'])

console.log(`Spawned child pid: ${grep.pid}`)
grep.stdin.end()

import { spawn } from 'node:child_process'
const grep = spawn('grep', ['ssh'])

console.log(`Spawned child pid: ${grep.pid}`)
grep.stdin.end()

`subprocess.ref()`

추가됨: v0.7.10

subprocess.unref()를 호출한 후 subprocess.ref()를 호출하면 자식 프로세스에 대한 제거된 참조 카운트가 복원되어 부모 프로세스가 자식 프로세스가 종료될 때까지 기다리도록 합니다.

CJSESM

const { spawn } = require('node:child_process')
const process = require('node:process')

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
})

subprocess.unref()
subprocess.ref()

import { spawn } from 'node:child_process'
import process from 'node:process'

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
})

subprocess.unref()
subprocess.ref()

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

[이력]

버전	변경 사항
v5.8.0	`options` 매개변수, 특히 `keepOpen` 옵션이 지원됩니다.
v5.0.0	이 메서드는 이제 흐름 제어를 위해 부울 값을 반환합니다.
v4.0.0	`callback` 매개변수가 지원됩니다.
v0.5.9	추가됨: v0.5.9

message <Object>
sendHandle <Handle> | <undefined> undefined 또는 net.Socket, net.Server, 또는 dgram.Socket 객체.
options <Object> options 인수는(있는 경우) 특정 유형의 핸들을 보내는 매개변수를 지정하는 데 사용되는 객체입니다. options는 다음 속성을 지원합니다.
- keepOpen <boolean> net.Socket 인스턴스를 전달할 때 사용할 수 있는 값입니다. true이면 소켓이 전송 프로세스에서 열린 상태로 유지됩니다. 기본값: false.
callback <Function>
반환값: <boolean>

부모 프로세스와 자식 프로세스 간에 IPC 채널이 설정된 경우(즉, child_process.fork()를 사용하는 경우) subprocess.send() 메서드를 사용하여 자식 프로세스에 메시지를 보낼 수 있습니다. 자식 프로세스가 Node.js 인스턴스인 경우 이러한 메시지는 'message' 이벤트를 통해 수신할 수 있습니다.

메시지는 직렬화 및 구문 분석을 거칩니다. 결과 메시지는 원래 전송된 메시지와 다를 수 있습니다.

예를 들어, 부모 스크립트에서:

CJSESM

const { fork } = require('node:child_process')
const forkedProcess = fork(`${__dirname}/sub.js`)

forkedProcess.on('message', message => {
  console.log('PARENT got message:', message)
})

// 자식이 다음을 출력하도록 합니다: CHILD got message: { hello: 'world' }
forkedProcess.send({ hello: 'world' })

import { fork } from 'node:child_process'
const forkedProcess = fork(`${import.meta.dirname}/sub.js`)

forkedProcess.on('message', message => {
  console.log('PARENT got message:', message)
})

// 자식이 다음을 출력하도록 합니다: CHILD got message: { hello: 'world' }
forkedProcess.send({ hello: 'world' })

그리고 자식 스크립트인 'sub.js'는 다음과 같습니다.

process.on('message', message => {
  console.log('CHILD got message:', message)
})

// 부모가 다음을 출력하도록 합니다: PARENT got message: { foo: 'bar', baz: null }
process.send({ foo: 'bar', baz: NaN })

자식 Node.js 프로세스는 자식 프로세스가 부모 프로세스에 메시지를 다시 보낼 수 있도록 하는 자체의 process.send() 메서드를 갖게 됩니다.

{cmd: 'NODE_foo'} 메시지를 보낼 때 특별한 경우가 있습니다. cmd 속성에 NODE_ 접두사가 포함된 메시지는 Node.js 코어 내에서 사용하기 위해 예약되어 있으며 자식의 'message' 이벤트에서 방출되지 않습니다. 대신 이러한 메시지는 'internalMessage' 이벤트를 사용하여 방출되고 Node.js에서 내부적으로 사용됩니다. 애플리케이션은 예고 없이 변경될 수 있으므로 이러한 메시지를 사용하거나 'internalMessage' 이벤트를 수신 대기하지 않아야 합니다.

subprocess.send()에 전달될 수 있는 선택적 sendHandle 인수는 자식 프로세스에 TCP 서버 또는 소켓 객체를 전달하기 위한 것입니다. 자식 프로세스는 'message' 이벤트에 등록된 콜백 함수에 전달된 두 번째 인수로 객체를 수신합니다. 소켓에서 수신되고 버퍼링된 데이터는 자식에게 전송되지 않습니다. Windows에서는 IPC 소켓 전송이 지원되지 않습니다.

선택적 callback은 메시지가 전송된 후 자식 프로세스가 메시지를 수신했을 수도 있기 전에 호출되는 함수입니다. 이 함수는 성공 시 단일 인수 null 또는 실패 시 Error 객체를 사용하여 호출됩니다.

callback 함수가 제공되지 않고 메시지를 보낼 수 없는 경우 ChildProcess 객체에서 'error' 이벤트가 방출됩니다. 예를 들어 자식 프로세스가 이미 종료된 경우 발생할 수 있습니다.

채널이 닫히거나 전송되지 않은 메시지의 백로그가 더 이상 전송하는 것이 현명하지 않을 정도로 임계값을 초과하는 경우 subprocess.send()는 false를 반환합니다. 그렇지 않으면 메서드는 true를 반환합니다. callback 함수를 사용하여 흐름 제어를 구현할 수 있습니다.

예시: 서버 객체 전송

아래 예시와 같이 sendHandle 인수를 사용하여 TCP 서버 객체의 핸들을 자식 프로세스에 전달할 수 있습니다.

CJSESM

const { fork } = require('node:child_process')
const { createServer } = require('node:net')

const subprocess = fork('subprocess.js')

// 서버 객체를 열고 핸들을 전송합니다.
const server = createServer()
server.on('connection', socket => {
  socket.end('handled by parent')
})
server.listen(1337, () => {
  subprocess.send('server', server)
})

import { fork } from 'node:child_process'
import { createServer } from 'node:net'

const subprocess = fork('subprocess.js')

// 서버 객체를 열고 핸들을 전송합니다.
const server = createServer()
server.on('connection', socket => {
  socket.end('handled by parent')
})
server.listen(1337, () => {
  subprocess.send('server', server)
})

그러면 자식 프로세스는 서버 객체를 다음과 같이 수신합니다.

process.on('message', (m, server) => {
  if (m === 'server') {
    server.on('connection', socket => {
      socket.end('handled by child')
    })
  }
})

이제 서버가 부모와 자식 프로세스 간에 공유되므로 일부 연결은 부모가, 일부는 자식이 처리할 수 있습니다.

위의 예시는 node:net 모듈을 사용하여 생성된 서버를 사용하지만, node:dgram 모듈 서버는 'connection' 대신 'message' 이벤트를 수신하고 server.listen() 대신 server.bind()를 사용하는 것을 제외하고는 동일한 워크플로우를 사용합니다. 그러나 이것은 Unix 플랫폼에서만 지원됩니다.

예시: 소켓 객체 전송

마찬가지로, sendHandler 인수를 사용하여 소켓의 핸들을 자식 프로세스에 전달할 수 있습니다. 아래 예시는 각각 "일반" 또는 "특별" 우선 순위로 연결을 처리하는 두 개의 자식을 생성합니다.

CJSESM

const { fork } = require('node:child_process')
const { createServer } = require('node:net')

const normal = fork('subprocess.js', ['normal'])
const special = fork('subprocess.js', ['special'])

// 서버를 열고 자식에게 소켓을 전송합니다. 자식 프로세스에 소켓을 전송하기 전에 소켓이 읽히지 않도록 `pauseOnConnect`를 사용합니다.
const server = createServer({ pauseOnConnect: true })
server.on('connection', socket => {
  // 특별 우선 순위인 경우...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket)
    return
  }
  // 일반 우선 순위입니다.
  normal.send('socket', socket)
})
server.listen(1337)

import { fork } from 'node:child_process';
import { createServer } = require('node:net');

const normal = fork('subprocess.js', ['normal']);
const special = fork('subprocess.js', ['special']);

// 서버를 열고 자식에게 소켓을 전송합니다. 자식 프로세스에 소켓을 전송하기 전에 소켓이 읽히지 않도록 `pauseOnConnect`를 사용합니다.
const server = createServer({ pauseOnConnect: true });
server.on('connection', (socket) => {

  // 특별 우선 순위인 경우...
  if (socket.remoteAddress === '74.125.127.100') {
    special.send('socket', socket);
    return;
  }
  // 일반 우선 순위입니다.
  normal.send('socket', socket);
});
server.listen(1337);

subprocess.js는 이벤트 콜백 함수에 전달된 두 번째 인수로 소켓 핸들을 수신합니다.

process.on('message', (m, socket) => {
  if (m === 'socket') {
    if (socket) {
      // 클라이언트 소켓이 존재하는지 확인합니다.
      // 소켓이 전송된 시점과 자식 프로세스에서 수신된 시점 사이에 소켓이 닫힐 수 있습니다.
      socket.end(`Request handled with ${process.argv[2]} priority`)
    }
  }
})

자식 프로세스에 전달된 소켓에 .maxConnections를 사용하지 마십시오. 부모는 소켓이 파괴될 때를 추적할 수 없습니다.

자식 프로세스의 모든 'message' 핸들러는 연결이 자식에게 전송되는 데 걸리는 시간 동안 연결이 닫혔을 수 있으므로 socket이 존재하는지 확인해야 합니다.

`subprocess.signalCode`

<문자열> | <null>

subprocess.signalCode 속성은 자식 프로세스가 수신한 시그널(있는 경우)을 나타내며, 없으면 null입니다.

`subprocess.spawnargs`

<배열>

subprocess.spawnargs 속성은 자식 프로세스가 실행된 명령줄 인수의 전체 목록을 나타냅니다.

`subprocess.spawnfile`

<문자열>

subprocess.spawnfile 속성은 실행된 자식 프로세스의 실행 파일 이름을 나타냅니다.

child_process.fork()의 경우, 해당 값은 process.execPath와 같습니다. child_process.spawn()의 경우, 해당 값은 실행 파일의 이름입니다. child_process.exec()의 경우, 해당 값은 자식 프로세스가 실행된 셸의 이름입니다.

`subprocess.stderr`

추가됨: v0.1.90

<stream.Readable> | <null> | <undefined>

자식 프로세스의 stderr을 나타내는 Readable Stream입니다.

자식 프로세스가 stdio[2]를 'pipe' 이외의 값으로 생성된 경우, 이 값은 null이 됩니다.

subprocess.stderr는 subprocess.stdio[2]의 별칭입니다. 두 속성 모두 동일한 값을 참조합니다.

자식 프로세스를 성공적으로 생성할 수 없는 경우 subprocess.stderr 속성은 null 또는 undefined가 될 수 있습니다.

`subprocess.stdin`

추가됨: v0.1.90

<stream.Writable> | <null> | <undefined>

자식 프로세스의 stdin을 나타내는 Writable Stream입니다.

자식 프로세스가 모든 입력을 읽기를 기다리는 경우 end()를 통해 이 스트림이 닫힐 때까지 자식 프로세스는 계속되지 않습니다.

stdio[0]이 'pipe' 이외의 값으로 설정되어 자식 프로세스가 생성된 경우 null이 됩니다.

subprocess.stdin은 subprocess.stdio[0]의 별칭입니다. 두 속성 모두 동일한 값을 참조합니다.

자식 프로세스를 성공적으로 생성할 수 없는 경우 subprocess.stdin 속성은 null 또는 undefined가 될 수 있습니다.

`subprocess.stdio`

추가됨: v0.7.10

<Array>

child_process.spawn()에 전달된 stdio 옵션의 위치에 해당하는 자식 프로세스에 대한 파이프의 스파스 배열이며, 'pipe' 값으로 설정된 경우입니다. subprocess.stdio[0], subprocess.stdio[1], 및 subprocess.stdio[2]는 각각 subprocess.stdin, subprocess.stdout 및 subprocess.stderr로도 사용할 수 있습니다.

다음 예에서는 자식의 fd 1 (stdout)만 파이프로 구성되므로 부모의 subprocess.stdio[1]만 스트림이고, 배열의 다른 모든 값은 null입니다.

CJSESM

const assert = require('node:assert')
const fs = require('node:fs')
const child_process = require('node:child_process')

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // 부모의 stdin을 자식에 사용합니다.
    'pipe', // 자식의 stdout을 부모에게 파이프합니다.
    fs.openSync('err.out', 'w'), // 자식의 stderr을 파일로 직접 보냅니다.
  ],
})

assert.strictEqual(subprocess.stdio[0], null)
assert.strictEqual(subprocess.stdio[0], subprocess.stdin)

assert(subprocess.stdout)
assert.strictEqual(subprocess.stdio[1], subprocess.stdout)

assert.strictEqual(subprocess.stdio[2], null)
assert.strictEqual(subprocess.stdio[2], subprocess.stderr)

import assert from 'node:assert'
import fs from 'node:fs'
import child_process from 'node:child_process'

const subprocess = child_process.spawn('ls', {
  stdio: [
    0, // 부모의 stdin을 자식에 사용합니다.
    'pipe', // 자식의 stdout을 부모에게 파이프합니다.
    fs.openSync('err.out', 'w'), // 자식의 stderr을 파일로 직접 보냅니다.
  ],
})

assert.strictEqual(subprocess.stdio[0], null)
assert.strictEqual(subprocess.stdio[0], subprocess.stdin)

assert(subprocess.stdout)
assert.strictEqual(subprocess.stdio[1], subprocess.stdout)

assert.strictEqual(subprocess.stdio[2], null)
assert.strictEqual(subprocess.stdio[2], subprocess.stderr)

자식 프로세스를 성공적으로 생성할 수 없는 경우 subprocess.stdio 속성은 undefined가 될 수 있습니다.

`subprocess.stdout`

추가됨: v0.1.90

<stream.Readable> | <null> | <undefined>

자식 프로세스의 stdout을 나타내는 Readable Stream입니다.

자식 프로세스가 stdio[1]을 'pipe' 이외의 값으로 설정하여 생성된 경우, 이 값은 null이 됩니다.

subprocess.stdout은 subprocess.stdio[1]의 별칭입니다. 두 속성은 동일한 값을 참조합니다.

CJSESM

const { spawn } = require('node:child_process')

const subprocess = spawn('ls')

subprocess.stdout.on('data', data => {
  console.log(`Received chunk ${data}`)
})

import { spawn } from 'node:child_process'

const subprocess = spawn('ls')

subprocess.stdout.on('data', data => {
  console.log(`Received chunk ${data}`)
})

자식 프로세스를 성공적으로 생성할 수 없는 경우 subprocess.stdout 속성은 null 또는 undefined가 될 수 있습니다.

`subprocess.unref()`

추가됨: v0.7.10

기본적으로 부모 프로세스는 분리된 자식 프로세스가 종료될 때까지 기다립니다. 지정된 subprocess가 종료될 때까지 부모 프로세스가 기다리지 않도록 하려면 subprocess.unref() 메서드를 사용합니다. 이렇게 하면 부모의 이벤트 루프가 자식 프로세스를 참조 카운트에 포함하지 않게 되어 자식과 부모 프로세스 간에 IPC 채널이 설정되어 있지 않으면 부모가 자식과 독립적으로 종료될 수 있습니다.

CJSESM

const { spawn } = require('node:child_process')
const process = require('node:process')

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
})

subprocess.unref()

import { spawn } from 'node:child_process'
import process from 'node:process'

const subprocess = spawn(process.argv[0], ['child_program.js'], {
  detached: true,
  stdio: 'ignore',
})

subprocess.unref()

`maxBuffer` 및 유니코드

maxBuffer 옵션은 stdout 또는 stderr에서 허용되는 최대 바이트 수를 지정합니다. 이 값을 초과하면 자식 프로세스가 종료됩니다. 이는 UTF-8 또는 UTF-16과 같은 멀티바이트 문자 인코딩을 포함하는 출력에 영향을 미칩니다. 예를 들어, console.log('中文测试')는 4개의 문자만 있지만 stdout에 13바이트의 UTF-8 인코딩된 바이트를 보냅니다.

셸 요구 사항

셸은 -c 스위치를 이해해야 합니다. 셸이 'cmd.exe'인 경우 /d /s /c 스위치를 이해해야 하며 명령줄 구문 분석이 호환되어야 합니다.

기본 Windows 셸

Microsoft는 %COMSPEC%에 루트 환경에서 'cmd.exe'의 경로가 포함되어야 한다고 지정하지만, 자식 프로세스는 항상 동일한 요구 사항을 따르는 것은 아닙니다. 따라서 셸을 생성할 수 있는 child_process 함수에서 process.env.ComSpec을 사용할 수 없는 경우 'cmd.exe'가 대체값으로 사용됩니다.

고급 직렬화

추가됨: v13.2.0, v12.16.0

자식 프로세스는 node:v8 모듈의 직렬화 API를 기반으로 하며, HTML 구조화된 복제 알고리즘을 기반으로 하는 IPC를 위한 직렬화 메커니즘을 지원합니다. 이는 일반적으로 더 강력하며 BigInt, Map 및 Set, ArrayBuffer 및 TypedArray, Buffer, Error, RegExp 등 더 많은 기본 JavaScript 객체 유형을 지원합니다.

그러나 이 형식은 JSON의 완전한 상위 집합이 아니며, 예를 들어 이러한 기본 유형의 객체에 설정된 속성은 직렬화 단계를 통해 전달되지 않습니다. 또한, 전달된 데이터의 구조에 따라 성능이 JSON과 동일하지 않을 수 있습니다. 따라서 이 기능을 사용하려면 child_process.spawn() 또는 child_process.fork()를 호출할 때 serialization 옵션을 'advanced'로 설정해야 합니다.

하위 프로세스 ​

비동기 프로세스 생성 ​

Windows에서 .bat 및 .cmd 파일 생성 ​

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

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

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

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

options.detached ​

options.stdio ​

동기 프로세스 생성 ​

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

child_process.execSync(command[, options]) ​

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

클래스: ChildProcess ​

이벤트: 'close' ​

이벤트: 'disconnect' ​

이벤트: 'error' ​

이벤트: 'exit' ​

이벤트: 'message' ​

이벤트: 'spawn' ​

subprocess.channel ​

subprocess.channel.ref() ​

subprocess.channel.unref() ​

subprocess.connected ​

subprocess.disconnect() ​

subprocess.exitCode ​

subprocess.kill([signal]) ​

subprocess[Symbol.dispose]() ​

subprocess.killed ​

subprocess.pid ​

subprocess.ref() ​

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

예시: 서버 객체 전송 ​

예시: 소켓 객체 전송 ​

subprocess.signalCode ​

subprocess.spawnargs ​

subprocess.spawnfile ​

subprocess.stderr ​

subprocess.stdin ​

subprocess.stdio ​

subprocess.stdout ​

subprocess.unref() ​

maxBuffer 및 유니코드 ​

셸 요구 사항 ​

기본 Windows 셸 ​

고급 직렬화 ​

하위 프로세스

비동기 프로세스 생성

Windows에서 `.bat` 및 `.cmd` 파일 생성

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

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

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

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

`options.detached`

`options.stdio`

동기 프로세스 생성

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

`child_process.execSync(command[, options])`

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

클래스: `ChildProcess`

이벤트: `'close'`

이벤트: `'disconnect'`

이벤트: `'error'`

이벤트: `'exit'`

이벤트: `'message'`

이벤트: `'spawn'`

`subprocess.channel`

`subprocess.channel.ref()`

`subprocess.channel.unref()`

`subprocess.connected`

`subprocess.disconnect()`

`subprocess.exitCode`

`subprocess.kill([signal])`

`subprocess[Symbol.dispose]()`

`subprocess.killed`

`subprocess.pid`

`subprocess.ref()`

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

예시: 서버 객체 전송

예시: 소켓 객체 전송

`subprocess.signalCode`

`subprocess.spawnargs`

`subprocess.spawnfile`

`subprocess.stderr`

`subprocess.stdin`

`subprocess.stdio`

`subprocess.stdout`

`subprocess.unref()`

`maxBuffer` 및 유니코드

셸 요구 사항

기본 Windows 셸

고급 직렬화