簡(jiǎn)介面向.NET開(kāi)發(fā)者的一份C#結(jié)合NPOI操作Excel的實(shí)例包適合需要處理.xls與.xlsx文件的初中級(jí)開(kāi)發(fā)人員也可作為項(xiàng)目?jī)?nèi)封裝Excel工具類的參考。壓縮包共15個(gè)文件以12個(gè)dll依賴庫(kù)、2個(gè)cs示例源碼和1個(gè)xml配置為主整體約2.19MB可快速對(duì)照依賴組織與調(diào)用方式。已有6358人學(xué)習(xí)下載說(shuō)明其在Excel讀寫(xiě)場(chǎng)景中具備一定參考價(jià)值。內(nèi)容圍繞工作簿創(chuàng)建、工作表與行列讀寫(xiě)、單元格樣式設(shè)置、文件保存以及不同Excel格式的兼容處理展開(kāi)并提供兩套版本示例便于比較接口差異與復(fù)用思路讀者可從中梳理NPOI的常用API、工具類封裝方式和基礎(chǔ)異常處理路徑減少在導(dǎo)入導(dǎo)出、報(bào)表生成等任務(wù)中的試錯(cuò)成本。1. 后臺(tái)報(bào)表繞不開(kāi)的那張表我用 NPOI 把它拆成了六個(gè)方法運(yùn)營(yíng)每周上傳一張門店銷售表系統(tǒng)解析入庫(kù)再把統(tǒng)計(jì)結(jié)果導(dǎo)出去這類需求在 C# 后臺(tái)里幾乎躲不掉。很多人第一反應(yīng)是裝 Office 用 Interop結(jié)果服務(wù)器上 EXCEL.EXE 殺不干凈。C# NPOI 操作 Excel 這套組合的價(jià)值就在這里不依賴 Office 安裝環(huán)境.xls和.xlsx共用一套IWorkbook接口十萬(wàn)行也能流式寫(xiě)出去。這份例子把打開(kāi)工作簿、按類型取值、反射映射成對(duì)象、樣式復(fù)用、合并單元格與下拉框、大數(shù)據(jù)量導(dǎo)出拆成互相獨(dú)立的方法適合正在做報(bào)表導(dǎo)入導(dǎo)出、被日期格式和內(nèi)存占用折騰過(guò)的 .NET 開(kāi)發(fā)者照著抄。2. 技術(shù)選型與工程骨架HSSF、XSSF、SXSSF 三套實(shí)現(xiàn)怎么分工NPOI 內(nèi)部并不是一個(gè)工作簿類包打天下而是按文件格式分了三套HSSFWorkbook對(duì)應(yīng) BIFF8 的.xlsXSSFWorkbook對(duì)應(yīng) OOXML 的.xlsxSXSSFWorkbook是 XSSF 的流式寫(xiě)版本。它們都實(shí)現(xiàn)了IWorkbook、ISheet、IRow、ICell這組接口所以業(yè)務(wù)代碼只要面向接口寫(xiě)格式差異就能被擋在工廠方法后面。這一章先把選型理由和工程骨架定下來(lái)后面幾章的讀寫(xiě)代碼才有地方放。2.1 為什么這套例子不用 Interop、OleDb 和 OpenXML SDKInterop 是最像“人在操作 Excel”的方案錄制宏再翻譯成 C# 幾乎不用思考。代價(jià)也很直接服務(wù)器必須裝 Office進(jìn)程里容易殘留 EXCEL.EXEIIS 應(yīng)用池身份一收緊就報(bào)權(quán)限錯(cuò)誤。我在一個(gè)定時(shí)任務(wù)里見(jiàn)過(guò)這種寫(xiě)法跑三天之后任務(wù)管理器里堆了四十多個(gè)隱藏進(jìn)程機(jī)器內(nèi)存一路漲——這種翻車不是配置能救的是方案本身不適合服務(wù)端。OleDb 走的是數(shù)據(jù)庫(kù)思路把 Sheet 當(dāng)表來(lái)查。讀還行寫(xiě)幾乎沒(méi)法用還要在目標(biāo)機(jī)器上配對(duì)應(yīng)位數(shù)的驅(qū)動(dòng)32 位和 64 位不匹配時(shí)報(bào)的錯(cuò)還特別模糊。OpenXML SDK 是官方的 OOXML 實(shí)現(xiàn)規(guī)范嚴(yán)謹(jǐn)?shù)a啰嗦得厲害寫(xiě)一個(gè)單元格要 new 一串對(duì)象而且它只認(rèn).xlsx老系統(tǒng)導(dǎo)出的.xls完全不支持。NPOI 的定位正好卡在中間。它把 Java 那套 POI 移植過(guò)來(lái)讀取、寫(xiě)入、樣式、公式、數(shù)據(jù)驗(yàn)證都有對(duì)應(yīng) API純托管實(shí)現(xiàn)容器里不用裝 Office。前些年另一個(gè)同類開(kāi)源庫(kù)改了授權(quán)協(xié)議之后不少團(tuán)隊(duì)又遷回 NPOI生態(tài)和文檔也就更全了。方案運(yùn)行依賴支持格式主要問(wèn)題Interop必須安裝 Officexls / xlsx進(jìn)程殘留、權(quán)限敏感、不適合 WebOleDb需要對(duì)應(yīng)位數(shù)驅(qū)動(dòng)以 xls 為主只能讀、寫(xiě)入能力弱、類型靠猜OpenXML SDK無(wú)僅 xlsxAPI 偏底層、不支持老格式NPOI HSSF / XSSF無(wú)xls / xlsx全量加載大文件吃內(nèi)存NPOI SXSSF無(wú)僅 xlsx只能寫(xiě)不能讀需要清理臨時(shí)文件2.2 依賴引入與目錄結(jié)構(gòu)建工程的部分沒(méi)什么玄學(xué)兩個(gè)項(xiàng)目就夠一個(gè)類庫(kù)放封裝一個(gè)控制臺(tái)負(fù)責(zé)跑例子驗(yàn)證。NPOI 通過(guò) NuGet 裝一個(gè)包里面已經(jīng)包含了 HSSF、XSSF、SXSSF 三套實(shí)現(xiàn)不需要額外引用別的包。# 解決方案 類庫(kù) 控制臺(tái)示例 dotnet new sln -n ExcelKit dotnet new classlib -o src/ExcelKit.Core -f net8.0 dotnet new console -o src/ExcelKit.Demo -f net8.0 dotnet sln add src/ExcelKit.Core src/ExcelKit.Demo # 示例項(xiàng)目引用類庫(kù)類庫(kù)引用 NPOI dotnet add src/ExcelKit.Demo reference src/ExcelKit.Core dotnet add src/ExcelKit.Core package NPOI-f net8.0換成你手上的 LTS 版本即可NPOI 對(duì)框架版本不挑。裝完之后目錄我一般這么切讀和寫(xiě)分開(kāi)轉(zhuǎn)換邏輯單獨(dú)抽出來(lái)這樣后面加csv導(dǎo)出或者換別的庫(kù)都不會(huì)牽一發(fā)動(dòng)全身ExcelKit/ ├── ExcelKit.sln ├── src/ │ ├── ExcelKit.Core/ │ │ ├── Abstractions/ExcelOptions.cs # 表頭行、起始行、是否跳過(guò)空行 │ │ ├── Attributes/ExcelColumnAttribute.cs # 列名和屬性的映射 │ │ ├── Internal/CellValueConverter.cs # 原始值到 CLR 類型的轉(zhuǎn)換 │ │ ├── Internal/StyleCache.cs # 樣式緩存避免超上限 │ │ ├── Reading/ExcelReader.cs # 打開(kāi)、遍歷、反射賦值 │ │ ├── Writing/ExcelWriter.cs # xls / xlsx 常規(guī)導(dǎo)出 │ │ └── Writing/SxssfExcelWriter.cs # 大數(shù)據(jù)量流式導(dǎo)出 │ └── ExcelKit.Demo/ │ ├── Program.cs │ ├── Models/OrderRow.cs │ └── samples/ # 放測(cè)試用的 xls、xlsx文件職責(zé)關(guān)鍵點(diǎn)ExcelOptions.cs表頭行號(hào)、數(shù)據(jù)起始行、空行策略不同來(lái)源的表頭位置經(jīng)常不一樣ExcelColumnAttribute.cs列名到屬性的映射表頭改名不影響實(shí)體CellValueConverter.cs日期、數(shù)字、布爾、枚舉的轉(zhuǎn)換所有類型判斷集中在一處ExcelReader.cs讀工作簿并映射成ListT處理空行、空單元格ExcelWriter.cs常規(guī)導(dǎo)出、樣式、合并、下拉樣式必須緩存復(fù)用SxssfExcelWriter.cs十萬(wàn)行級(jí)導(dǎo)出Dispose負(fù)責(zé)清臨時(shí)文件2.3 一個(gè)能跑通的最小閉環(huán)在拆細(xì)節(jié)之前先讓讀寫(xiě)跑通一次確認(rèn)包引用沒(méi)問(wèn)題。下面這段是示例項(xiàng)目里Program.cs的核心負(fù)責(zé)按擴(kuò)展名創(chuàng)建工作簿、保存、再打開(kāi)讀回來(lái)using NPOI.HSSF.UserModel; using NPOI.SS.UserModel; using NPOI.XSSF.UserModel; // 按擴(kuò)展名選擇實(shí)現(xiàn).xls 走 HSSF.xlsx 走 XSSF static IWorkbook CreateWorkbook(string path) { var ext Path.GetExtension(path).ToLowerInvariant(); return ext switch { .xls new HSSFWorkbook(), // BIFF8最多 65536 行、256 列 .xlsx new XSSFWorkbook(), // OOXML最多 1048576 行 _ throw new NotSupportedException($不支持的擴(kuò)展名: {ext}) }; } // 先寫(xiě)臨時(shí)文件再替換避免目標(biāo)文件被占用時(shí)把原文件寫(xiě)壞 static void SaveWorkbook(IWorkbook workbook, string path) { var tmp path .tmp; using (var fs new FileStream(tmp, FileMode.Create, FileAccess.Write)) { workbook.Write(fs); // Write 不會(huì)替你關(guān)閉傳入的流 fs.Flush(); } File.Move(tmp, path, overwrite: true); } // 打開(kāi)時(shí)交給工廠方法讀文件頭自動(dòng)判斷格式 static IWorkbook OpenWorkbook(string path) WorkbookFactory.Create(File.OpenRead(path));CreateWorkbook的意義在于把“用哪套實(shí)現(xiàn)”這件事收斂到一個(gè)地方業(yè)務(wù)代碼只拿到IWorkbook。SaveWorkbook里那個(gè)臨時(shí)文件加File.Move的寫(xiě)法是血淚經(jīng)驗(yàn)?zāi)繕?biāo)文件正被 Excel 打開(kāi)時(shí)直接FileMode.Create會(huì)拋IOException更糟的是有些情況下文件被截?cái)嗔瞬攀∮脩裟玫揭粋€(gè)打不開(kāi)的 xlsx。走臨時(shí)文件至少保證原文件完好。WorkbookFactory.Create接受流它自己讀魔數(shù)判斷是 BIFF 還是 ZIP 包所以讀取端完全不用關(guān)心擴(kuò)展名——順帶說(shuō)一句用戶把.xlsx改成.xls傳上來(lái)的情況真有工廠方法能兜住按擴(kuò)展名判斷的寫(xiě)法就翻車了。提示W(wǎng)orkbookFactory.Create(Stream)之后不要立刻把流 Dispose 掉工作簿內(nèi)部還引用著它后續(xù)操作可能報(bào)“無(wú)法訪問(wèn)已關(guān)閉的流”。3. 讀取鏈路拆解從工作簿到單元格把 Excel 當(dāng)半結(jié)構(gòu)化數(shù)據(jù)源讀取看著簡(jiǎn)單實(shí)際是坑最集中的一段。Excel 不是數(shù)據(jù)庫(kù)沒(méi)有列類型單元格里存的可能是文本、可能是數(shù)字、可能是公式日期還是個(gè)偽裝成數(shù)字的 double。這一章按“定位 Sheet → 取值 → 映射成對(duì)象”三步走每一步都給可直接用的代碼。3.1 定位 Sheet 與遍歷有效行第一步是把 Sheet 拿到手。用戶傳上來(lái)的文件里常有隱藏 Sheet、說(shuō)明頁(yè)、匯總頁(yè)按名字取最穩(wěn)取不到再退回第一個(gè)// 名字優(yōu)先名字為空或找不到時(shí)退回第一個(gè) Sheet public static ISheet GetSheet(IWorkbook wb, string? name) (string.IsNullOrWhiteSpace(name) ? null : wb.GetSheet(name)) ?? wb.GetSheetAt(0);遍歷行的時(shí)候有兩個(gè)屬性容易混LastRowNum是最后一行的索引0 基空表返回 -1PhysicalNumberOfRows是實(shí)際有內(nèi)容的行數(shù)。很多人拿PhysicalNumberOfRows當(dāng)循環(huán)上界遇到中間夾了空行就少讀一截。正確姿勢(shì)是用FirstRowNum到LastRowNum閉區(qū)間遍歷然后對(duì)每一行判空var sheet GetSheet(wb, 明細(xì)); if (sheet.PhysicalNumberOfRows 0) return new ListOrderRow(); var first sheet.FirstRowNum; // 通常就是表頭行 var last sheet.LastRowNum; // 注意被格式化過(guò)的空行也會(huì)算進(jìn)來(lái) for (var r first 1; r last; r) { var row sheet.GetRow(r); // 越界或沒(méi)內(nèi)容的行會(huì)返回 null if (row is null) continue; // ... 逐格取值 }GetRow返回 null 這件事必須處理LastRowNum會(huì)把“只設(shè)過(guò)格式?jīng)]填過(guò)值”的行也算進(jìn)去表格末尾拖了一片帶邊框的空行是常態(tài)。不加判空線上就會(huì)收到一堆NullReferenceException堆棧還指在業(yè)務(wù)代碼里排查起來(lái)像個(gè)黑匣子。3.2 單元格取值類型分支是繞不過(guò)去的ICell的CellType決定了你能調(diào)哪個(gè)屬性。對(duì)著一個(gè)文本單元格取NumericCellValue拋的是InvalidOperationException消息還只告訴你類型不對(duì)。更麻煩的是公式單元格它的CellType是Formula真實(shí)結(jié)果藏在CachedFormulaResultType里得先看緩存類型再?zèng)Q定怎么取。public static object? GetValue(ICell? cell) { if (cell is null) return null; // 公式單元格不能直接按 CellType 分支要先看緩存結(jié)果的類型 var type cell.CellType CellType.Formula ? cell.CachedFormulaResultType : cell.CellType; switch (type) { case CellType.String: return cell.StringCellValue; case CellType.Boolean: return cell.BooleanCellValue; case CellType.Numeric: // 日期在文件里就是個(gè) double只能靠單元格格式判斷 return DateUtil.IsCellDateFormatted(cell) ? DateUtil.GetJavaDate(cell.NumericCellValue) : cell.NumericCellValue; case CellType.Blank: return null; case CellType.Error: // #DIV/0!、#N/A 這類錯(cuò)誤值轉(zhuǎn)成字符串保留原始信息 return FormulaError.ForInt(cell.ErrorCellValue).String; default: return cell.ToString(); } }DateUtil.IsCellDateFormatted判斷的是單元格的顯示格式不是值本身——同樣是45000格式是日期就是 2023 年某天格式是常規(guī)就還是個(gè)數(shù)字。這個(gè)判斷一定要在取NumericCellValue之前做反過(guò)來(lái)先取值再判斷得到的已經(jīng)是 double 了沒(méi)有格式信息可查。DateUtil.GetJavaDate名字里帶 Java 是歷史遺留返回的是 .NET 的DateTime直接用就行。它按 1900 日期系統(tǒng)換算Excel 那個(gè)“1900 年不是閏年”的歷史 bug NPOI 已經(jīng)處理了不用自己補(bǔ)一天。如果只是要把內(nèi)容原樣展示比如做預(yù)覽還有個(gè)更省事的辦法new DataFormatter().FormatCellValue(cell)它按單元格格式渲染成字符串0.00%、￥#,##0.00這些格式都能還原。缺點(diǎn)是拿到的是字符串后續(xù)做數(shù)值計(jì)算還得再轉(zhuǎn)一次我一般只在日志和預(yù)覽里用。3.3 反射映射成對(duì)象讓表頭變化不影響實(shí)體逐格GetValue再手寫(xiě)賦值字段一多就容易錯(cuò)位。用一個(gè)特性標(biāo)出列名讀取時(shí)按表頭建索引屬性順序調(diào)整、中間插列都不會(huì)影響結(jié)果[AttributeUsage(AttributeTargets.Property)] public sealed class ExcelColumnAttribute : Attribute { public ExcelColumnAttribute(string header) Header header; public string Header { get; } public bool Required { get; init; } } public sealed class OrderRow { [ExcelColumn(門店名稱, Required true)] public string StoreName { get; set; } ; [ExcelColumn(訂單日期)] public DateTime OrderDate { get; set; } [ExcelColumn(金額)] public decimal Amount { get; set; } [ExcelColumn(狀態(tài))] public string? Status { get; set; } }映射邏輯本身不復(fù)雜難點(diǎn)在容錯(cuò)表頭可能有空格、可能有合并單元格留下的空列、類型轉(zhuǎn)換可能失敗。public static ListT ReadSheetT(ISheet sheet, ExcelOptions options) where T : new() { var headerRow sheet.GetRow(options.HeaderRowIndex) ?? throw new InvalidDataException(表頭行不存在); // 列索引 - 屬性忽略表頭里的空白列 var map new Dictionaryint, PropertyInfo(); for (var c headerRow.FirstCellNum; c headerRow.LastCellNum; c) { var header GetValue(headerRow.GetCell(c))?.ToString()?.Trim(); if (string.IsNullOrEmpty(header)) continue; var prop typeof(T).GetProperties() .FirstOrDefault(p p.GetCustomAttributeExcelColumnAttribute()?.Header header); if (prop is not null) map[c] prop; } var list new ListT(); for (var r options.DataStartRowIndex; r sheet.LastRowNum; r) { var row sheet.GetRow(r); if (row is null) continue; var item new T(); var hasValue false; foreach (var (col, prop) in map) { var raw GetValue(row.GetCell(col, MissingCellPolicy.CREATE_NULL_AS_BLANK)); if (raw is null || raw is string s s.Length 0) continue; prop.SetValue(item, CellValueConverter.Convert(raw, prop.PropertyType)); hasValue true; } if (hasValue) list.Add(item); // 整行全空就丟掉 } return list; }幾個(gè)參數(shù)值得說(shuō)MissingCellPolicy.CREATE_NULL_AS_BLANK讓不存在的單元格返回一個(gè) Blank 單元格而不是 null省掉一層判空options.HeaderRowIndex和DataStartRowIndex分開(kāi)配置是因?yàn)橛行┠０宓谝恍惺谴髽?biāo)題、第二行才是表頭。Convert方法里要處理NullableT、枚舉、decimal的InvariantCulture轉(zhuǎn)換。金額字段最容易出事源文件里是1234.56服務(wù)器區(qū)域設(shè)置是德語(yǔ)Convert.ToDecimal會(huì)把點(diǎn)當(dāng)千分位讀出 123456。統(tǒng)一用CultureInfo.InvariantCulture轉(zhuǎn)換能省掉一大半“數(shù)據(jù)對(duì)不上”的工單。4. 寫(xiě)入與導(dǎo)出樣式緩存、合并單元格和十萬(wàn)行的流式寫(xiě)法寫(xiě)比讀更容易埋雷因?yàn)楹芏鄦?wèn)題不會(huì)當(dāng)場(chǎng)報(bào)錯(cuò)而是等用戶用 Excel 打開(kāi)時(shí)才提示“發(fā)現(xiàn)不可讀取的內(nèi)容”。這一章按常規(guī)導(dǎo)出、表頭樣式與交互元素、大數(shù)據(jù)量三條線拆重點(diǎn)講樣式復(fù)用和 SXSSF 的窗口機(jī)制。4.1 樣式緩存別在循環(huán)里 CreateCellStyleNPOI 的ICellStyle是工作簿級(jí)別的對(duì)象每個(gè)工作簿能創(chuàng)建的樣式數(shù)量有上限.xls是 4000 左右.xlsx是 64000。你寫(xiě)row.CreateCell(0).CellStyle wb.CreateCellStyle()放在一萬(wàn)行的循環(huán)里前幾千行沒(méi)問(wèn)題后面直接拋異常報(bào)錯(cuò)信息還只說(shuō)“樣式數(shù)量超出限制”。字體同理CreateFont也是有限額的。正確做法是按用途緩存整個(gè)工作簿復(fù)用同一份public sealed class StyleCache { private readonly IWorkbook _wb; private readonly Dictionarystring, ICellStyle _cache new(); public StyleCache(IWorkbook wb) _wb wb; public ICellStyle GetHeaderStyle() { if (_cache.TryGetValue(header, out var cached)) return cached; var style _wb.CreateCellStyle(); style.Alignment HorizontalAlignment.Center; style.VerticalAlignment VerticalAlignment.Center; style.FillForegroundColor IndexedColors.Grey25Percent.Index; style.FillPattern FillPattern.SolidForeground; style.BorderBottom BorderStyle.Thin; style.WrapText true; var font _wb.CreateFont(); font.IsBold true; font.FontHeightInPoints 11; style.SetFont(font); _cache[header] style; return style; } public ICellStyle GetDateStyle() { if (_cache.TryGetValue(date, out var cached)) return cached; var style _wb.CreateCellStyle(); style.DataFormat _wb.CreateDataFormat().GetFormat(yyyy-mm-dd); _cache[date] style; return style; } }DataFormat那段也值得單獨(dú)拎出來(lái)日期列如果不設(shè)格式寫(xiě)進(jìn)去的DateTime打開(kāi)后顯示成一串45123用戶第一反應(yīng)是系統(tǒng)壞了。CreateDataFormat().GetFormat(...)返回的是格式索引同一個(gè)格式字符串重復(fù)調(diào)用會(huì)得到同一個(gè)索引所以緩存不是強(qiáng)制的但樣式對(duì)象必須緩存。4.2 合并單元格、凍結(jié)窗格、下拉框與公式報(bào)表類導(dǎo)出的“專業(yè)感”基本靠這幾樣堆出來(lái)標(biāo)題行合并居中、表頭凍結(jié)、狀態(tài)列給下拉框、合計(jì)行用公式。這些 API 在 HSSF 和 XSSF 上是同一套接口只有底層實(shí)現(xiàn)不同所以代碼不用分叉。var sheet wb.CreateSheet(明細(xì)); // 第一行放大標(biāo)題合并 A1:F1 var titleRow sheet.CreateRow(0); titleRow.CreateCell(0).SetCellValue(門店銷售明細(xì)); sheet.AddMergedRegion(new CellRangeAddress(0, 0, 0, 5)); // 首行, 末行, 首列, 末列 // 凍結(jié)前兩行橫向滾動(dòng)時(shí)列頭還在 sheet.CreateFreezePane(0, 2); // 狀態(tài)列給下拉框范圍到第 5000 行 var helper sheet.GetDataValidationHelper(); var constraint helper.CreateExplicitListConstraint(new[] { 待審核, 已審核, 已駁回 }); var validation helper.CreateValidation(constraint, new CellRangeAddressList(2, 5000, 5, 5)); validation.ShowErrorBox true; validation.CreateErrorBox(取值不合法, 請(qǐng)從下拉列表里選擇狀態(tài)); sheet.AddValidationData(validation); // 合計(jì)行走公式讓 Excel 自己算比在服務(wù)端算好再寫(xiě)死更靈活 var totalRow sheet.CreateRow(sheet.LastRowNum 1); totalRow.CreateCell(0).SetCellValue(合計(jì)); totalRow.CreateCell(3).SetCellFormula($SUM(D3:D{totalRow.RowNum}));CellRangeAddress的參數(shù)順序是行在前、列在后四個(gè)值分別是首行、末行、首列、末列全部 0 基。合并時(shí)如果只寫(xiě)了左上角單元格的值其余單元格留空某些版本的 Excel 打開(kāi)會(huì)警告穩(wěn)妥做法是給合并區(qū)域每個(gè)格子都建出來(lái)再設(shè)值。公式單元格寫(xiě)進(jìn)去之后CachedFormulaResultType在你這邊是空的——NPOI 不做計(jì)算。所以別的系統(tǒng)讀這個(gè)文件時(shí)如果直接取緩存值拿到的是 0 或者空。要么在服務(wù)端算好寫(xiě)成值要么在文件打開(kāi)時(shí)讓 Excel 重算一次設(shè)置wb.ForceFormulaRecalculation true就能讓 Excel 打開(kāi)時(shí)算一遍。注意CreateFreezePane(0, 2)的第一個(gè)參數(shù)是凍結(jié)的列數(shù)傳 0 表示只凍行別把行列順序記反了。4.3 SXSSF 流式導(dǎo)出十萬(wàn)行不該進(jìn)內(nèi)存XSSFWorkbook是全內(nèi)存模型一行十列十萬(wàn)行大概要吃掉幾百兆加上 GC 壓力服務(wù)器上很容易直接 OOM。SXSSFWorkbook的思路是滑動(dòng)窗口內(nèi)存里只保留最近 N 行超出的部分刷到臨時(shí)文件最后合并成一個(gè) xlsx 包。窗口大小在構(gòu)造函數(shù)里指定public void ExportLarge(string path, IEnumerableOrderRow rows, int window 500) { // window 是內(nèi)存中保留的行數(shù)超過(guò)就刷到磁盤(pán)臨時(shí)文件 using var wb new SXSSFWorkbook(window); // Dispose 時(shí)會(huì)刪掉臨時(shí)文件 wb.CompressTemporaryFiles true; var sheet wb.CreateSheet(明細(xì)); var styles new StyleCache(wb); var headerStyle styles.GetHeaderStyle(); var dateStyle styles.GetDateStyle(); var r 0; var header sheet.CreateRow(r); string[] headers { 門店名稱, 訂單日期, 金額, 狀態(tài) }; for (var c 0; c headers.Length; c) { var cell header.CreateCell(c); cell.SetCellValue(headers[c]); cell.CellStyle headerStyle; } foreach (var item in rows) { var row sheet.CreateRow(r); row.CreateCell(0).SetCellValue(item.StoreName); var dateCell row.CreateCell(1); dateCell.SetCellValue(item.OrderDate); dateCell.CellStyle dateStyle; // 日期列套格式否則顯示成數(shù)字 row.CreateCell(2).SetCellValue((double)item.Amount); row.CreateCell(3).SetCellValue(item.Status ?? ); } using var fs new FileStream(path, FileMode.Create, FileAccess.Write); wb.Write(fs); }窗口大小不是越大越好。設(shè)成 500內(nèi)存里最多五百行臨時(shí)文件會(huì)多一點(diǎn)設(shè)成 50000內(nèi)存優(yōu)勢(shì)就不明顯了。我一般按單行寬度估十列左右的表500 到 1000 是比較平衡的值。using那句不能省。SXSSFWorkbook在%TEMP%下建臨時(shí)文件只有Dispose才會(huì)清理。少寫(xiě)一個(gè)using跑一周之后磁盤(pán)告警DBA 找過(guò)來(lái)你還得先解釋這不是日志文件。另外 SXSSF 只能寫(xiě)不能讀AutoSizeColumn也只在設(shè)置了TrackAllColumnsForAutoSizing之后才有意義寬表上還特別慢我一般直接按內(nèi)容估算列寬寫(xiě)死。5. 避坑與排查NPOI 上線后必然撞上的 5 個(gè)問(wèn)題下面五條都是踩過(guò)之后寫(xiě)進(jìn)回歸用例的遇到報(bào)錯(cuò)別急著搜異常消息先按現(xiàn)象對(duì)一遍。5.1 報(bào)“文件正由另一進(jìn)程使用”或讀出來(lái)是空表現(xiàn)象導(dǎo)出時(shí)拋IOException: The process cannot access the file或者讀文件時(shí)PhysicalNumberOfRows是 0但用 Excel 打開(kāi)明明有數(shù)據(jù)。原因?qū)懧窂缴夏繕?biāo)文件正被 Excel 或預(yù)覽服務(wù)打開(kāi)讀路徑上是File.OpenRead之后又用using提前釋放了流WorkbookFactory.Create內(nèi)部還引用著它讀到一半拿到空數(shù)據(jù)。解決寫(xiě)走臨時(shí)文件加File.Move(tmp, path, overwrite: true)讀的時(shí)候讓流的生命周期覆蓋工作簿的整個(gè)使用期要么不用using要么改成先把整個(gè)文件讀進(jìn)MemoryStream再創(chuàng)建。上傳接口還有個(gè)常見(jiàn)原因前端傳的是 0 字節(jié)文件Length 0直接攔掉別讓它走到 NPOI 里。5.2 日期讀成 45000 多金額多出幾位小數(shù)現(xiàn)象OrderDate字段全是45123這種數(shù)字金額1234.56讀成123456或者變成1234.5600000000001。原因日期在 xlsx 里本來(lái)就是個(gè) double沒(méi)走DateUtil.IsCellDateFormatted判斷就當(dāng)成普通數(shù)字返回了金額問(wèn)題一半來(lái)自double的二進(jìn)制精度一半來(lái)自區(qū)域設(shè)置——服務(wù)器用逗號(hào)做小數(shù)點(diǎn)時(shí)decimal.Parse會(huì)按當(dāng)?shù)亓?xí)慣解析。解決取值前先判日期格式金額一律Convert.ToDecimal(raw, CultureInfo.InvariantCulture)實(shí)體里的金額字段用decimal不用double。反方向?qū)С鰰r(shí)也一樣寫(xiě)double進(jìn)去再讀出來(lái)對(duì)比最后一位對(duì)不上就是精度問(wèn)題。5.3 十萬(wàn)行導(dǎo)出內(nèi)存飆升進(jìn)程被 OOM 殺掉現(xiàn)象導(dǎo)出任務(wù)跑到一半容器重啟日志里沒(méi)有任何異常堆棧只有一條退出碼。原因用了XSSFWorkbook全量加載每行每格都是完整對(duì)象十萬(wàn)行輕松幾百兆疊加并發(fā)導(dǎo)出內(nèi)存直接頂?shù)饺萜魃舷?。解決超過(guò)兩萬(wàn)行走SXSSFWorkbook窗口設(shè) 500 到 1000同時(shí)限制并發(fā)導(dǎo)出數(shù)量用信號(hào)量控制在兩三個(gè)導(dǎo)出任務(wù)改成后臺(tái)隊(duì)列加下載鏈接別讓用戶點(diǎn)一下就在請(qǐng)求線程里同步跑完。另外注意SXSSFWorkbook的臨時(shí)文件目錄容器里/tmp默認(rèn)可能只有幾百兆。5.4 樣式超出上限或者 Excel 打開(kāi)提示“發(fā)現(xiàn)不可讀取的內(nèi)容”現(xiàn)象小數(shù)據(jù)量導(dǎo)出正常行數(shù)一多就拋樣式超限異?；蛘呶募苌捎?Excel 打開(kāi)彈修復(fù)提示。原因循環(huán)里CreateCellStyle沒(méi)有復(fù)用修復(fù)提示多半是合并區(qū)域和已有數(shù)據(jù)重疊、Sheet 名超過(guò) 31 個(gè)字符、或者.xls里用了只有.xlsx支持的寫(xiě)法。解決樣式統(tǒng)一走緩存類字體也一樣寫(xiě)之前校驗(yàn) Sheet 名長(zhǎng)度和非法字符[]:*?/\.xls導(dǎo)出時(shí)把行數(shù)控制在 65536 以內(nèi)超了直接給用戶提示換 xlsx別等HSSFWorkbook寫(xiě)到一半拋異常。5.5 容器里 AutoSizeColumn 拋異?；蛘袑挾茸兂?0現(xiàn)象本地 Windows 跑得好好的部署到 Linux 容器后AutoSizeColumn拋異?；蛘吡袑捜兂赡J(rèn)值。原因自動(dòng)列寬需要測(cè)量文字渲染寬度較新的 NPOI 用純托管的字體庫(kù)容器鏡像里沒(méi)裝對(duì)應(yīng)字體就測(cè)不出來(lái)用老版本的話還會(huì)依賴系統(tǒng)圖形庫(kù)Linux 上直接報(bào)libgdiplus找不到。解決鏡像里裝一套基礎(chǔ)字體比如開(kāi)源的中文字體包或者干脆放棄自動(dòng)寬度按列的字符數(shù)手動(dòng)SetColumnWidth(c, Math.Min(255, maxLen * 256))穩(wěn)定又不受環(huán)境影響。6. 二次開(kāi)發(fā)把散落各處的 NPOI 調(diào)用收成一個(gè)導(dǎo)出服務(wù)接手過(guò)的幾個(gè)項(xiàng)目里NPOI 的調(diào)用最后都會(huì)散成一地A 類里一個(gè)new XSSFWorkbook()B 服務(wù)里又一份樣式代碼C 接口為了加一列改了三處。改造方向很明確——只暴露一個(gè)IExcelService入?yún)⑹菙?shù)據(jù)集合和一個(gè)配置對(duì)象出參是byte[]或臨時(shí)文件路徑業(yè)務(wù)層不該出現(xiàn)ICell、ICellStyle這些類型。public interface IExcelService { byte[] ExportT(IReadOnlyListT data, ExcelExportOptions? options null); ListT ImportT(Stream stream, ExcelOptions? options null) where T : new(); }實(shí)現(xiàn)里把前面幾章的東西拼起來(lái)ExcelExportOptions帶上格式xls / xlsx、Sheet 名、是否凍結(jié)表頭、列寬策略導(dǎo)出時(shí)按數(shù)據(jù)量自動(dòng)切XSSFWorkbook和SXSSFWorkbook列定義全部來(lái)自ExcelColumnAttribute加字段不用改導(dǎo)出代碼。改造前后差別很明顯改造前改造后每個(gè)接口各寫(xiě)一份樣式樣式只在StyleCache里定義一次加一列改三處代碼實(shí)體加個(gè)特性即可數(shù)據(jù)量一大就 OOM按行數(shù)自動(dòng)走 SXSSF表頭改名導(dǎo)致導(dǎo)入失敗按列名匹配找不到列直接報(bào)錯(cuò)并指出列名驗(yàn)證方法我一般用金標(biāo)準(zhǔn)對(duì)比準(zhǔn)備一份人工核對(duì)過(guò)的樣本表跑導(dǎo)入后序列化成 JSON 存進(jìn)倉(cāng)庫(kù)作為回歸基線導(dǎo)出則把生成的文件再讀回來(lái)逐格對(duì)比關(guān)鍵字段。這樣做的好處是日期格式、空行、合并單元格這些玄學(xué)問(wèn)題都能被自動(dòng)兜住而不是等運(yùn)營(yíng)反饋。改的時(shí)候有個(gè)技巧先別動(dòng)業(yè)務(wù)代碼在原來(lái)的調(diào)用點(diǎn)上加一層IExcelService適配用舊邏輯實(shí)現(xiàn)接口跑通之后再換內(nèi)部實(shí)現(xiàn)。這樣出問(wèn)題時(shí)能立刻切回去不用回滾整個(gè)分支。從那以后我每次接報(bào)表需求都先把表頭、空行、日期格式這三件事寫(xiě)成回歸用例再動(dòng)手比事后加班查數(shù)據(jù)對(duì)不上劃算多了。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取