Node.js构建CLI工具：子进程stdout无法实时输出问题排查

问题描述 #

开发Node.js CLI工具时，使用child_process.spawn或exec创建子进程执行系统命令，发现子进程的stdout无法实时打印，只有当Promise resolve后才会一次性输出内容。相关实现代码如下：

基于spawn的原始实现 #

import * as Child_process from "child_process";

export function asyncExec(command: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = Child_process.spawn(command, { shell: true });
    child.stdout?.pipe(process.stdout);
    child.on("error", (err) => {
      reject(err);
    });
    child.on("exit", (code) => {
      if (code === 0) {
        resolve(code.toString());
      } else {
        reject(new Error(`Process exited with code ${code}`));
      }
    });
  });
}

基于exec的原始实现 #

import * as Child_process from "child_process";

export function asyncExec(command: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = Child_process.exec(command, (err, stdout, stderr) => {
      if (err) {
        reject(new Error(stderr || err.message));
      } else {
        resolve(stdout);
      }
    });
    child.stdout?.pipe(process.stdout);
  });
}

原因分析 #

1. exec的内置缓冲机制：exec方法默认会将子进程的stdout和stderr全部缓存到内存中，直到进程完全退出后才通过回调返回结果。即便调用了pipe方法，输出内容也会先被exec缓存，无法实时流向父进程的stdout。

2. 非TTY环境的块缓冲：无论是spawn还是exec，Node.js创建的子进程默认运行在非交互式终端（非TTY）环境下。大部分命令行工具在这种环境下会使用块缓冲策略——只有当输出缓冲区填满或进程退出时，才会输出内容，而非逐行实时输出。

修复方案 #

方案1：继承父进程的stdio（最简单有效） #

通过设置子进程的stdio选项为['inherit', 'inherit', 'inherit']，让子进程直接使用父进程的标准输入、输出和错误流。这会让子进程认为自己运行在TTY环境下，自动切换为行缓冲，从而实现实时输出。

修复后的spawn实现

import * as Child_process from "child_process";

export function asyncExec(command: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = Child_process.spawn(command, { 
      shell: true,
      stdio: ['inherit', 'inherit', 'inherit']
    });

    child.on("error", (err) => reject(err));
    child.on("exit", (code) => {
      if (code === 0) {
        resolve(code.toString());
      } else {
        reject(new Error(`Process exited with code ${code}`));
      }
    });
  });
}

修复后的exec实现

import * as Child_process from "child_process";

export function asyncExec(command: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = Child_process.exec(command, {
      stdio: ['inherit', 'inherit', 'inherit']
    }, (err, stdout, stderr) => {
      if (err) {
        reject(new Error(stderr || err.message));
      } else {
        resolve(stdout);
      }
    });
  });
}

方案2：手动监听流式输出（需自定义处理时使用） #

如果需要对子进程的输出做过滤、修改等自定义处理，可以监听stdout的data事件，或使用readline模块逐行读取输出，强制实时打印内容，同时规避块缓冲问题。

import * as Child_process from "child_process";
import { createInterface } from "readline";

export function asyncExec(command: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const child = Child_process.spawn(command, { shell: true });
    let fullOutput = '';

    // 用readline逐行读取，确保实时输出每一行
    const rl = createInterface({
      input: child.stdout!,
      crlfDelay: Infinity
    });

    rl.on('line', (line) => {
      console.log(line);
      fullOutput += line + '\n';
    });

    // 实时打印错误输出
    child.stderr?.on('data', (data) => {
      process.stderr.write(data);
    });

    child.on("error", (err) => reject(err));
    child.on("exit", (code) => {
      rl.close();
      if (code === 0) {
        resolve(fullOutput.trim());
      } else {
        reject(new Error(`Process exited with code ${code}`));
      }
    });
  });
}

额外提示：针对特定命令的缓冲关闭 #

如果调用的是Python、Node.js等脚本命令，可通过命令参数强制关闭缓冲：

• Python：添加-u参数，如python -u your_script.py
• Node.js：脚本内使用process.stdout.write()代替console.log()（console.log默认有缓冲），或启动时添加--no-buffer参数（部分版本支持）

内容的提问来源于stack exchange，提问作者Eitank