簡介SharpCompress 0.37.2 是一份面向 .NET 開發(fā)者的壓縮庫 NuGet 離線包適合需要在項(xiàng)目中集成 zip、rar、7z、tar 等格式讀寫能力的工程師尤其適用于無法直接訪問外網(wǎng)源、需手動(dòng)引入依賴的內(nèi)網(wǎng)或離線開發(fā)環(huán)境。壓縮包共 11 個(gè)文件以 5 個(gè) SharpCompress.dll 程序集為核心分別對應(yīng) net8.0、net6.0、netstandard2.1、netstandard2.0 與 net462 多個(gè)目標(biāo)框架另含 nuspec 清單、Content_Types.xml、rels 關(guān)系文件、README.md 說明文檔及 p7s 簽名文件整體約 1.19MB體積輕量便于隨項(xiàng)目分發(fā)。該庫支持流式讀寫與多格式解壓可減少自行封裝底層壓縮邏輯的工作量。目前已有 87 人學(xué)習(xí)下載適合需要快速補(bǔ)齊壓縮處理能力、對照多框架程序集選型的開發(fā)者參考使用。1. 從 sharpcompress.0.37.2.zip 說起一個(gè)被低估的壓縮庫到底能解決什么如果你在 .NET 項(xiàng)目里處理過 zip、7z、tar、gzip 甚至 rar 的解壓大概率繞不開一個(gè)名字SharpCompress。它不像 System.IO.Compression 那樣是官方內(nèi)置但在格式覆蓋面上要寬得多——官方庫主要管 zip 和 gzip而 SharpCompress 把 7z、rar、tar、tar.gz、tar.bz2、lzip、xz 這些常見歸檔格式都納入了同一套讀寫接口。你拿到的 sharpcompress.0.37.2.zip 就是這個(gè)庫某個(gè)版本的源碼或發(fā)布包版本號 0.37.2 說明它還在 0.x 階段API 相對穩(wěn)定但仍有演進(jìn)空間。這個(gè)標(biāo)題背后真正的問題不是“怎么解壓一個(gè) zip”而是“當(dāng)項(xiàng)目需要同時(shí)面對多種壓縮格式、又不想為每種格式引入不同第三方庫時(shí)怎么用一套代碼統(tǒng)一處理”。SharpCompress 的價(jià)值就在這里它把歸檔讀取抽象成 IArchive / IReader 體系寫入抽象成 IWriter流式處理大文件時(shí)不需要一次性把整個(gè)歸檔讀進(jìn)內(nèi)存。適合誰做桌面工具、批量文件處理、備份恢復(fù)、日志歸檔、安裝包解析的 .NET 工程師尤其是那些被“rar 解壓要額外找?guī)臁?z 又要換一套 API”折磨過的人。這一篇不打算復(fù)述官方 README而是按我實(shí)際在項(xiàng)目里用它的路徑從引入方式、核心 API、參數(shù)配置、踩坑記錄到進(jìn)階技巧把 sharpcompress 0.37.2 這個(gè)版本能落地的用法講清楚。你如果是第一次接觸可以跟著代碼塊直接跑如果你已經(jīng)用過舊版本可以重點(diǎn)看參數(shù)差異和避坑部分。2. 把 SharpCompress 接進(jìn)項(xiàng)目引入方式與最小可跑示例2.1 包引入的三種路徑與版本選擇拿到 sharpcompress.0.37.2.zip 之后第一件事是決定怎么把它變成項(xiàng)目里可引用的依賴。常見做法有三種直接引用編譯好的 DLL、把源碼項(xiàng)目加入解決方案、通過 NuGet 安裝對應(yīng)版本。前兩種適合你需要改源碼或調(diào)試內(nèi)部邏輯的場景第三種適合絕大多數(shù)生產(chǎn)項(xiàng)目。如果你走 NuGet命令很簡單dotnet add package SharpCompress --version 0.37.2如果你拿到的是源碼 zip解壓后通常會看到 SharpCompress 主項(xiàng)目和一些測試項(xiàng)目。用 dotnet CLI 把主項(xiàng)目加入你的解決方案dotnet sln add ./SharpCompress/SharpCompress.csproj dotnet add ./YourApp/YourApp.csproj reference ./SharpCompress/SharpCompress.csproj這里有個(gè)版本選擇上的實(shí)際考量0.37.x 系列對 .NET Standard 2.0 和 .NET 6 的支持比較完整如果你的項(xiàng)目還在 .NET Framework 4.6.1 上也能跑但部分異步 API 會退化成同步實(shí)現(xiàn)。我一般會在 csproj 里顯式鎖定版本避免 CI 環(huán)境自動(dòng)拉到更高版本導(dǎo)致行為變化PackageReference IncludeSharpCompress Version0.37.2 /參數(shù)說明Version 寫死到補(bǔ)丁號是因?yàn)?0.x 階段小版本之間偶爾會有 API 簽名調(diào)整鎖版本能保證本地和構(gòu)建服務(wù)器行為一致。如果你確實(shí)需要升級先在一個(gè)分支上跑完解壓測試用例再合并。2.2 讀取 zip 的最小代碼與流式處理要點(diǎn)引入之后最常用的入口是ArchiveFactory.Open或ZipArchive.Open。下面這段代碼演示從文件路徑打開一個(gè) zip遍歷條目并解壓到指定目錄using SharpCompress.Archives; using SharpCompress.Common; string archivePath D:\data\sample.zip; string outputDir D:\data\extracted; Directory.CreateDirectory(outputDir); using (var archive ArchiveFactory.Open(archivePath)) { foreach (var entry in archive.Entries) { if (entry.IsDirectory) continue; // 只解壓 .txt 和 .csv避免釋放不需要的文件 string ext Path.GetExtension(entry.Key); if (ext ! .txt ext ! .csv) continue; string destPath Path.Combine(outputDir, entry.Key); Directory.CreateDirectory(Path.GetDirectoryName(destPath)!); entry.WriteToFile(destPath, new ExtractionOptions { ExtractFullPath true, Overwrite true }); } }邏輯說明ArchiveFactory.Open會根據(jù)文件頭自動(dòng)識別格式不要求你提前知道是 zip 還是 7z。entry.Key是歸檔內(nèi)的相對路徑WriteToFile負(fù)責(zé)把當(dāng)前條目寫到磁盤。ExtractionOptions里ExtractFullPath true會保留目錄結(jié)構(gòu)Overwrite true表示同名文件直接覆蓋。參數(shù)說明如果你處理的是不可信來源的歸檔ExtractFullPath要配合路徑校驗(yàn)一起用防止../這類路徑穿越。0.37.2 里WriteToFile本身不會做安全路徑檢查需要你自己在Path.Combine之后判斷最終路徑是否在 outputDir 之下。另一個(gè)參數(shù)是entry.Size可以在解壓前用來估算總大小避免磁盤寫滿。流式處理方面如果你不想落盤可以用entry.OpenEntryStream()拿到一個(gè)只讀流直接喂給后續(xù)處理邏輯using (var archive ArchiveFactory.Open(archivePath)) { var target archive.Entries.First(e e.Key.EndsWith(.csv)); using (var stream target.OpenEntryStream()) using (var reader new StreamReader(stream)) { string? line; while ((line reader.ReadLine()) ! null) { // 逐行處理內(nèi)存占用與文件大小無關(guān) } } }這種寫法在解壓大文件時(shí)特別有用因?yàn)椴粫淮涡园褩l目內(nèi)容讀進(jìn) byte 數(shù)組。注意OpenEntryStream返回的流在archive釋放后不可再用所以處理邏輯要放在 using 塊內(nèi)部。3. 寫入與壓縮用 SharpCompress 生成 zip 和 7z 的實(shí)操細(xì)節(jié)3.1 創(chuàng)建 zip 的 Writer 用法與壓縮級別讀取之外SharpCompress 也能寫歸檔。創(chuàng)建 zip 的常見做法是用ZipArchive.Create()配合WriterOptionsusing SharpCompress.Archives; using SharpCompress.Common; using SharpCompress.Writers; string outputZip D:\data\output.zip; using (var archive ZipArchive.Create()) { archive.AddEntry(docs/readme.txt, D:\src\readme.txt); archive.AddEntry(data/report.csv, D:\src\report.csv); archive.SaveTo(outputZip, new WriterOptions(CompressionType.Deflate) { LeaveStreamOpen false }); }邏輯說明AddEntry的第一個(gè)參數(shù)是歸檔內(nèi)路徑第二個(gè)參數(shù)是本地文件路徑。SaveTo觸發(fā)實(shí)際寫入WriterOptions指定壓縮算法。zip 常用Deflate兼容性最好如果你追求更高壓縮率可以用Deflate64但部分老解壓工具不支持。參數(shù)說明LeaveStreamOpen設(shè)為 false 表示 SaveTo 完成后關(guān)閉內(nèi)部流避免文件句柄泄漏。如果你是在內(nèi)存流上操作需要設(shè)為 true 以便后續(xù)讀取。壓縮級別在 0.37.2 里通過WriterOptions的CompressionType間接控制沒有直接的 0-9 檔位這一點(diǎn)和某些庫不同選型時(shí)要注意。3.2 7z 寫入的差異與適用場景7z 的寫入接口和 zip 類似但入口不同using SharpCompress.Archives.SevenZip; using SharpCompress.Common; using SharpCompress.Writers; string output7z D:\data\output.7z; using (var archive SevenZipArchive.Create()) { archive.AddEntry(logs/app.log, D:\src\app.log); archive.SaveTo(output7z, new WriterOptions(CompressionType.LZMA) { LeaveStreamOpen false }); }邏輯說明SevenZipArchive.Create()創(chuàng)建 7z 歸檔壓縮類型用LZMA。7z 的優(yōu)勢在于壓縮率通常比 zip 高尤其是文本類文件。但要注意SharpCompress 對 7z 的寫入支持在 0.37.2 里是有限的——它不支持加密寫入也不支持固實(shí)壓縮塊的自定義分塊大小。如果你的場景需要這些特性得換別的方案。參數(shù)說明CompressionType.LZMA是 7z 的默認(rèn)算法LZMA2在部分版本里也可用但 0.37.2 的 WriterOptions 對 7z 的可選參數(shù)較少。實(shí)際項(xiàng)目中我一般用 7z 做冷備份zip 做需要廣泛兼容的分發(fā)。提示寫入大文件時(shí)AddEntry會持有源文件句柄直到SaveTo完成。如果源文件在寫入過程中被其他進(jìn)程修改可能拋 IOException。穩(wěn)妥做法是先復(fù)制到臨時(shí)目錄再添加。4. 避坑與排查SharpCompress 0.37.2 的 5 個(gè)血淚教訓(xùn)4.1 中文文件名亂碼現(xiàn)象、原因與解決現(xiàn)象解壓 zip 后中文文件名變成亂碼比如“報(bào)告.csv”變成“±¨??.csv”。原因zip 格式對文件名編碼沒有統(tǒng)一強(qiáng)制標(biāo)準(zhǔn)Windows 下常用 GBK而 SharpCompress 默認(rèn)按 UTF-8 解析。如果歸檔創(chuàng)建時(shí)用的是 GBK 且沒有設(shè)置 UTF-8 標(biāo)志位就會亂碼。解決在讀取時(shí)顯式指定編碼。0.37.2 里可以通過ReaderOptions設(shè)置using SharpCompress.Readers; var options new ReaderOptions { ArchiveEncoding new ArchiveEncoding { Default System.Text.Encoding.GetEncoding(GBK) } }; using (var archive ArchiveFactory.Open(archivePath, options)) { // 遍歷條目時(shí)文件名會按 GBK 解碼 }注意ArchiveEncoding需要引用SharpCompress.Common命名空間。如果歸檔來源不固定可以先嘗試 UTF-8失敗后再回退 GBK。4.2 大文件解壓內(nèi)存暴漲流式與緩沖的取舍現(xiàn)象解壓一個(gè) 2GB 的 zip 時(shí)進(jìn)程內(nèi)存沖到 1.5GB 以上。原因用了entry.WriteToFile之外的方式比如先把entry.OpenEntryStream()讀進(jìn)MemoryStream或者遍歷時(shí)對每個(gè)條目調(diào)用了entry.Size之外的屬性觸發(fā)了內(nèi)部緩沖。解決堅(jiān)持用OpenEntryStream逐塊讀取緩沖區(qū)大小控制在 81920 字節(jié)左右。不要用StreamReader.ReadToEnd()處理大文件。如果必須拿到完整字節(jié)數(shù)組先判斷entry.Size是否超過閾值超過就改用臨時(shí)文件中轉(zhuǎn)。4.3 加密 zip 讀取失敗密碼傳了卻報(bào)錯(cuò)現(xiàn)象帶密碼的 zip 在ArchiveFactory.Open時(shí)直接拋 CryptographicException或者遍歷到加密條目時(shí)才失敗。原因SharpCompress 對加密 zip 的支持分兩種ZipCrypto 和 AES。0.37.2 對 AES 加密的支持需要顯式傳密碼且部分壓縮方法組合不支持。解決打開時(shí)傳入ReaderOptions的Passwordvar options new ReaderOptions { Password yourpassword }; using (var archive ArchiveFactory.Open(archivePath, options)) { // 加密條目在訪問時(shí)才會真正解密 }如果仍然失敗先用 7-Zip 等工具確認(rèn)加密算法AES-256 在 0.37.2 里支持有限必要時(shí)先解密再處理。4.4 路徑穿越ExtractFullPath 不是安全開關(guān)現(xiàn)象解壓惡意 zip 時(shí)文件被寫到了目標(biāo)目錄之外。原因ExtractFullPath true只是保留歸檔內(nèi)的相對路徑不會阻止../向上跳轉(zhuǎn)。解決在Path.Combine之后做規(guī)范化校驗(yàn)string fullDest Path.GetFullPath(Path.Combine(outputDir, entry.Key)); if (!fullDest.StartsWith(Path.GetFullPath(outputDir) Path.DirectorySeparatorChar)) { throw new InvalidOperationException(檢測到路徑穿越: entry.Key); }這一步不能省尤其是處理用戶上傳的歸檔時(shí)。4.5 版本升級后 API 不兼容0.36 到 0.37 的變化現(xiàn)象從 0.36 升級到 0.37.2 后原來能編譯的代碼報(bào)錯(cuò)提示ArchiveFactory.Open重載不存在或WriterOptions構(gòu)造函數(shù)參數(shù)不匹配。原因0.37 系列調(diào)整了部分命名空間和構(gòu)造函數(shù)簽名比如WriterOptions的壓縮類型參數(shù)從枚舉位置參數(shù)改成了屬性初始化。解決升級前先看項(xiàng)目的 Release Notes把new WriterOptions(CompressionType.Deflate)改成new WriterOptions(CompressionType.Deflate) { ... }形式并檢查ArchiveEncoding的引用路徑。如果項(xiàng)目大建議先在一個(gè)分支上升級并跑完所有解壓測試用例。5. 進(jìn)階技巧用 SharpCompress 做批量歸檔校驗(yàn)與格式轉(zhuǎn)換5.1 批量校驗(yàn)歸檔完整性生產(chǎn)環(huán)境里經(jīng)常需要確認(rèn)一批歸檔文件是否損壞。SharpCompress 可以在不完整解壓的情況下做基礎(chǔ)校驗(yàn)遍歷所有條目并嘗試讀取每個(gè)條目的流到末尾不落盤。using SharpCompress.Archives; bool ValidateArchive(string path) { try { using (var archive ArchiveFactory.Open(path)) { foreach (var entry in archive.Entries) { if (entry.IsDirectory) continue; using (var stream entry.OpenEntryStream()) { byte[] buffer new byte[81920]; while (stream.Read(buffer, 0, buffer.Length) 0) { } } } } return true; } catch { return false; } }這個(gè)方法的代價(jià)是完整讀取一遍數(shù)據(jù)但不需要磁盤寫入。對于幾十 MB 的歸檔可以接受上 GB 的歸檔建議抽樣校驗(yàn)或只檢查中央目錄。5.2 格式轉(zhuǎn)換zip 轉(zhuǎn) tar.gz 的流式管道有時(shí)需要把 zip 轉(zhuǎn)成 tar.gz 以便在 Linux 環(huán)境分發(fā)。SharpCompress 支持 tar 和 gzip 寫入可以邊讀邊寫using SharpCompress.Archives; using SharpCompress.Common; using SharpCompress.Writers; using SharpCompress.Writers.Tar; using (var source ArchiveFactory.Open(D:\data\input.zip)) using (var tarStream File.Create(D:\data\output.tar.gz)) using (var writer new TarWriter(tarStream, new TarWriterOptions(CompressionType.GZip, true))) { foreach (var entry in source.Entries) { if (entry.IsDirectory) continue; using (var entryStream entry.OpenEntryStream()) { writer.Write(entry.Key, entryStream, entry.LastModifiedTime ?? DateTime.Now); } } }邏輯說明TarWriter的第二個(gè)參數(shù)true表示在 tar 外層再套 gzip 壓縮。Write方法接收條目名、流和修改時(shí)間。這樣轉(zhuǎn)換不需要中間臨時(shí)文件內(nèi)存占用也穩(wěn)定。參數(shù)說明TarWriterOptions的CompressionType.GZip對應(yīng) .tar.gz改成BZip2就是 .tar.bz2。entry.LastModifiedTime可能為 null用DateTime.Now兜底。5.3 一個(gè)我常用的習(xí)慣每次在項(xiàng)目里引入或升級 SharpCompress我會先寫一個(gè)小的控制臺程序把手上所有格式的樣本各跑一遍zip、7z、tar、tar.gz、rar只讀。跑通之后再寫業(yè)務(wù)代碼。這個(gè)習(xí)慣幫我提前發(fā)現(xiàn)了編碼問題、加密兼容問題和路徑穿越漏洞比在業(yè)務(wù)邏輯里調(diào)試省事得多。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取