简介SharpCompress 0.37.2 为面向 .NET 开发者的跨版本压缩解压库资源适用于在 C# 项目中便捷处理 zip、tar、7z 等常见归档格式可有效降低文件流读写与压缩算法集成的复杂度。该压缩包共包含 11 个文件以针对 net8.0、net6.0、netstandard2.1、netstandard2.0 及 net462 等目标框架编译的 SharpCompress.dll 为核心同时附带 XML 文档、NuGet 包描述文件、程序集签名及 README 说明便于开发者按项目环境选取引用并快速查阅 API 用法。整个资源大小约 1.19MB轻量实用。已有 87 人下载学习适合需要引入成熟压缩方案的中高级 .NET 工程师或需要在离线场景集成库文件的项目团队。通过该压缩包可直接获取对应版本的托管程序集、包元数据与文档免去在线安装的额外步骤同时核验包签名信息有助于提升构建与交付的可靠性。1. SharpCompress 是什么解压界的瑞士军刀但别被 0.37.2 这个版本号骗了如果你在 .NET 项目里被 rar、7z、tar.gz 这些格式搞得焦头烂额sharpcompress.0.37.2 这个 NuGet 包应该在你的还原清单里。它不是微软官方组件却在开源社区里被广泛当作多格式压缩的默认选择。这套 0.37.2 版本体积不大但把 zip、tar、rar、7z 的读写统一在了一套流式 API 里写起来比反复切换底层命令要顺手得多。这篇笔记从选型理由讲到踩坑记录适合刚接手带历史包袱的压缩模块、或者想给工具箱补一个多格式库的 .NET 开发者。需要提醒的是这个版本号自带一些历史含义后面我会单独说明。2. 为什么 SharpCompress 能一次搞定 zip、rar、7z格式支持与选型逻辑2.1 SharpCompress 与 System.IO.Compression 的边界什么时候该换库很多项目一开始用 System.IO.Compression 处理 zip发现也能跑但需求一复杂就卡住。微软官方库只内置了 zip、gzip、tar 的一部分rar 和 7z 完全不在支持范围。如果有人给你一个加密的 rar 分卷包官方库只能干瞪眼。SharpCompress 的定位就是补上这些缺位它同时支持 zip、tar、tar.gz、tar.bz2、rar、7z、gzip、bzip2、xz 的读取以及 zip、tar、gzip、bzip2 的写入。每次版本更新都会修正一些格式细节0.37.2 这个版本在 rar 5 的处理上已经比较成熟。我一般会建议按这个边界选型如果业务只用标准 zip并且需要和 Java 系互传老老实实用 System.IO.Compression如果出现 rar、7z、加密分卷、自定义扩展名或者需要流式读取压缩包内部条目就换 SharpCompress。还有一个容易被忽略的理由官方库对 zip 的压缩选项控制很有限SharpCompress 的 Writer 支持按条目指定压缩类型和压缩等级这在处理混合内容时非常灵活。比如日志文件用快速压缩图片文件用存储模式避免 CPU 空耗。选型时也要注意版本号的策略。SharpCompress 的版本号不是单纯的功能递增0.37.2 属于较新的稳定系列API 与早期 0.30 系列有差异。有些老教程里写的 ArchiveFactory.WriteTo 在当前版本已经变了网上搜到的代码如果用的是旧接口编译时会直接报错。这也是我在这里坚持写 0.37.2 实际可用代码的原因——版本差异是这个库最大的学习成本之一。2.2 核心对象Reader、Writer 与 Archive 的设计差异SharpCompress 提供了三套风格不同的 API。第一套是只读的 Reader面向流式读取压缩包适合边读边处理内存占用低。第二套是 Writer面向写入可以逐条添加条目并控制压缩参数。第三套是 Archive面向随机访问适合需要查目录、按条目不连续读取的场景。三者各有分工用错会导致性能问题。例如用 Archive 去读一个巨大的 tar 包它可能把整个条目目录读进内存而用 Reader 只能顺序读无法跳回上一条。在实际项目中我倾向于把 Reader 当作默认选择。对于绝大多数“从压缩包里读出文件流并转发出去”的场景顺序读就够了而且 Reader 天然支持从流中读取不需要知道文件大小。Archive 更适合需要反复读取、或者需要读取分卷压缩包的时候。Writer 则是写入时不二之选它和 Reader 共享一套条目抽象所以用 Writer 写出来的包用 Reader 读时不会出现奇怪的路径兼容问题。这里有一个设计上的坑Reader 和 Archive 的读取粒度不同。Reader 需要先进入某个条目再读取该条目的流Archive 则可以直接通过 entry.Key / entry.OpenEntryStream() 获取条目。不要混用。常见错误是先用 Archive 枚举根目录再试图用 Reader 读取同一个压缩包结果 Reader 会从头开始无法定位。如果确实需要随机访问全程用 Archive如果想顺序解压并控制内存全程用 Reader。2.3 从 sharpcompress.0.37.2 的包结构看版本约定刚解压 sharpcompress.0.37.2.zip 时你会看到 lib 目录下按 netstandard2.0、net462 等不同目标框架分了好几个子目录。这不是冗余是因为底层 API 在不同 .NET 版本上的实现有差异。选择对应的 DLL 时要看你项目的目标框架。如果你用 .NET 6可以直接引用 netstandard2.0 版本兼容性最好。如果误引用了低版本对应的 DLL在运行时可能出现方法未找到之类的异常。这个包里还有一个 SharpCompress.Desktop 的区分。桌面框架下某些格式比如旧版 RAR 的 Unicode 文件名会有额外处理。在 .NET Core 上该库会退回到纯托管实现性能略有下降但功能不变。理解了这一点当你遇到“同样的代码在 Framework 上正常、在 Core 上抛异常”的问题时就不会去怀疑业务逻辑而是优先检查是否踩到了框架差异。版本约定的另一层含义是0.37.2 是发行包对应的源码标签可以在仓库的历史提交里找到。如果你需要修复某个 bug建议直接拉对应版本的源码构建而不是拿主分支的代码去改。因为主分支可能已经引入破坏性变更编译出来和 NuGet 包行为不一致。我见过有人改了主分支源码想替换包结果 API 签名对不上最后被迫降级。另外建议在项目里锁定这个包版本因为新版本可能会改变 ReaderOptions 的默认值升包后出现行为差异这类问题在上线前很难发现。3. 把 sharpcompress.0.37.2 跑起来最小解压与压缩代码3.1 用 ZipArchive 完成最小解压代码与参数说明先来一段最常见的解压代码用 SharpCompress 读取 zip 文件里的所有条目并输出到指定目录。using SharpCompress.Readers; using (var stream File.OpenRead(C:\data\backup.zip)) using (var reader ReaderFactory.Open(stream)) { while (reader.MoveToNextEntry()) { if (!reader.Entry.IsDirectory) { reader.WriteEntryToDirectory(C:\data\extracted, new ExtractionOptions { ExtractFullPath true, Overwrite true }); } } }这段代码的逻辑是先用文件流打开压缩包再用ReaderFactory.Open自动识别格式。MoveToNextEntry在内部会判断当前流属于哪种压缩类型并将条目指针移动到下一条。遇到目录条目直接跳过否则写入目标目录。ExtractionOptions里的ExtractFullPath表示保持压缩包内的相对路径Overwrite决定是否覆盖已存在文件。两个参数建议显式设置因为默认值在不同版本里有调整不写清楚容易产生“解出来少了一半文件”的错觉。这里有一个性能注意点WriteEntryToDirectory内部会对每个条目打开目标文件并复制流但如果你需要二次处理比如重命名、去重、过滤大文件就不要用这个方法而是自己读取条目的流。看下面的变体using var reader ReaderFactory.Open(stream); while (reader.MoveToNextEntry()) { if (reader.Entry.IsDirectory) continue; if (reader.Entry.Size 100 * 1024 * 1024) continue; // 跳过 100 MB 以上条目 using var entryStream reader.OpenEntryStream(); using var output File.Create(Path.Combine(targetDir, reader.Entry.Key)); entryStream.CopyTo(output); }由OpenEntryStream返回的流只能在这一个条目内读取移动指针到下一个条目后之前条目对应的流就失效。所以循环内不能缓存多个条目的流必须立刻消费。Entry.Size在读取时就可以拿到适合做前置过滤。如果目标目录不存在需要先Directory.CreateDirectory否则File.Create会抛目录找不到的异常别问我怎么知道的。3.2 用 Writer 生成 tar.gz 压缩包分步实现解压之外写入一个 tar.gz 包是常见的交付需求。SharpCompress 的 Writer 支持单格式写入但 tar.gz 其实是两个步骤先生成 tar 流再用 gzip 套一层。常见做法是用WriterFactory.Open传一个 gzip 压缩流给 TarWriter。using var fileStream File.Create(C:\data\output.tar.gz); using var gzipStream new GZipStream(fileStream, CompressionLevel.Optimal); using var writer WriterFactory.Open(ArchiveType.Tar, gzipStream); writer.Write(C:\data\file1.txt, file1.txt); writer.Write(C:\data\pic.png, images\pic.png);这里WriterFactory.Open的第一个参数指定内部格式第二个参数是输出流。要点是gzip 流在外层tar 流在逻辑上属于内层。Write方法有多个重载最简单的是传源文件路径和条目名。如果需要记录条目标时间、权限等信息可以传额外的 FileInfo。注意Write执行时并不会立即将内容写入文件流它会在条目数据复制完毕后刷新所以不要提前关闭gzipStream要等 writer 释放后再释放外层流。实际项目中经常要压缩整个目录手动逐条Write太累。可以遍历目录后写成递归函数但要注意路径分隔符。统一把条目名里的\替换成/否则在 Linux 上解压会看到反斜杠文件名。这个细节很容易翻车。3.3 内存流与文件流的切换避免把大文件读进内存很多初学代码喜欢写byte[] data File.ReadAllBytes再塞进 MemoryStream 交给压缩库。这种写法在小文件没问题但一旦遇到几百 MB 的包内存立刻告急。SharpCompress 的所有 API 都接受流所以尽量让文件流贯穿始终。以下写法是正确的姿势using var input File.OpenRead(C:\data\big.zip); using var reader ReaderFactory.Open(input); while (reader.MoveToNextEntry()) { // 直接消费不经过 MemoryStream }如果你必须把解压结果放到内存里比如后端接口需要把压缩包内容转成 JSON 后再透传那也要控制单个条目的体积。一个实用的策略是按条目大小做开关小于 10 MB 读进内存大于则写入临时文件。这样既满足接口的即时处理又不至于把进程内存撑爆。Entry.Size在流式读取时是可用的所以这个判断可以放在OpenEntryStream之前。需要格外注意的是ReaderFactory.Open在读流时并不预读整个压缩包它只是根据文件头判断格式。所以如果流被包装过比如加了一层自定义加密直接抛异常。这不算 bug而是设计如此任何压缩库都必须看到标准的文件头才能工作。如果你的包是加密后再做 base64 传输的必须先解密还原成原始压缩流。4. 加密、分卷与大文件的流式处理代码怎么写才不翻车这一章解决的是最容易让人放弃的三个场景加密、分卷、流式。这三个需求背后都隐藏着一些不打开源码就看不出的约定但只要把参数和调用姿势写对SharpCompress 能处理得相当干净。4.1 Rar 与 7z 的加密解压密码参数怎么传加密是压缩领域的大坑。SharpCompress 对 rar 和 7z 的加密支持程度不同。rar 的传统加密rar2、rar4可以通过ReaderOptions.Password直接解压而 rar5 的某些加密头处理在 0.37.2 版本已经可用但不是所有变体都支持。7z 则只支持 AES-256 加密的条目如果你遇到“密码正确但解不开”的情况先确认压缩时选的加密方式。一个正确的加密解压写法var options new ReaderOptions { Password your-password, LookForHeader true }; using var reader ReaderFactory.Open(fileStream, options); while (reader.MoveToNextEntry()) { reader.WriteEntryToDirectory(targetDir, new ExtractionOptions { ExtractFullPath true, Overwrite true }); }这里的LookForHeader会让库在流中搜索文件头而不是假设流起始就是文件头。这个参数对于从大文件中提取内嵌压缩包很有用但也会增加扫描耗时。在确定压缩包就是完整文件的场景下建议设为false以提升性能。密码错误时MoveToNextEntry或读取条目流时会抛出密码错误异常不要在主循环里只 catch 一次就以为全部处理完毕要区分条目级别。注意同一个加密包在 Windows 和 Linux 上对密码的处理可能不一致和系统区域的 UTF-8 设置有关。遇到诡异问题时先尝试把密码用 ASCII 重新输入。另一个细节不要把密码写死在代码里。日志、配置文件都可能被扫描到。我一般把密码放环境变量配合IConfiguration注入。压缩包来源不可信时更要注意不要用同一套密码解压所有文件否则相当于把钥匙交给了不可控的代码路径。4.2 分卷压缩 Volume 的处理连续文件的聚合逻辑rar 分卷.part1.rar、.part2.rar和 7z 分卷.7z.001、.7z.002是另一个高频需求。SharpCompress 的 Reader 本身不支持直接“吃”多个分卷流需要你自己把多个文件流串起来。常见做法是打开第一个分卷其余分卷按顺序作为追加流传入。一个实用的分卷解压实现var files Directory.GetFiles(C:\data\, *.part*.rar) .OrderBy(f f, StringComparer.OrdinalIgnoreCase) .ToArray(); using var primary File.OpenRead(files[0]); using var reader ReaderFactory.Open(primary, new ReaderOptions { Password password }); while (reader.MoveToNextEntry()) { reader.WriteEntryToDirectory(C:\data\out, new ExtractionOptions { ExtractFullPath true }); }但这其实只读到了第一个分卷后面的分卷不会被自动识别。SharpCompress 提供了 Volume 相关对象但不同格式的处理方式不一致。对于 rar你需要手动处理跨卷条目的拼接。最简单的方案是先解压第一个分卷当某个条目的流读完但校验失败时关闭当前流并打开下一个分卷再继续。实际操作时我建议直接调用ArchiveFactory.Open打开第一个文件它会自动寻找同目录下的分卷文件因为 Archive 模式实现了分卷发现逻辑。所以分卷场景请用 Archive 而不是 Reader。代码大致是using var archive ArchiveFactory.Open(files[0]); foreach (var entry in archive.Entries) { entry.WriteToDirectory(C:\data\out, new ExtractionOptions { ExtractFullPath true, Overwrite true }); }注意分卷文件的命名必须连续且在同一目录否则自动发现会失败。分卷文件缺失时库抛出的异常信息往往只写“CRC 错误”很容易让人误以为文件损坏。实际原因是后续分卷没有找到。遇到这种异常时先检查目录里分卷是否齐全再检查是不是命名大小写不匹配。如果文件列表为空直接抛异常提示用户要比后续解压过程中的任何错误都容易定位。4.3 流式读取条目解压不落盘直接进管道把解压数据直接传给下一个处理模块可以省去中间文件读写。这在处理 zip 内含多个文件、需要逐一转码的场景非常有用。using var reader ReaderFactory.Open(input, new ReaderOptions { LeaveOpen true }); while (reader.MoveToNextEntry()) { using var s reader.OpenEntryStream(); // 直接写入 HTTP 响应流而不是写到磁盘 s.CopyTo(httpResponse.Body); }LeaveOpen控制关闭 reader 时是否同时关闭底层流。如果底层流是网络流就要设置LeaveOpen true否则 reader 释放时会把网络连接一起关掉。如果底层流是文件流设false会更省心。流式读取的另一个好处是可以用CopyToAsync实现异步处理后面章节会讲。有一个容易忽略的参数ReaderOptions.LeaveOpen在不同版本中默认值不同。在 0.37.2 里默认是 false。如果你是从旧版本升级上来的代码之前没显式设置也能工作升级后可能突然报“流已关闭”这就是版本行为变化导致的。所以升级包之后务必检查所有ReaderOptions的默认值变更。对于超过 2GB 的压缩包还要考虑文件流的缓存策略。打开底层 FileStream 时用FileOptions.SequentialScan可以降低文件系统预读的冲击反之如果你要随机读取多个条目用FileOptions.RandomAccess更合适。这也是我在处理超大包时常用的一个调优点。5. SharpCompress 避坑指南五个现象背后的真实原因SharpCompress 整体设计不算复杂但真正遇到问题时网上资料很少大家基本靠试。我把这一年多在 0.37.2 上踩过的坑按频率排了序下面五条最值得留意。每条都按“现象 → 原因 → 解决”的顺序写你可以直接对照自己的代码排查。5.1 条目名乱码不是库的问题是压缩包创建端的问题现象解压 rar 或旧 zip文件名显示成“锟斤拷”或省略号或者在 Linux 上解压后路径全变成下划线。原因SharpCompress 默认按 UTF-8 解析而老工具用 GBK/CP936 写入。0.37.2 没有暴露解码器注入点所以你不能直接在 ReaderOptions 里指定编码。解决读取 entry.Key 后如果包含“?”或明显乱码把它按 ISO-8859-1 转回 byte[]再按 GBK 重新编码。示例代码var rawBytes Encoding.Latin1.GetBytes(entry.Key); var corrected Encoding.GetEncoding(GBK).GetString(rawBytes);然后使用 corrected 作为目标文件名。注意不要先写成字符串再转因为 .NET 的字符串已经破坏了原始字节序列。这个坑很隐蔽但用一次就能记住。5.2 OutOfMemoryException多半是 Archive 模式惹的祸现象解压几个 GB 的 tar 包进程内存飙到 1.5GB 并抛 OutOfMemoryException。原因ArchiveFactory.Open 会构造整个文件列表的树形结构。tar 包如果包含几十万个文件这些对象占用的内存远大于压缩包本身。解决改用 ReaderFactory.Open 顺序读取因为 Reader 不会预加载条目目录。如果确实需要 Archive 的随机访问尝试分批处理先用 Reader 把索引落盘再按需定位。另外检查是不是在 MoveToNextEntry 循环里用 MemoryStream 暂存了太多条目要确保每个条目处理完就释放。5.3 同代码不同运行时的差异先查目标框架再查异常现象同一段解压代码在 .NET Framework 4.7.2 上正常迁移到 .NET 6 后抛 NotSupportedException。原因SharpCompress 内部使用了一些桌面框架独有的 API 处理旧格式这些分支在 netstandard2.0 目标里被排除。0.37.2 的发行包里有多个 DLL项目引用错了也会出现同样现象。解决检查项目生成的 deps.json 或程序集加载日志确认加载的是 lib/netstandard2.0/SharpCompress.dll。如果还有问题不要试图在 ReaderOptions 里找不存在的“编码”或“兼容模式”属性而是去查异常堆栈里的 “PlatformNotSupported” 标志对应到该版本源码的条件编译分支手动绕过。5.4 遍历慢得像死循环关掉 LookForHeader 试试现象一个只有 200 个条目的 zip 包MoveToNextEntry 循环却卡了 10 秒。原因ReaderOptions 默认的 LookForHeader 为 true它会从流的头部或当前位置向后扫描文件头。这个扫描在完整文件流上完全多余还会把未压缩的字节也拖进检测流程。解决在确定流起始就是压缩包文件头时显式设置LookForHeader false。同时使用 FileStream 时不要用异步读取模式这会引入额外缓冲。改完通常能把冷启动时间降一个数量级。如果包里条目数很大还可以考虑在解析前用文件流预读一部分字节识别真实格式避免让库在未知位置反复试探。5.5 写入压缩包时进度事件没有触发现象调用 writer.Write 时传入的 IProgress 一次都没回调。原因Write 方法的重载有很多只有带 progress 参数的那个重载才会报告字节进度。如果误用了不带 progress 的重载当然没有回调。解决使用writer.Write(entryPath, entryName, new FileInfo(entryPath), progress)重载。注意进度是按字节计不是按条目计所以要先知道你写入的总大小。想要百分比就用一个累加器除以总大小。如果你在解压端看到进度条乱跳多半是多个条目的进度叠加了需要每个条目单独建一个 progress 实例。6. 进阶技巧并行解压与性能验证的最后一公里当单个压缩包内文件很多但彼此独立很多人会想到多线程提升速度。但 SharpCompress 的 Reader 和 Archive 都不是线程安全的同一个流不能并发读多个条目。正确做法是按压缩包粒度并行而不是按条目并行。var zipFiles Directory.GetFiles(C:\data\, *.zip); await Parallel.ForEachAsync(zipFiles, new ParallelOptions { MaxDegreeOfParallelism 4 }, async (file, ct) { await Task.Run(() { using var reader ReaderFactory.Open(File.OpenRead(file)); while (reader.MoveToNextEntry()) { reader.WriteEntryToDirectory(C:\data\out, new ExtractionOptions { ExtractFullPath true, Overwrite false }); } }, ct); });MaxDegreeOfParallelism要按磁盘 IO 能力和目标运行环境调整。压满 CPU 并不等于压满磁盘通常 4 到 8 对机械盘已经很高了。我一直习惯在跑完一批后对比总耗时与资源占用而不是盲目调大并发数。验证方式很简单用Stopwatch计时同时用Process.WorkingSet64观察内存。如果并发数翻倍但耗时没降说明瓶颈在磁盘或解压算法的单线程部分。我踩过一个很惨的坑曾经为了提高解压吞吐让多个线程直接操作同一个ReaderFactory.Open出来的流结果出现大量 CRC 错误。排查了一个下午最后才确认流内部有共享状态根本不适合并发读。那之后我给自己定了一条铁律凡是MoveToNextEntry循环体里的操作永远不允许并行要并行就并行整个解压流程。另外建议在发布前做一次小规模的性能基线测试固定同样的输入记录 CPU、内存和耗时。SharpCompress 的版本升级可能会改变默认压缩策略0.37.2 相比早期版本在 rar5 解压上优化明显但 zip 写入的压缩等级默认值有变动。不要相信直觉跑一次数据再决定要不要加WriterOptions参数。希望帮到你。本文还有配套的精品资源点击获取
SharpCompress 0.37.2实战：.NET多格式压缩解压与避坑指南
简介SharpCompress 0.37.2 为面向 .NET 开发者的跨版本压缩解压库资源适用于在 C# 项目中便捷处理 zip、tar、7z 等常见归档格式可有效降低文件流读写与压缩算法集成的复杂度。该压缩包共包含 11 个文件以针对 net8.0、net6.0、netstandard2.1、netstandard2.0 及 net462 等目标框架编译的 SharpCompress.dll 为核心同时附带 XML 文档、NuGet 包描述文件、程序集签名及 README 说明便于开发者按项目环境选取引用并快速查阅 API 用法。整个资源大小约 1.19MB轻量实用。已有 87 人下载学习适合需要引入成熟压缩方案的中高级 .NET 工程师或需要在离线场景集成库文件的项目团队。通过该压缩包可直接获取对应版本的托管程序集、包元数据与文档免去在线安装的额外步骤同时核验包签名信息有助于提升构建与交付的可靠性。1. SharpCompress 是什么解压界的瑞士军刀但别被 0.37.2 这个版本号骗了如果你在 .NET 项目里被 rar、7z、tar.gz 这些格式搞得焦头烂额sharpcompress.0.37.2 这个 NuGet 包应该在你的还原清单里。它不是微软官方组件却在开源社区里被广泛当作多格式压缩的默认选择。这套 0.37.2 版本体积不大但把 zip、tar、rar、7z 的读写统一在了一套流式 API 里写起来比反复切换底层命令要顺手得多。这篇笔记从选型理由讲到踩坑记录适合刚接手带历史包袱的压缩模块、或者想给工具箱补一个多格式库的 .NET 开发者。需要提醒的是这个版本号自带一些历史含义后面我会单独说明。2. 为什么 SharpCompress 能一次搞定 zip、rar、7z格式支持与选型逻辑2.1 SharpCompress 与 System.IO.Compression 的边界什么时候该换库很多项目一开始用 System.IO.Compression 处理 zip发现也能跑但需求一复杂就卡住。微软官方库只内置了 zip、gzip、tar 的一部分rar 和 7z 完全不在支持范围。如果有人给你一个加密的 rar 分卷包官方库只能干瞪眼。SharpCompress 的定位就是补上这些缺位它同时支持 zip、tar、tar.gz、tar.bz2、rar、7z、gzip、bzip2、xz 的读取以及 zip、tar、gzip、bzip2 的写入。每次版本更新都会修正一些格式细节0.37.2 这个版本在 rar 5 的处理上已经比较成熟。我一般会建议按这个边界选型如果业务只用标准 zip并且需要和 Java 系互传老老实实用 System.IO.Compression如果出现 rar、7z、加密分卷、自定义扩展名或者需要流式读取压缩包内部条目就换 SharpCompress。还有一个容易被忽略的理由官方库对 zip 的压缩选项控制很有限SharpCompress 的 Writer 支持按条目指定压缩类型和压缩等级这在处理混合内容时非常灵活。比如日志文件用快速压缩图片文件用存储模式避免 CPU 空耗。选型时也要注意版本号的策略。SharpCompress 的版本号不是单纯的功能递增0.37.2 属于较新的稳定系列API 与早期 0.30 系列有差异。有些老教程里写的 ArchiveFactory.WriteTo 在当前版本已经变了网上搜到的代码如果用的是旧接口编译时会直接报错。这也是我在这里坚持写 0.37.2 实际可用代码的原因——版本差异是这个库最大的学习成本之一。2.2 核心对象Reader、Writer 与 Archive 的设计差异SharpCompress 提供了三套风格不同的 API。第一套是只读的 Reader面向流式读取压缩包适合边读边处理内存占用低。第二套是 Writer面向写入可以逐条添加条目并控制压缩参数。第三套是 Archive面向随机访问适合需要查目录、按条目不连续读取的场景。三者各有分工用错会导致性能问题。例如用 Archive 去读一个巨大的 tar 包它可能把整个条目目录读进内存而用 Reader 只能顺序读无法跳回上一条。在实际项目中我倾向于把 Reader 当作默认选择。对于绝大多数“从压缩包里读出文件流并转发出去”的场景顺序读就够了而且 Reader 天然支持从流中读取不需要知道文件大小。Archive 更适合需要反复读取、或者需要读取分卷压缩包的时候。Writer 则是写入时不二之选它和 Reader 共享一套条目抽象所以用 Writer 写出来的包用 Reader 读时不会出现奇怪的路径兼容问题。这里有一个设计上的坑Reader 和 Archive 的读取粒度不同。Reader 需要先进入某个条目再读取该条目的流Archive 则可以直接通过 entry.Key / entry.OpenEntryStream() 获取条目。不要混用。常见错误是先用 Archive 枚举根目录再试图用 Reader 读取同一个压缩包结果 Reader 会从头开始无法定位。如果确实需要随机访问全程用 Archive如果想顺序解压并控制内存全程用 Reader。2.3 从 sharpcompress.0.37.2 的包结构看版本约定刚解压 sharpcompress.0.37.2.zip 时你会看到 lib 目录下按 netstandard2.0、net462 等不同目标框架分了好几个子目录。这不是冗余是因为底层 API 在不同 .NET 版本上的实现有差异。选择对应的 DLL 时要看你项目的目标框架。如果你用 .NET 6可以直接引用 netstandard2.0 版本兼容性最好。如果误引用了低版本对应的 DLL在运行时可能出现方法未找到之类的异常。这个包里还有一个 SharpCompress.Desktop 的区分。桌面框架下某些格式比如旧版 RAR 的 Unicode 文件名会有额外处理。在 .NET Core 上该库会退回到纯托管实现性能略有下降但功能不变。理解了这一点当你遇到“同样的代码在 Framework 上正常、在 Core 上抛异常”的问题时就不会去怀疑业务逻辑而是优先检查是否踩到了框架差异。版本约定的另一层含义是0.37.2 是发行包对应的源码标签可以在仓库的历史提交里找到。如果你需要修复某个 bug建议直接拉对应版本的源码构建而不是拿主分支的代码去改。因为主分支可能已经引入破坏性变更编译出来和 NuGet 包行为不一致。我见过有人改了主分支源码想替换包结果 API 签名对不上最后被迫降级。另外建议在项目里锁定这个包版本因为新版本可能会改变 ReaderOptions 的默认值升包后出现行为差异这类问题在上线前很难发现。3. 把 sharpcompress.0.37.2 跑起来最小解压与压缩代码3.1 用 ZipArchive 完成最小解压代码与参数说明先来一段最常见的解压代码用 SharpCompress 读取 zip 文件里的所有条目并输出到指定目录。using SharpCompress.Readers; using (var stream File.OpenRead(C:\data\backup.zip)) using (var reader ReaderFactory.Open(stream)) { while (reader.MoveToNextEntry()) { if (!reader.Entry.IsDirectory) { reader.WriteEntryToDirectory(C:\data\extracted, new ExtractionOptions { ExtractFullPath true, Overwrite true }); } } }这段代码的逻辑是先用文件流打开压缩包再用ReaderFactory.Open自动识别格式。MoveToNextEntry在内部会判断当前流属于哪种压缩类型并将条目指针移动到下一条。遇到目录条目直接跳过否则写入目标目录。ExtractionOptions里的ExtractFullPath表示保持压缩包内的相对路径Overwrite决定是否覆盖已存在文件。两个参数建议显式设置因为默认值在不同版本里有调整不写清楚容易产生“解出来少了一半文件”的错觉。这里有一个性能注意点WriteEntryToDirectory内部会对每个条目打开目标文件并复制流但如果你需要二次处理比如重命名、去重、过滤大文件就不要用这个方法而是自己读取条目的流。看下面的变体using var reader ReaderFactory.Open(stream); while (reader.MoveToNextEntry()) { if (reader.Entry.IsDirectory) continue; if (reader.Entry.Size 100 * 1024 * 1024) continue; // 跳过 100 MB 以上条目 using var entryStream reader.OpenEntryStream(); using var output File.Create(Path.Combine(targetDir, reader.Entry.Key)); entryStream.CopyTo(output); }由OpenEntryStream返回的流只能在这一个条目内读取移动指针到下一个条目后之前条目对应的流就失效。所以循环内不能缓存多个条目的流必须立刻消费。Entry.Size在读取时就可以拿到适合做前置过滤。如果目标目录不存在需要先Directory.CreateDirectory否则File.Create会抛目录找不到的异常别问我怎么知道的。3.2 用 Writer 生成 tar.gz 压缩包分步实现解压之外写入一个 tar.gz 包是常见的交付需求。SharpCompress 的 Writer 支持单格式写入但 tar.gz 其实是两个步骤先生成 tar 流再用 gzip 套一层。常见做法是用WriterFactory.Open传一个 gzip 压缩流给 TarWriter。using var fileStream File.Create(C:\data\output.tar.gz); using var gzipStream new GZipStream(fileStream, CompressionLevel.Optimal); using var writer WriterFactory.Open(ArchiveType.Tar, gzipStream); writer.Write(C:\data\file1.txt, file1.txt); writer.Write(C:\data\pic.png, images\pic.png);这里WriterFactory.Open的第一个参数指定内部格式第二个参数是输出流。要点是gzip 流在外层tar 流在逻辑上属于内层。Write方法有多个重载最简单的是传源文件路径和条目名。如果需要记录条目标时间、权限等信息可以传额外的 FileInfo。注意Write执行时并不会立即将内容写入文件流它会在条目数据复制完毕后刷新所以不要提前关闭gzipStream要等 writer 释放后再释放外层流。实际项目中经常要压缩整个目录手动逐条Write太累。可以遍历目录后写成递归函数但要注意路径分隔符。统一把条目名里的\替换成/否则在 Linux 上解压会看到反斜杠文件名。这个细节很容易翻车。3.3 内存流与文件流的切换避免把大文件读进内存很多初学代码喜欢写byte[] data File.ReadAllBytes再塞进 MemoryStream 交给压缩库。这种写法在小文件没问题但一旦遇到几百 MB 的包内存立刻告急。SharpCompress 的所有 API 都接受流所以尽量让文件流贯穿始终。以下写法是正确的姿势using var input File.OpenRead(C:\data\big.zip); using var reader ReaderFactory.Open(input); while (reader.MoveToNextEntry()) { // 直接消费不经过 MemoryStream }如果你必须把解压结果放到内存里比如后端接口需要把压缩包内容转成 JSON 后再透传那也要控制单个条目的体积。一个实用的策略是按条目大小做开关小于 10 MB 读进内存大于则写入临时文件。这样既满足接口的即时处理又不至于把进程内存撑爆。Entry.Size在流式读取时是可用的所以这个判断可以放在OpenEntryStream之前。需要格外注意的是ReaderFactory.Open在读流时并不预读整个压缩包它只是根据文件头判断格式。所以如果流被包装过比如加了一层自定义加密直接抛异常。这不算 bug而是设计如此任何压缩库都必须看到标准的文件头才能工作。如果你的包是加密后再做 base64 传输的必须先解密还原成原始压缩流。4. 加密、分卷与大文件的流式处理代码怎么写才不翻车这一章解决的是最容易让人放弃的三个场景加密、分卷、流式。这三个需求背后都隐藏着一些不打开源码就看不出的约定但只要把参数和调用姿势写对SharpCompress 能处理得相当干净。4.1 Rar 与 7z 的加密解压密码参数怎么传加密是压缩领域的大坑。SharpCompress 对 rar 和 7z 的加密支持程度不同。rar 的传统加密rar2、rar4可以通过ReaderOptions.Password直接解压而 rar5 的某些加密头处理在 0.37.2 版本已经可用但不是所有变体都支持。7z 则只支持 AES-256 加密的条目如果你遇到“密码正确但解不开”的情况先确认压缩时选的加密方式。一个正确的加密解压写法var options new ReaderOptions { Password your-password, LookForHeader true }; using var reader ReaderFactory.Open(fileStream, options); while (reader.MoveToNextEntry()) { reader.WriteEntryToDirectory(targetDir, new ExtractionOptions { ExtractFullPath true, Overwrite true }); }这里的LookForHeader会让库在流中搜索文件头而不是假设流起始就是文件头。这个参数对于从大文件中提取内嵌压缩包很有用但也会增加扫描耗时。在确定压缩包就是完整文件的场景下建议设为false以提升性能。密码错误时MoveToNextEntry或读取条目流时会抛出密码错误异常不要在主循环里只 catch 一次就以为全部处理完毕要区分条目级别。注意同一个加密包在 Windows 和 Linux 上对密码的处理可能不一致和系统区域的 UTF-8 设置有关。遇到诡异问题时先尝试把密码用 ASCII 重新输入。另一个细节不要把密码写死在代码里。日志、配置文件都可能被扫描到。我一般把密码放环境变量配合IConfiguration注入。压缩包来源不可信时更要注意不要用同一套密码解压所有文件否则相当于把钥匙交给了不可控的代码路径。4.2 分卷压缩 Volume 的处理连续文件的聚合逻辑rar 分卷.part1.rar、.part2.rar和 7z 分卷.7z.001、.7z.002是另一个高频需求。SharpCompress 的 Reader 本身不支持直接“吃”多个分卷流需要你自己把多个文件流串起来。常见做法是打开第一个分卷其余分卷按顺序作为追加流传入。一个实用的分卷解压实现var files Directory.GetFiles(C:\data\, *.part*.rar) .OrderBy(f f, StringComparer.OrdinalIgnoreCase) .ToArray(); using var primary File.OpenRead(files[0]); using var reader ReaderFactory.Open(primary, new ReaderOptions { Password password }); while (reader.MoveToNextEntry()) { reader.WriteEntryToDirectory(C:\data\out, new ExtractionOptions { ExtractFullPath true }); }但这其实只读到了第一个分卷后面的分卷不会被自动识别。SharpCompress 提供了 Volume 相关对象但不同格式的处理方式不一致。对于 rar你需要手动处理跨卷条目的拼接。最简单的方案是先解压第一个分卷当某个条目的流读完但校验失败时关闭当前流并打开下一个分卷再继续。实际操作时我建议直接调用ArchiveFactory.Open打开第一个文件它会自动寻找同目录下的分卷文件因为 Archive 模式实现了分卷发现逻辑。所以分卷场景请用 Archive 而不是 Reader。代码大致是using var archive ArchiveFactory.Open(files[0]); foreach (var entry in archive.Entries) { entry.WriteToDirectory(C:\data\out, new ExtractionOptions { ExtractFullPath true, Overwrite true }); }注意分卷文件的命名必须连续且在同一目录否则自动发现会失败。分卷文件缺失时库抛出的异常信息往往只写“CRC 错误”很容易让人误以为文件损坏。实际原因是后续分卷没有找到。遇到这种异常时先检查目录里分卷是否齐全再检查是不是命名大小写不匹配。如果文件列表为空直接抛异常提示用户要比后续解压过程中的任何错误都容易定位。4.3 流式读取条目解压不落盘直接进管道把解压数据直接传给下一个处理模块可以省去中间文件读写。这在处理 zip 内含多个文件、需要逐一转码的场景非常有用。using var reader ReaderFactory.Open(input, new ReaderOptions { LeaveOpen true }); while (reader.MoveToNextEntry()) { using var s reader.OpenEntryStream(); // 直接写入 HTTP 响应流而不是写到磁盘 s.CopyTo(httpResponse.Body); }LeaveOpen控制关闭 reader 时是否同时关闭底层流。如果底层流是网络流就要设置LeaveOpen true否则 reader 释放时会把网络连接一起关掉。如果底层流是文件流设false会更省心。流式读取的另一个好处是可以用CopyToAsync实现异步处理后面章节会讲。有一个容易忽略的参数ReaderOptions.LeaveOpen在不同版本中默认值不同。在 0.37.2 里默认是 false。如果你是从旧版本升级上来的代码之前没显式设置也能工作升级后可能突然报“流已关闭”这就是版本行为变化导致的。所以升级包之后务必检查所有ReaderOptions的默认值变更。对于超过 2GB 的压缩包还要考虑文件流的缓存策略。打开底层 FileStream 时用FileOptions.SequentialScan可以降低文件系统预读的冲击反之如果你要随机读取多个条目用FileOptions.RandomAccess更合适。这也是我在处理超大包时常用的一个调优点。5. SharpCompress 避坑指南五个现象背后的真实原因SharpCompress 整体设计不算复杂但真正遇到问题时网上资料很少大家基本靠试。我把这一年多在 0.37.2 上踩过的坑按频率排了序下面五条最值得留意。每条都按“现象 → 原因 → 解决”的顺序写你可以直接对照自己的代码排查。5.1 条目名乱码不是库的问题是压缩包创建端的问题现象解压 rar 或旧 zip文件名显示成“锟斤拷”或省略号或者在 Linux 上解压后路径全变成下划线。原因SharpCompress 默认按 UTF-8 解析而老工具用 GBK/CP936 写入。0.37.2 没有暴露解码器注入点所以你不能直接在 ReaderOptions 里指定编码。解决读取 entry.Key 后如果包含“?”或明显乱码把它按 ISO-8859-1 转回 byte[]再按 GBK 重新编码。示例代码var rawBytes Encoding.Latin1.GetBytes(entry.Key); var corrected Encoding.GetEncoding(GBK).GetString(rawBytes);然后使用 corrected 作为目标文件名。注意不要先写成字符串再转因为 .NET 的字符串已经破坏了原始字节序列。这个坑很隐蔽但用一次就能记住。5.2 OutOfMemoryException多半是 Archive 模式惹的祸现象解压几个 GB 的 tar 包进程内存飙到 1.5GB 并抛 OutOfMemoryException。原因ArchiveFactory.Open 会构造整个文件列表的树形结构。tar 包如果包含几十万个文件这些对象占用的内存远大于压缩包本身。解决改用 ReaderFactory.Open 顺序读取因为 Reader 不会预加载条目目录。如果确实需要 Archive 的随机访问尝试分批处理先用 Reader 把索引落盘再按需定位。另外检查是不是在 MoveToNextEntry 循环里用 MemoryStream 暂存了太多条目要确保每个条目处理完就释放。5.3 同代码不同运行时的差异先查目标框架再查异常现象同一段解压代码在 .NET Framework 4.7.2 上正常迁移到 .NET 6 后抛 NotSupportedException。原因SharpCompress 内部使用了一些桌面框架独有的 API 处理旧格式这些分支在 netstandard2.0 目标里被排除。0.37.2 的发行包里有多个 DLL项目引用错了也会出现同样现象。解决检查项目生成的 deps.json 或程序集加载日志确认加载的是 lib/netstandard2.0/SharpCompress.dll。如果还有问题不要试图在 ReaderOptions 里找不存在的“编码”或“兼容模式”属性而是去查异常堆栈里的 “PlatformNotSupported” 标志对应到该版本源码的条件编译分支手动绕过。5.4 遍历慢得像死循环关掉 LookForHeader 试试现象一个只有 200 个条目的 zip 包MoveToNextEntry 循环却卡了 10 秒。原因ReaderOptions 默认的 LookForHeader 为 true它会从流的头部或当前位置向后扫描文件头。这个扫描在完整文件流上完全多余还会把未压缩的字节也拖进检测流程。解决在确定流起始就是压缩包文件头时显式设置LookForHeader false。同时使用 FileStream 时不要用异步读取模式这会引入额外缓冲。改完通常能把冷启动时间降一个数量级。如果包里条目数很大还可以考虑在解析前用文件流预读一部分字节识别真实格式避免让库在未知位置反复试探。5.5 写入压缩包时进度事件没有触发现象调用 writer.Write 时传入的 IProgress 一次都没回调。原因Write 方法的重载有很多只有带 progress 参数的那个重载才会报告字节进度。如果误用了不带 progress 的重载当然没有回调。解决使用writer.Write(entryPath, entryName, new FileInfo(entryPath), progress)重载。注意进度是按字节计不是按条目计所以要先知道你写入的总大小。想要百分比就用一个累加器除以总大小。如果你在解压端看到进度条乱跳多半是多个条目的进度叠加了需要每个条目单独建一个 progress 实例。6. 进阶技巧并行解压与性能验证的最后一公里当单个压缩包内文件很多但彼此独立很多人会想到多线程提升速度。但 SharpCompress 的 Reader 和 Archive 都不是线程安全的同一个流不能并发读多个条目。正确做法是按压缩包粒度并行而不是按条目并行。var zipFiles Directory.GetFiles(C:\data\, *.zip); await Parallel.ForEachAsync(zipFiles, new ParallelOptions { MaxDegreeOfParallelism 4 }, async (file, ct) { await Task.Run(() { using var reader ReaderFactory.Open(File.OpenRead(file)); while (reader.MoveToNextEntry()) { reader.WriteEntryToDirectory(C:\data\out, new ExtractionOptions { ExtractFullPath true, Overwrite false }); } }, ct); });MaxDegreeOfParallelism要按磁盘 IO 能力和目标运行环境调整。压满 CPU 并不等于压满磁盘通常 4 到 8 对机械盘已经很高了。我一直习惯在跑完一批后对比总耗时与资源占用而不是盲目调大并发数。验证方式很简单用Stopwatch计时同时用Process.WorkingSet64观察内存。如果并发数翻倍但耗时没降说明瓶颈在磁盘或解压算法的单线程部分。我踩过一个很惨的坑曾经为了提高解压吞吐让多个线程直接操作同一个ReaderFactory.Open出来的流结果出现大量 CRC 错误。排查了一个下午最后才确认流内部有共享状态根本不适合并发读。那之后我给自己定了一条铁律凡是MoveToNextEntry循环体里的操作永远不允许并行要并行就并行整个解压流程。另外建议在发布前做一次小规模的性能基线测试固定同样的输入记录 CPU、内存和耗时。SharpCompress 的版本升级可能会改变默认压缩策略0.37.2 相比早期版本在 rar5 解压上优化明显但 zip 写入的压缩等级默认值有变动。不要相信直觉跑一次数据再决定要不要加WriterOptions参数。希望帮到你。本文还有配套的精品资源点击获取