Node.js child_process maxBuffer 超限错误排查

症状

错误信息直接点名机制：Error: maxBuffer exceeded，而默认上限解释了出现时机。exec 的定位就是在回调里交付完整输出，因此必须把它全部缓存在内存里，默认天花板是 1 MB。自己测一下命令输出体量：git log –oneline | wc -c 得到比如 3,140,000 字节，对着 1 MB 的限制，子进程是在输出到一半时被杀掉的。这也解释了为什么同一条命令在终端里好好的——shell 从不做有上限的缓冲。代码数月未改、故障随数据增长渐渐出现，正是这个模式。

诊断思路

　　先量出真实输出字节数并与 1048576 对比，超限即可立刻定罪；再 grep maxBuffer 确认代码里配的是默认值还是前人设过的自定义值；最后判断输出是否真的需要进内存——如果下游只是逐行迭代，流或文件在所有维度上都优于更大的缓冲。stderr 用 2>&1 重定向进 stdout 会让缓冲体量翻倍，是常见的隐形放大器。

根因

　　child_process.exec 为了便利把整个 stdout 收进单个缓冲区，一旦超过 maxBuffer 就中止子进程。输出体量随仓库或集群规模增长越过上限，曾经成功的命令如今在流到一半时死亡，且不会交付任何部分数据。

修复与验证

　　输出确实有界时，按“实测体量加余量”的理由调大 maxBuffer，而不是拍一个魔法数字；输出随数据增长时，彻底停止缓冲：改用 spawn 配合 readline 逐行消费，一次只在内存里保留一行；转储类大产物用 pipeline 直接流进文件再解析。验证时以 shell 为基准：终端里 wc -l 得到的行数必须与 Node 路径一致；运行期间观察 heapUsed——流式变体应保持平坦且与输出规模无关，缓冲式变体则随体量线性增长；再把输出放大一倍重跑，确认流式路径的内存曲线纹丝不动。把 maxBuffer 设成天文数字是用无界内存换不崩溃，负载之下必出事故。

代码示例

Error: maxBuffer exceeded
    at Socket.<anonymous> (node:child_process:429:20)

git log --oneline | wc -c   # e.g. 3_140_000 bytes

exec(cmd, { maxBuffer: 16 * 1024 * 1024 }, callback); // measured 3 MB + headroom

import { spawn } from 'node:child_process';
import { readline } from 'node:readline/promises';

const child = spawn('git', ['log', '--oneline']);
const rl = readline.createInterface({ input: child.stdout });
let count = 0;
for await (const line of rl) {
  count += 1; // one line in memory at a time
}