child_process

child_process executa programas externos a partir do Node - prefira spawn com arrays de argumentos explícitos, entenda os modos stdio e evite injeção de shell ao envolver ferramentas CLI.

Receita

import { spawn } from 'node:child_process';
 
const child = spawn('git', ['rev-parse', 'HEAD'], { stdio: ['ignore', 'pipe', 'pipe'] });

import { promisify } from 'node:util';
import { execFile } from 'node:child_process';
 
const execFileAsync = promisify(execFile);
const { stdout } = await execFileAsync('node', ['--version']);

Quando usar isso:

• Processamento de imagem via ffmpeg CLI
• Operações Git em scripts de deploy
• Execução de formatadores de linguagem em hooks de pre-commit
• Isolamento de código não confiável em um processo OS separado (com sandbox além do Node)

Exemplo Funcional

import { spawn } from 'node:child_process';
import { once } from 'node:events';
 
async function runGitHash(): Promise<string> {
  const child = spawn('git', ['rev-parse', 'HEAD'], {
    stdio: ['ignore', 'pipe', 'pipe'],
  });
 
  let stdout = '';
  child.stdout.on('data', (chunk: Buffer) => {
    stdout += chunk.toString('utf8');
  });
 
  const [code] = await once(child, 'exit');
  if (code !== 0) throw new Error(`git saiu com código ${code}`);
  return stdout.trim();
}
 
// Perigoso - não faça isso com entrada do usuário:
// spawn(`git rev-parse ${userBranch}`, { shell: true });

import { pipeline } from 'node:stream/promises';
import { spawn } from 'node:child_process';
import { createWriteStream } from 'node:fs';
 
async function compressWithGzip(input: string, output: string): Promise<void> {
  const gzip = spawn('gzip', ['-c', input], { stdio: ['ignore', 'pipe', 'inherit'] });
  await pipeline(gzip.stdout, createWriteStream(output));
  const code = await new Promise<number>((res) => gzip.on('exit', res));
  if (code !== 0) throw new Error(`gzip falhou ${code}`);
}

O que isso demonstra:

• O array de argumentos passa literais para execve sem interpretação do shell
• Coleta de stdout via chunks de stream - não os limites de buffer do exec para saída grande
• Pipe de stdout do child para arquivo com pipeline para backpressure
• shell: true apenas para comandos fixos confiáveis - nunca com strings de usuário

Mergulho Profundo

Como Funciona

• spawn - streams stdio, retorna imediatamente, evento exit com código.
• exec - bufferiza stdout/stderr, invoca o shell por padrão - risco de injeção.
• execFile - sem shell, saída bufferizada com maxBuffer padrão de 1MB.
• fork - child especial do Node com canal IPC - padrão legado antes de worker_threads.

Comparação de APIs

Notas de TypeScript

import type { ChildProcess } from 'node:child_process';
 
export function killProcessTree(child: ChildProcess): void {
  if (child.pid) process.kill(-child.pid, 'SIGTERM');
}

Específico da plataforma - grupos de processos Linux precisam de detached: true no spawn.

Armadilhas

• shell: true + entrada do usuário - injeção de comando. Correção: spawn(cmd, [arg1, arg2]) sem shell.
• exec maxBuffer excedido - lança erro em stdout grande. Correção: spawn com streams.
• Não coletar zombies - sempre anexe um manipulador exit ou aguarde a saída em supervisores de longa duração.
• Stdio herdado em daemons - o child mantém o TTY aberto. Correção: stdio: 'ignore' para jobs em background.
• Aspas de caminho no Windows - ainda use a forma de array; evite escapar aspas manualmente em strings de shell.

Alternativas

FAQs

Relacionado

• worker_threads - CPU em processo
• Process Signals & Shutdown - matando children de forma limpa
• Process Best Practices - checklist de segurança
• Callbacks vs Promises Migration - promisify execFile

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, e NestJS 11.