System.IO.Compression.BrotliStream 支持 .NET Core 2.1+，旧版需换包
你用的是 .NET Framework 4.7.2？那
BrotliStream直接不可用——它只内置于 .NET Core 2.1 及以上、.NET 5+。老项目想用，得手动装
System.IO.Compression.BrotliNuGet 包（注意不是
Microsoft.AspNetCore.App那个“全家桶”）。
常见错误现象：
TypeLoadException: Could not load type 'System.IO.Compression.BrotliStream'，八成是框架版本不匹配或没装对包。 确认目标框架：用
dotnet --list-runtimes或查项目文件里的
<targetframework></targetframework>.NET Framework 项目必须显式安装
System.IO.Compression.Brotliv4.3.0+（低版本不支持
CompressionLevel.Optimal） 别误装
Microsoft.AspNetCore.Http.Features等带 Brotli 名字但无关的包
压缩单个文件时别直接套用 GZipStream 模式
BrotliStream和
GZipStream行为一致，但参数含义有坑：它的
CompressionLevel枚举值和实际压缩率不线性对应，尤其
Fastest在某些输入下反而比
Optimal慢（因内部哈希策略不同）。
使用场景：压缩日志文件、JSON 导出包这类中等重复度文本时，
Optimal通常更稳；压缩已加密/随机二进制数据（如加密图片），Brotli 本身收益极小，还拖慢流程。 别设
CompressionLevel.NoCompression期望跳过——它仍会做头部写入，体积反而略增 压缩大文件（>100MB）建议分块读取，避免
MemoryStream吃爆内存 示例写法：
using var fs = File.Create("out.br");
using var bs = new BrotliStream(fs, CompressionLevel.Optimal);
await File.CopyAsync("in.txt", bs); // 注意：CopyAsync 内部按 8KB 块处理，够用
解压失败常因流未关闭或头部损坏
错误信息如
InvalidDataException: The archive entry was compressed using an unsupported compression method，大概率不是算法问题，而是流生命周期没管好。
根本原因：Brotli 要求完整写入头部 + 数据尾部标记，如果压缩端提前 dispose 流、或网络传输截断了最后几个字节，解压端就卡在“等尾部校验”上。
压缩后务必调用bs.Close()或用
using确保
Dispose()触发（它会 flush 尾部） 网络传输 Brotli 文件时，检查 Content-Length 是否匹配实际字节数（常见于 Nginx 未配
gzip_disable "msie6";类似逻辑） 解压前可用
File.ReadAllBytes检查末尾是否以
0xFD 0x2F B1 0x00（Brotli magic）开头，但**不保证**结尾完整——必须依赖流关闭行为
跨平台解压兼容性取决于 Brotli 版本而非 .NET 版本
你在 Linux 上用
lbrotli命令行解压失败？不是 C# 的锅，是 Brotli 标准本身有微小演进。.NET 内置的实现基于 Google 官方 C 库的某个快照（v1.0.9 左右），而较新 CLI 工具（如
brotliv1.1.0+）默认启用
--long模式，生成的流 .NET 无法识别。
性能影响：启用
--long可提升 5–10% 压缩率，但代价是内存翻倍、解压速度降 20%，对服务端高频解压场景不划算。 若需和 CLI 工具互通，压缩端统一加参数：
brotli --quality=5 --no-long（对应 .NET 的
Optimal） 别指望
BrotliStream支持自定义窗口大小——所有参数都封装在
CompressionLevel里，没法细调 Windows 上用 PowerShell 的
Expand-Archive解不了 .br 文件，它只认 .zip/.cab
事情说清了就结束
