System.IO.Pipelines专为网络流设计，不适用于直接替代FileStream；强行用于文件IO会因同步退化、额外拷贝和背压失控导致性能下降30%以上及内存泄漏风险。
System.IO.Pipelines 不是用来替代 FileStream 或直接读写文件的 —— 它专为网络流设计，强行套用到文件 IO 上反而降低性能、增加出错概率。
PipeReader 从 FileStream 构造失败或数据“消失”
常见错误是试图直接用 StreamPipeReader.Create(fileStream)，尤其在 Windows 上没加 FileOptions.Asynchronous 时，底层会退化成同步 I/O，导致线程池卡死、超时或 InvalidOperationException: "PipeWriter has been completed."。更隐蔽的问题是：即使构造成功，StreamPipeReader 内部多一层拷贝 + 锁竞争，实测大文件吞吐量可能下降 30% 以上。
- 不要用
StreamPipeReader.Create(fileStream)包装普通FileStream - 若必须桥接文件到管道（例如复用已有
PipeReader解析器），得手动分块读取：fileStream.ReadAsync()→ 租借MemoryPool<byte>.Shared.Rent()</byte>→ 转ReadOnlySequence<byte></byte>→pipe.Writer.WriteAsync() - 每次
WriteAsync()后必须显式调用memoryPool.Return(buffer)，否则内存泄漏
PipeWriter.WriteAsync() 后数据不出现或卡死
根本原因不是写失败，而是背压机制被忽略：WriteAsync() 只表示“写入缓冲区完成”，不等于“数据已被消费”。如果下游没调 ReadAsync() 或漏掉 AdvanceTo()，缓冲区就会堆积，最终触发 OperationCanceledException 或静默丢弃。
-
WriteAsync()返回后，必须确保下游有活跃的读循环，且每次ReadAsync()后都调AdvanceTo(consumed, examined) - 不能传
buffer.Start给两个参数，否则下次ReadAsync()会永远挂起 - 若解析未完成整包（如只读到半行），应设
consumed = buffer.Start、examined = buffer.End，告诉管道“我看到这么多，但还没消化”
PipeWriter 写入文件流时如何控制背压
把文件内容推入管道不是“一口气塞满”，而是读一块、等写完、再读下一块。关键在用 GetMemory() + Advance() + FlushAsync() 协同控制内存生命周期和数据流动节奏。
- 每次调
writer.GetMemory(n)前要检查返回的Memory<byte>.Length</byte>，它可能小于n（尤其缓冲区快满时） -
Advance(n)后必须立刻await writer.FlushAsync()，否则后续GetMemory()可能返回长度为 0 的内存 - 文件读完后必须
await writer.CompleteAsync()，否则reader.ReadAsync()永远不会收到result.IsCompleted == true - 禁用
stream.CopyToAsync(pipe.Writer.AsStream())—— 这绕过管道内存管理，丢失背压能力
为什么 Pipe 不适合直接做文件 IO
System.IO.Pipelines 的核心价值在于零拷贝、跨内存块视图（ReadOnlySequence<byte></byte>）和生产者-消费者解耦，这些对网络协议解析至关重要；但文件 IO 的瓶颈通常在磁盘寻道和系统调用，而非内存拷贝。用 Pipe 包一层，反而引入额外调度开销和内存租借/归还逻辑。
- 高性能文件读写应优先用
FileStream.ReadAsync(Memory<byte>, CancellationToken)</byte>+MemoryPool<byte>.Shared.Rent()</byte> - 需要“边读边解析”语义时，可组合
FileStream和Pipe，但这是应用层桥接，非框架原生支持 -
MemoryMappedFile或Span<byte></byte>批量读取仍是大文件场景的更优选择
最容易被忽略的是：PipeReader/PipeWriter 本身不是线程安全的，多个线程并发调用同一个实例会导致不可预测行为；还有，AdvanceTo() 的两个参数含义必须严格区分 —— consumed 是已处理完的位置，examined 是已扫描但未处理的最远位置，二者语义混淆是静默丢数据的根源。
