TransformStream 背压怎么配置或排查

TransformStream 的背压要同时看可写端和可读端：前者由 writableStrategy 控制输入队列，后者由 readableStrategy 控制输出队列。先让 highWaterMark 与 size(chunk) 使用同一种单位，再优先使用 pipeThrough() 让链路自动传递背压；手动写入时则等待 writer.ready。

如果队列持续增长，先检查数据单位和下游消费速度，不要只把一个 highWaterMark 调大。desiredSize 接近或低于 0、writer.ready 长时间 pending，才说明生产端应该放慢。

先把两个 highWaterMark 的单位分清

TransformStream 构造函数的第二、第三个参数分别对应可写侧和可读侧的队列策略。highWaterMark 不是永远表示字节数：没有自定义 size() 时，普通流通常按 chunk 数量计算；使用 size(chunk) 后，队列总量就是各 chunk 返回值之和。

例如输入是二进制块，就让两侧都按字节衡量；如果输入是一条条 JSON 记录，则可以按记录数或估算后的字节数衡量。两套策略不必相同，但单位必须能解释，否则调参结果没有可比性。

用策略对象配置可解释的缓冲边界

下面的例子把输入和输出都设成按字节计量。它只展示配置方式，图中的参数也是说明性示意；生产环境应根据单块大小、转换耗时和下游吞吐做小规模压测。

const byteStrategy = {
  // 让 highWaterMark 的单位与 Uint8Array 的字节数一致
  highWaterMark: 64 * 1024,
  size(chunk) {
    // 非二进制输入按 1 个 chunk 处理，避免读取不存在的 byteLength
    return chunk instanceof Uint8Array ? chunk.byteLength : 1;
  },
};

const stream = new TransformStream(
  {
    transform(chunk, controller) {
      // 转换后再入队；desiredSize 只用于观察输出队列压力
      controller.enqueue(chunk);
      console.debug("output desiredSize:", controller.desiredSize);
    },
  },
  byteStrategy, // 输入侧：限制等待转换的总字节量
  byteStrategy, // 输出侧：限制等待消费的总字节量
);

如果只是想限制“最多暂存多少条记录”，可以改用 { highWaterMark: 8, size: () => 1 }。不要把 64 KiB 误写成 64 个 chunk 后再拿两组数据比较；highWaterMark 与 size() 必须成对理解。

pipeThrough 和手动 writer 的排查方法

标准的管道连接会把下游的压力向前传递。下游写入慢时，浏览器不会无限制地从源头读取；如果你绕过管道直接拿 writer 连续写，就必须在生产循环中等待 ready。

async function writeWithBackpressure(stream, chunks) {
  const writer = stream.writable.getWriter();
  try {
    for (const chunk of chunks) {
      // ready 未解决时，说明写入侧需要等待下游释放队列空间
      await writer.ready;
      await writer.write(chunk);
    }
    // 等待所有已写入的数据完成，再关闭可写侧
    await writer.close();
  } catch (error) {
    // 失败时主动 abort，避免调用方继续向错误流写入
    await writer.abort(error);
    throw error;
  } finally {
    writer.releaseLock();
  }
}

在 transform() 中记录 controller.desiredSize 可以帮助判断输出队列。它为 0 时队列接近高水位，变成负数表示已超过偏好的队列大小；如果是 null，通常要先排除流已经关闭或出错的情况。这个值是观察信号，不是替代 pipeThrough() 的手动调度器。

按现象定位是配置问题还是消费问题

验证时准备一个固定大小的输入源，再把 sink 的写入故意延迟。观察队列是否在阈值附近波动、下游恢复后是否回落、发生异常时源头是否停止。不要只看最终输出内容正确；背压是否生效，关键在于等待行为和队列趋势。

常见问题与边界

只设置 readableStrategy 可以吗？

可以，但它只改变可读端的队列策略。输入端如果也存在突发流量，应同时评估 writableStrategy，否则等待转换的输入仍可能堆积。

highWaterMark 越大吞吐越高吗？

不一定。更大的缓冲只能吸收短时速度差，还会增加延迟和内存占用；下游长期更慢时，应该修复消费能力或限制生产，而不是无限加大水位。

为什么 pipeThrough 后看不到手动等待？

背压由管道内部协调，应用层不必为每个 chunk 手动 await。只有直接使用 writer，或需要自定义批量调度时，才把 writer.ready 纳入自己的循环。

收尾检查

排查 TransformStream 背压时，先确认两侧策略和单位，再确认连接方式，最后用 desiredSize、writer.ready、下游耗时和内存曲线交叉判断。这样调出的阈值才是可解释的工程参数，而不是一次偶然的数字。