簡介面向.NET開發(fā)者的一份C#結(jié)合NPOI操作Excel的實(shí)例包適合需要處理.xls與.xlsx文件的初中級開發(fā)人員也可作為項(xiàng)目內(nèi)封裝Excel工具類的參考。壓縮包共15個(gè)文件以12個(gè)dll依賴庫、2個(gè)cs示例源碼和1個(gè)xml配置為主整體約2.19MB可快速對照依賴組織與調(diào)用方式。已有6358人學(xué)習(xí)下載說明其在Excel讀寫場景中具備一定參考價(jià)值。內(nèi)容圍繞工作簿創(chuàng)建、工作表與行列讀寫、單元格樣式設(shè)置、文件保存以及不同Excel格式的兼容處理展開并提供兩套版本示例便于比較接口差異與復(fù)用思路讀者可從中梳理NPOI的常用API、工具類封裝方式和基礎(chǔ)異常處理路徑減少在導(dǎo)入導(dǎo)出、報(bào)表生成等任務(wù)中的試錯(cuò)成本。1. 后臺(tái)報(bào)表繞不開的那張表我用 NPOI 把它拆成了六個(gè)方法運(yùn)營每周上傳一張門店銷售表系統(tǒng)解析入庫再把統(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接口十萬行也能流式寫出去。這份例子把打開工作簿、按類型取值、反射映射成對象、樣式復(fù)用、合并單元格與下拉框、大數(shù)據(jù)量導(dǎo)出拆成互相獨(dú)立的方法適合正在做報(bào)表導(dǎo)入導(dǎo)出、被日期格式和內(nèi)存占用折騰過的 .NET 開發(fā)者照著抄。2. 技術(shù)選型與工程骨架HSSF、XSSF、SXSSF 三套實(shí)現(xiàn)怎么分工NPOI 內(nèi)部并不是一個(gè)工作簿類包打天下而是按文件格式分了三套HSSFWorkbook對應(yīng) BIFF8 的.xlsXSSFWorkbook對應(yīng) OOXML 的.xlsxSXSSFWorkbook是 XSSF 的流式寫版本。它們都實(shí)現(xiàn)了IWorkbook、ISheet、IRow、ICell這組接口所以業(yè)務(wù)代碼只要面向接口寫格式差異就能被擋在工廠方法后面。這一章先把選型理由和工程骨架定下來后面幾章的讀寫代碼才有地方放。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ù)里見過這種寫法跑三天之后任務(wù)管理器里堆了四十多個(gè)隱藏進(jìn)程機(jī)器內(nèi)存一路漲——這種翻車不是配置能救的是方案本身不適合服務(wù)端。OleDb 走的是數(shù)據(jù)庫思路把 Sheet 當(dāng)表來查。讀還行寫幾乎沒法用還要在目標(biāo)機(jī)器上配對應(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啰嗦得厲害寫一個(gè)單元格要 new 一串對象而且它只認(rèn).xlsx老系統(tǒng)導(dǎo)出的.xls完全不支持。NPOI 的定位正好卡在中間。它把 Java 那套 POI 移植過來讀取、寫入、樣式、公式、數(shù)據(jù)驗(yàn)證都有對應(yīng) API純托管實(shí)現(xiàn)容器里不用裝 Office。前些年另一個(gè)同類開源庫改了授權(quán)協(xié)議之后不少團(tuán)隊(duì)又遷回 NPOI生態(tài)和文檔也就更全了。方案運(yùn)行依賴支持格式主要問題Interop必須安裝 Officexls / xlsx進(jìn)程殘留、權(quán)限敏感、不適合 WebOleDb需要對應(yīng)位數(shù)驅(qū)動(dòng)以 xls 為主只能讀、寫入能力弱、類型靠猜OpenXML SDK無僅 xlsxAPI 偏底層、不支持老格式NPOI HSSF / XSSF無xls / xlsx全量加載大文件吃內(nèi)存NPOI SXSSF無僅 xlsx只能寫不能讀需要清理臨時(shí)文件2.2 依賴引入與目錄結(jié)構(gòu)建工程的部分沒什么玄學(xué)兩個(gè)項(xiàng)目就夠一個(gè)類庫放封裝一個(gè)控制臺(tái)負(fù)責(zé)跑例子驗(yàn)證。NPOI 通過 NuGet 裝一個(gè)包里面已經(jīng)包含了 HSSF、XSSF、SXSSF 三套實(shí)現(xiàn)不需要額外引用別的包。# 解決方案 類庫 控制臺(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)目引用類庫類庫引用 NPOI dotnet add src/ExcelKit.Demo reference src/ExcelKit.Core dotnet add src/ExcelKit.Core package NPOI-f net8.0換成你手上的 LTS 版本即可NPOI 對框架版本不挑。裝完之后目錄我一般這么切讀和寫分開轉(zhuǎn)換邏輯單獨(dú)抽出來這樣后面加csv導(dǎo)出或者換別的庫都不會(huì)牽一發(fā)動(dòng)全身ExcelKit/ ├── ExcelKit.sln ├── src/ │ ├── ExcelKit.Core/ │ │ ├── Abstractions/ExcelOptions.cs # 表頭行、起始行、是否跳過空行 │ │ ├── Attributes/ExcelColumnAttribute.cs # 列名和屬性的映射 │ │ ├── Internal/CellValueConverter.cs # 原始值到 CLR 類型的轉(zhuǎn)換 │ │ ├── Internal/StyleCache.cs # 樣式緩存避免超上限 │ │ ├── Reading/ExcelReader.cs # 打開、遍歷、反射賦值 │ │ ├── Writing/ExcelWriter.cs # xls / xlsx 常規(guī)導(dǎo)出 │ │ └── Writing/SxssfExcelWriter.cs # 大數(shù)據(jù)量流式導(dǎo)出 │ └── ExcelKit.Demo/ │ ├── Program.cs │ ├── Models/OrderRow.cs │ └── samples/ # 放測試用的 xls、xlsx文件職責(zé)關(guān)鍵點(diǎn)ExcelOptions.cs表頭行號(hào)、數(shù)據(jù)起始行、空行策略不同來源的表頭位置經(jīng)常不一樣ExcelColumnAttribute.cs列名到屬性的映射表頭改名不影響實(shí)體CellValueConverter.cs日期、數(shù)字、布爾、枚舉的轉(zhuǎn)換所有類型判斷集中在一處ExcelReader.cs讀工作簿并映射成ListT處理空行、空單元格ExcelWriter.cs常規(guī)導(dǎo)出、樣式、合并、下拉樣式必須緩存復(fù)用SxssfExcelWriter.cs十萬行級導(dǎo)出Dispose負(fù)責(zé)清臨時(shí)文件2.3 一個(gè)能跑通的最小閉環(huán)在拆細(xì)節(jié)之前先讓讀寫跑通一次確認(rèn)包引用沒問題。下面這段是示例項(xiàng)目里Program.cs的核心負(fù)責(zé)按擴(kuò)展名創(chuàng)建工作簿、保存、再打開讀回來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}) }; } // 先寫臨時(shí)文件再替換避免目標(biāo)文件被占用時(shí)把原文件寫壞 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); } // 打開時(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的寫法是血淚經(jīng)驗(yàn)?zāi)繕?biāo)文件正被 Excel 打開時(shí)直接FileMode.Create會(huì)拋IOException更糟的是有些情況下文件被截?cái)嗔瞬攀∮脩裟玫揭粋€(gè)打不開的 xlsx。走臨時(shí)文件至少保證原文件完好。WorkbookFactory.Create接受流它自己讀魔數(shù)判斷是 BIFF 還是 ZIP 包所以讀取端完全不用關(guān)心擴(kuò)展名——順帶說一句用戶把.xlsx改成.xls傳上來的情況真有工廠方法能兜住按擴(kuò)展名判斷的寫法就翻車了。提示W(wǎng)orkbookFactory.Create(Stream)之后不要立刻把流 Dispose 掉工作簿內(nèi)部還引用著它后續(xù)操作可能報(bào)“無法訪問已關(guān)閉的流”。3. 讀取鏈路拆解從工作簿到單元格把 Excel 當(dāng)半結(jié)構(gòu)化數(shù)據(jù)源讀取看著簡單實(shí)際是坑最集中的一段。Excel 不是數(shù)據(jù)庫沒有列類型單元格里存的可能是文本、可能是數(shù)字、可能是公式日期還是個(gè)偽裝成數(shù)字的 double。這一章按“定位 Sheet → 取值 → 映射成對象”三步走每一步都給可直接用的代碼。3.1 定位 Sheet 與遍歷有效行第一步是把 Sheet 拿到手。用戶傳上來的文件里常有隱藏 Sheet、說明頁、匯總頁按名字取最穩(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)上界遇到中間夾了空行就少讀一截。正確姿勢是用FirstRowNum到LastRowNum閉區(qū)間遍歷然后對每一行判空var sheet GetSheet(wb, 明細(xì)); if (sheet.PhysicalNumberOfRows 0) return new ListOrderRow(); var first sheet.FirstRowNum; // 通常就是表頭行 var last sheet.LastRowNum; // 注意被格式化過的空行也會(huì)算進(jìn)來 for (var r first 1; r last; r) { var row sheet.GetRow(r); // 越界或沒內(nèi)容的行會(huì)返回 null if (row is null) continue; // ... 逐格取值 }GetRow返回 null 這件事必須處理LastRowNum會(huì)把“只設(shè)過格式?jīng)]填過值”的行也算進(jìn)去表格末尾拖了一片帶邊框的空行是常態(tài)。不加判空線上就會(huì)收到一堆NullReferenceException堆棧還指在業(yè)務(wù)代碼里排查起來像個(gè)黑匣子。3.2 單元格取值類型分支是繞不過去的ICell的CellType決定了你能調(diào)哪個(gè)屬性。對著一個(gè)文本單元格取NumericCellValue拋的是InvalidOperationException消息還只告訴你類型不對。更麻煩的是公式單元格它的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之前做反過來先取值再判斷得到的已經(jīng)是 double 了沒有格式信息可查。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 反射映射成對象讓表頭變化不影響實(shí)體逐格GetValue再手寫賦值字段一多就容易錯(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ù)值得說MissingCellPolicy.CREATE_NULL_AS_BLANK讓不存在的單元格返回一個(gè) Blank 單元格而不是 null省掉一層判空options.HeaderRowIndex和DataStartRowIndex分開配置是因?yàn)橛行┠０宓谝恍惺谴髽?biāo)題、第二行才是表頭。Convert方法里要處理NullableT、枚舉、decimal的InvariantCulture轉(zhuǎn)換。金額字段最容易出事源文件里是1234.56服務(wù)器區(qū)域設(shè)置是德語Convert.ToDecimal會(huì)把點(diǎn)當(dāng)千分位讀出 123456。統(tǒng)一用CultureInfo.InvariantCulture轉(zhuǎn)換能省掉一大半“數(shù)據(jù)對不上”的工單。4. 寫入與導(dǎo)出樣式緩存、合并單元格和十萬行的流式寫法寫比讀更容易埋雷因?yàn)楹芏鄦栴}不會(huì)當(dāng)場報(bào)錯(cuò)而是等用戶用 Excel 打開時(shí)才提示“發(fā)現(xiàn)不可讀取的內(nèi)容”。這一章按常規(guī)導(dǎo)出、表頭樣式與交互元素、大數(shù)據(jù)量三條線拆重點(diǎn)講樣式復(fù)用和 SXSSF 的窗口機(jī)制。4.1 樣式緩存別在循環(huán)里 CreateCellStyleNPOI 的ICellStyle是工作簿級別的對象每個(gè)工作簿能創(chuàng)建的樣式數(shù)量有上限.xls是 4000 左右.xlsx是 64000。你寫row.CreateCell(0).CellStyle wb.CreateCellStyle()放在一萬行的循環(huán)里前幾千行沒問題后面直接拋異常報(bào)錯(cuò)信息還只說“樣式數(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ú)拎出來日期列如果不設(shè)格式寫進(jìn)去的DateTime打開后顯示成一串45123用戶第一反應(yīng)是系統(tǒng)壞了。CreateDataFormat().GetFormat(...)返回的是格式索引同一個(gè)格式字符串重復(fù)調(diào)用會(huì)得到同一個(gè)索引所以緩存不是強(qiáng)制的但樣式對象必須緩存。4.2 合并單元格、凍結(jié)窗格、下拉框與公式報(bào)表類導(dǎo)出的“專業(yè)感”基本靠這幾樣堆出來標(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(取值不合法, 請從下拉列表里選擇狀態(tài)); sheet.AddValidationData(validation); // 合計(jì)行走公式讓 Excel 自己算比在服務(wù)端算好再寫死更靈活 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í)如果只寫了左上角單元格的值其余單元格留空某些版本的 Excel 打開會(huì)警告穩(wěn)妥做法是給合并區(qū)域每個(gè)格子都建出來再設(shè)值。公式單元格寫進(jìn)去之后CachedFormulaResultType在你這邊是空的——NPOI 不做計(jì)算。所以別的系統(tǒng)讀這個(gè)文件時(shí)如果直接取緩存值拿到的是 0 或者空。要么在服務(wù)端算好寫成值要么在文件打開時(shí)讓 Excel 重算一次設(shè)置wb.ForceFormulaRecalculation true就能讓 Excel 打開時(shí)算一遍。注意CreateFreezePane(0, 2)的第一個(gè)參數(shù)是凍結(jié)的列數(shù)傳 0 表示只凍行別把行列順序記反了。4.3 SXSSF 流式導(dǎo)出十萬行不該進(jìn)內(nèi)存XSSFWorkbook是全內(nèi)存模型一行十列十萬行大概要吃掉幾百兆加上 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ù)超過就刷到磁盤臨時(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)勢就不明顯了。我一般按單行寬度估十列左右的表500 到 1000 是比較平衡的值。using那句不能省。SXSSFWorkbook在%TEMP%下建臨時(shí)文件只有Dispose才會(huì)清理。少寫一個(gè)using跑一周之后磁盤告警DBA 找過來你還得先解釋這不是日志文件。另外 SXSSF 只能寫不能讀AutoSizeColumn也只在設(shè)置了TrackAllColumnsForAutoSizing之后才有意義寬表上還特別慢我一般直接按內(nèi)容估算列寬寫死。5. 避坑與排查NPOI 上線后必然撞上的 5 個(gè)問題下面五條都是踩過之后寫進(jìn)回歸用例的遇到報(bào)錯(cuò)別急著搜異常消息先按現(xiàn)象對一遍。5.1 報(bào)“文件正由另一進(jìn)程使用”或讀出來是空表現(xiàn)象導(dǎo)出時(shí)拋IOException: The process cannot access the file或者讀文件時(shí)PhysicalNumberOfRows是 0但用 Excel 打開明明有數(shù)據(jù)。原因?qū)懧窂缴夏繕?biāo)文件正被 Excel 或預(yù)覽服務(wù)打開讀路徑上是File.OpenRead之后又用using提前釋放了流WorkbookFactory.Create內(nèi)部還引用著它讀到一半拿到空數(shù)據(jù)。解決寫走臨時(shí)文件加File.Move(tmp, path, overwrite: true)讀的時(shí)候讓流的生命周期覆蓋工作簿的整個(gè)使用期要么不用using要么改成先把整個(gè)文件讀進(jìn)MemoryStream再創(chuàng)建。上傳接口還有個(gè)常見原因前端傳的是 0 字節(jié)文件Length 0直接攔掉別讓它走到 NPOI 里。5.2 日期讀成 45000 多金額多出幾位小數(shù)現(xiàn)象OrderDate字段全是45123這種數(shù)字金額1234.56讀成123456或者變成1234.5600000000001。原因日期在 xlsx 里本來就是個(gè) double沒走DateUtil.IsCellDateFormatted判斷就當(dāng)成普通數(shù)字返回了金額問題一半來自double的二進(jìn)制精度一半來自區(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í)也一樣寫double進(jìn)去再讀出來對比最后一位對不上就是精度問題。5.3 十萬行導(dǎo)出內(nèi)存飆升進(jìn)程被 OOM 殺掉現(xiàn)象導(dǎo)出任務(wù)跑到一半容器重啟日志里沒有任何異常堆棧只有一條退出碼。原因用了XSSFWorkbook全量加載每行每格都是完整對象十萬行輕松幾百兆疊加并發(fā)導(dǎo)出內(nèi)存直接頂?shù)饺萜魃舷?。解決超過兩萬行走SXSSFWorkbook窗口設(shè) 500 到 1000同時(shí)限制并發(fā)導(dǎo)出數(shù)量用信號(hào)量控制在兩三個(gè)導(dǎo)出任務(wù)改成后臺(tái)隊(duì)列加下載鏈接別讓用戶點(diǎn)一下就在請求線程里同步跑完。另外注意SXSSFWorkbook的臨時(shí)文件目錄容器里/tmp默認(rèn)可能只有幾百兆。5.4 樣式超出上限或者 Excel 打開提示“發(fā)現(xiàn)不可讀取的內(nèi)容”現(xiàn)象小數(shù)據(jù)量導(dǎo)出正常行數(shù)一多就拋樣式超限異常或者文件能生成用 Excel 打開彈修復(fù)提示。原因循環(huán)里CreateCellStyle沒有復(fù)用修復(fù)提示多半是合并區(qū)域和已有數(shù)據(jù)重疊、Sheet 名超過 31 個(gè)字符、或者.xls里用了只有.xlsx支持的寫法。解決樣式統(tǒng)一走緩存類字體也一樣寫之前校驗(yàn) Sheet 名長度和非法字符[]:*?/\.xls導(dǎo)出時(shí)把行數(shù)控制在 65536 以內(nèi)超了直接給用戶提示換 xlsx別等HSSFWorkbook寫到一半拋異常。5.5 容器里 AutoSizeColumn 拋異常或整列寬度變成 0現(xiàn)象本地 Windows 跑得好好的部署到 Linux 容器后AutoSizeColumn拋異?；蛘吡袑捜兂赡J(rèn)值。原因自動(dòng)列寬需要測量文字渲染寬度較新的 NPOI 用純托管的字體庫容器鏡像里沒裝對應(yīng)字體就測不出來用老版本的話還會(huì)依賴系統(tǒng)圖形庫Linux 上直接報(bào)libgdiplus找不到。解決鏡像里裝一套基礎(chǔ)字體比如開源的中文字體包或者干脆放棄自動(dòng)寬度按列的字符數(shù)手動(dòng)SetColumnWidth(c, Math.Min(255, maxLen * 256))穩(wěn)定又不受環(huán)境影響。6. 二次開發(fā)把散落各處的 NPOI 調(diào)用收成一個(gè)導(dǎo)出服務(wù)接手過的幾個(gè)項(xiàng)目里NPOI 的調(diào)用最后都會(huì)散成一地A 類里一個(gè)new XSSFWorkbook()B 服務(wù)里又一份樣式代碼C 接口為了加一列改了三處。改造方向很明確——只暴露一個(gè)IExcelService入?yún)⑹菙?shù)據(jù)集合和一個(gè)配置對象出參是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)里把前面幾章的東西拼起來ExcelExportOptions帶上格式xls / xlsx、Sheet 名、是否凍結(jié)表頭、列寬策略導(dǎo)出時(shí)按數(shù)據(jù)量自動(dòng)切XSSFWorkbook和SXSSFWorkbook列定義全部來自ExcelColumnAttribute加字段不用改導(dǎo)出代碼。改造前后差別很明顯改造前改造后每個(gè)接口各寫一份樣式樣式只在StyleCache里定義一次加一列改三處代碼實(shí)體加個(gè)特性即可數(shù)據(jù)量一大就 OOM按行數(shù)自動(dòng)走 SXSSF表頭改名導(dǎo)致導(dǎo)入失敗按列名匹配找不到列直接報(bào)錯(cuò)并指出列名驗(yàn)證方法我一般用金標(biāo)準(zhǔn)對比準(zhǔn)備一份人工核對過的樣本表跑導(dǎo)入后序列化成 JSON 存進(jìn)倉庫作為回歸基線導(dǎo)出則把生成的文件再讀回來逐格對比關(guān)鍵字段。這樣做的好處是日期格式、空行、合并單元格這些玄學(xué)問題都能被自動(dòng)兜住而不是等運(yùn)營反饋。改的時(shí)候有個(gè)技巧先別動(dòng)業(yè)務(wù)代碼在原來的調(diào)用點(diǎn)上加一層IExcelService適配用舊邏輯實(shí)現(xiàn)接口跑通之后再換內(nèi)部實(shí)現(xiàn)。這樣出問題時(shí)能立刻切回去不用回滾整個(gè)分支。從那以后我每次接報(bào)表需求都先把表頭、空行、日期格式這三件事寫成回歸用例再動(dòng)手比事后加班查數(shù)據(jù)對不上劃算多了。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取