为流式任务添加进度条

目标

长时间导入把进度打印到 stdout，破坏了下游的机器可读输出。本配方仅在 stderr 为 TTY 时用回车覆盖的方式在 stderr 渲染进度，结束时补一个换行保持终端整洁，从而把数据输出与界面输出分离；提醒应按比例节流渲染，且进度条对屏幕阅读器不友好。

步骤要点

1. 仅在 stderr 为 TTY 时渲染进度。
2. 用回车覆盖更新而不写 stdout。
3. 结束时补换行保持终端整洁。
4. 按比例节流更新，避免逐项渲染。

const show = process.stderr.isTTY;
function progress(done, total) {
  if (!show) return;
  const pct = Math.floor((done / total) * 100);
  process.stderr.write(`\r${pct}% (${done}/${total})`);
}

排错提示

• 把进度写进日志会污染输出。
• 回车符写入 stdout 会破坏数据。
• 逐项渲染开销大。

适用边界

• 对屏幕阅读器不友好。
• 对不均匀任务剩余时间估计不准。