child_process

child_process ejecuta programas externos desde Node; prefiere spawn con arrays de argumentos explícitos, comprende los modos stdio y evita la inyección de shell al envolver herramientas CLI.

Receta

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']);

Cuándo usarlo:

• Procesamiento de imágenes a través de ffmpeg CLI
• Operaciones Git en scripts de despliegue
• Ejecución de formateadores de lenguaje en hooks de pre-commit
• Aislamiento de código no confiable en un proceso de SO separado (con sandbox más allá de Node)

Ejemplo de funcionamiento

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 exited ${code}`);
  return stdout.trim();
}
 
// Peligroso - no hagas esto con entrada de usuario:
// 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 failed ${code}`);
}

Lo que esto demuestra:

• El array de argumentos pasa literales a execve sin interpretación de shell
• Recopila stdout a través de fragmentos de stream, no límites de búfer exec para salida grande
• Redirige el stdout del hijo a un archivo con pipeline para contrapresión
• shell: true solo para comandos fijos confiables, nunca con cadenas de usuario

Análisis profundo

Cómo funciona

• spawn - transmite stdio, regresa inmediatamente, evento exit con código.
• exec - almacena stdout/stderr en búfer, invoca shell por defecto - riesgo de inyección.
• execFile - sin shell, salida almacenada en búfer con maxBuffer por defecto de 1MB.
• fork - hijo especial de Node con canal IPC - patrón heredado antes de worker_threads.

Comparación de API

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 de la plataforma: los grupos de procesos de Linux necesitan detached: true en spawn.

Errores comunes

• shell: true + entrada de usuario - inyección de comandos. Solución: spawn(cmd, [arg1, arg2]) sin shell.
• exec maxBuffer excedido - lanza un error en stdout grande. Solución: spawn con streams.
• No recolectar zombies - siempre adjuntar un manejador exit o esperar la salida en supervisores de larga duración.
• Stdio heredado en demonios - el hijo mantiene el TTY abierto. Solución: stdio: 'ignore' para trabajos en segundo plano.
• Comillas en rutas de Windows - sigue usando la forma de array; evita el escape manual de comillas en cadenas de shell.

Alternativas

Preguntas frecuentes

Relacionado

• worker_threads - CPU en proceso
• Process Signals & Shutdown - matar hijos limpiamente
• Processes Best Practices - lista de verificación de seguridad
• Callbacks vs Promises Migration - promisify execFile

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.