为什么需要输出捕获？

子进程往往会产生大量日志或调试信息。若不加控制，可能出现两大痛点：

• 硬盘空间耗尽：单条命令一次性写入数百 MB 或 GB 的日志。导致宿主机磁盘被撑爆，
• 审计与排查困难：日志文件过大或无限增长，使得后期定位问题变得费时且不可靠。

需要在 stdout/stderr 输出时既能实时落盘，又能限制总字节数。

两项主要需求

1. 落盘：将子进程的所有输出持久化到文件，方便审计和事后查看。
2. 截断：给每个输出通道设定最大字节数，超过后丢弃多余内容并标记为已截断。

createOutputCapture——主要函数

/**
* 创建一个带字节上限的输出捕获器。老实说，*
* 子进程的 stdout/stderr 会被流式写入文件。但写入量不能超过 maxBytes。* 超过上限后后续数据会被丢弃，并将 truncated 标记为 true。*
* @param filePath - 输出文件的完整方法
* @param maxBytes - 最大允许写入的字节数
* @returns OutputCapture 实例。用于追加数据和读取状态
*/
export function createOutputCapture: OutputCapture {
// 确保输出目录存在
fs.mkdirSync,{ recursive: true });// 以同步写方式打开文件
const fd = fs.openSync;// 字节上限，最小为0
const byteLimit = Math.max;按理说，let bytesWritten = 0;// 已写入字节数
let truncated = false;// 是否已触发截断
let closed = false;// 文件是否已关闭
/** 将 Buffer 写入文件 */
function appendBuffer: void {
if return;// 已关闭或无数据
const remaining = byteLimit - bytesWritten;if {
truncated = true;return，老实说，// 空间已满
}
const slice = chunk.length> remaining
chunk.subarray
: chunk;fs.writeSync;bytesWritten += slice.length;if {
truncated = true;// 部分数据被截断
}
}
/** 将字符串写入文件 */
function appendText: void {
appendBuffer);}
/** 销毁句柄，释放资源 */
function close: void {
if return;fs.closeSync;closed = true;}
return {
filePath,get bytesWritten { return bytesWritten;},get truncated { return truncated;},appendBuffer,appendText,close,};}

再看初始化。打开文件

fs.mkdirSync,{ recursive: true });const fd = fs.openSync;

• SYNCHRONOUS 的 openSync — 比传统的 CreateWriteStream  
• —  
• — 

appendBuffer——主要写入逻辑

function appendBuffer: void { if return;const remaining = byteLimit - bytesWritten;if { truncated = true;return，} const slice = chunk.length> remaining?chunk.subarray : chunk;fs.writeSync;bytesWritten += slice.length;if { truncated = true; } }

• 为何使用 fs.writeSync: 回调来自 'data',同步保证顺序且无回调嵌套。异步可能导致乱序或竞争条件。
• Dedupe logic:* 若剩余空间不足，只切片前面可用部分；若完全不足，则直接标记截断并丢弃整个块。
• * 一次性把所有有效内容同步写入，提高 I/O 效率。

appendText——文本封装助手

ts function appendText{ appendBuffer);}

• * 对于纯文本输入。可直接使用此方法，无需手动转换成 Buffer。
* 内部仍使用同步 write 保持一致性。 * 避免多处出现编码转换错误。不过， * 对 UTF‑8 多字节字符安全处理。 * 简化调用方代码，让业务关注业务而非 I/O。 * 在高并发场景下仍保持低延迟。怎么说呢， * 与 appendBuffer 一致的错误处理与截断逻辑。 * 在 Node.js 单线程模型下无锁竞争风险。`

`

close——安全释放资源

function close{ ifreturn;// idempotent fs.closeSync; closed=true;}`

• * 调用一次即可；调用不会抛错，也不会重复关闭 FD.
— ，Avoid double-close bugs. — Simplify lifecycle management.`

Reasoning:	Implementation detail:
Prevent multiple close calls	Idempotent flag check
Avoid resource leaks	Explicit sync close

使用示例

`

const stdoutCapture=createOutputCapture;const stderrCapture=createOutputCapture;

const result=await runSandboxedCommand({ commandSpec。io:{ onStdout:=>stdoutCapture.appendBuffer,onStderr:=>stderrCapture.appendBuffer,},});不过，

stdoutCapture.close;说起来，stderrCapture.close;不过，

return{ ...result,stdoutBytes:stdoutCapture.bytesWritten,stderrBytes:stderrCapture.bytesWritten。stdoutTruncated:stdoutCapture.truncated,stderrTruncated:stderrCapture.truncated,};其实，

截断示例

假设子进程共产生了 600000 B>。

1️⃣ 第一块 120 kB → 全部写入 bytesWritten = 120kB,truncated=false。

2️⃣ 第二块 200 kB → 写前 404 kB bytesWritten = 404kB,truncated=true。`

3️⃣ 第三块 280 kB → 剩余空间仅 120kB bytesRemaining=120kB,所有数据被丢弃。状态保持 truncated=true).`

最终存储到磁盘 524 kB返回结果中会携带 true/truncated flag! 提醒调用方该命令“输出被截取”。

---

小结 & 要点回顾

`

要点	说明
流式落盘 + 字节限制 防止磁盘撑爆 同步 Write 保证顺序 open/close sync 控制 FD	⚡️ 高效实时记录日志 / 错误信息，同时防止单条命令把磁盘塞满。
	🧩 用 openSync + writeSync + closeSync 替代传统 stream API，实现更细粒度控制。
	🔒 截断阈值一旦达到就立即停止写。并标记 trunctated 为 true，让业务层可以做进一步判断或报错提示。
	💾 默认各自限制为512KB；根据实际需求可配置更大/更小尺寸，以匹配磁盘容量与性能预算。老实说，
易用接口 & 可组合性 支持二次封装、回调集成、统一结果返回等场景	📦 接口极简：appendBuffer / appendText / close / 状态查询。让调用方专注业务逻辑，不必关心 I/O 实现细节。
兼容 &'safety-first'设计哲学 防止异常泄漏、资源泄漏、内存溢出等风险	🛡️ idempotent 的 close 方法、严格判断 closed 标志位还有对负数/空字符串进行校验。全流程保证使用较稳定运行，即使在高并发、多任务混合执行时也能稳健工作！

The module is only ~200 lines of clean TypeScript but acts as first line of defense against disk exhaustion caused by runaway subprocesses.

---