出與避坑)
簡(jiǎn)介面向正在用 C# 處理 Excel 的 .NET 開發(fā)者這份資料圍繞 NPOI 庫給出可直接參考的讀寫示例覆蓋舊版 .xls 與新版 .xlsx 兩種格式既適合剛接觸 NPOI 的新手入門也適合需要封裝通用工具類的中級(jí)開發(fā)者對(duì)照借鑒。壓縮包共 15 個(gè)文件以 12 個(gè) dll 依賴庫為主另有 2 個(gè) cs 源碼與 1 個(gè) xml 配置整體約 2.19MBdll 提供 NPOI 各模塊及 JSON、壓縮等支撐能力cs 文件則呈現(xiàn)工具類的組織方式。內(nèi)容涉及工作簿與工作表創(chuàng)建、單元格寫入與遍歷讀取、字體邊框?qū)R等樣式設(shè)置、文件保存和異常處理并按 2012Version 與 201607Version 分版本實(shí)現(xiàn)便于比較不同 NPOI 版本下的 API 差異及 HSSF、XSSF 兩套模型。已有 6358 人學(xué)習(xí)可為項(xiàng)目中的 Excel 導(dǎo)入導(dǎo)出、報(bào)表生成與工具類封裝提供參考。1. 別急著裝 Office先看清 C# NPOI 操作Excel 到底解決什么問題后臺(tái)要導(dǎo)一份對(duì)賬單服務(wù)器上沒裝 OfficeMicrosoft.Office.Interop.Excel一跑就拋 0x800A03EC這個(gè)場(chǎng)景我見過不止一次。換個(gè)角度看C# NPOI 操作Excel 最省心的地方恰恰是它根本不碰 Office——純托管庫在進(jìn)程里直接拼 xls/xlsx 的二進(jìn)制結(jié)構(gòu)服務(wù)器裝不裝 Office 都能跑。它一套 API 覆蓋兩種格式老的.xls走 HSSF新的.xlsx走 XSSF數(shù)據(jù)量大再換 SXSSF 流式寫十萬行也不至于把內(nèi)存吃穿。適合做報(bào)表導(dǎo)出、批量數(shù)據(jù)導(dǎo)入、模板填充的后臺(tái)服務(wù)、桌面工具和接口項(xiàng)目如果你只是偶爾手動(dòng)改個(gè)表那確實(shí)沒必要上它。2. 技術(shù)選型與工程結(jié)構(gòu)HSSF、XSSF、SXSSF 三套模型怎么分工打開 NPOI 的命名空間會(huì)看到一堆HSSF開頭的類第一反應(yīng)通常是“這不是 Java 那套的翻版嗎”。確實(shí)接口模型沿用了IWorkbook/ISheet/IRow/ICell這層抽象好處是同一份業(yè)務(wù)代碼換個(gè)實(shí)現(xiàn)類就能讀寫不同格式壞處是新手很容易在new的那一行就把類型寫死后面想兼容.xls就得大改。選型這一步基本決定了后面會(huì)不會(huì)返工所以拆代碼之前先把模型說清楚。2.1 三種工作簿模型的邊界模型對(duì)應(yīng)格式內(nèi)存形態(tài)適用量級(jí)主要限制HSSFWorkbook.xls全量駐留內(nèi)存幾萬行以內(nèi)單表 65536 行、256 列XSSFWorkbook.xlsxDOM 全量駐留十萬行內(nèi)看堆大小行數(shù)越多內(nèi)存線性上漲SXSSFWorkbook.xlsx滑動(dòng)窗口 磁盤臨時(shí)文件百萬行級(jí)已刷出的行不能再改、不能刪行我的默認(rèn)規(guī)則很粗暴對(duì)方?jīng)]明確要求.xls一律XSSFWorkbook導(dǎo)出預(yù)估超過五萬行直接上SXSSFWorkbook只有對(duì)接老系統(tǒng)、對(duì)方還在用舊版表格軟件時(shí)才回頭用HSSF。這條規(guī)則能省掉九成的兼容性扯皮。SXSSF 的代價(jià)必須提前說清楚。它把已經(jīng)寫出去的行刷到磁盤臨時(shí)文件內(nèi)存里只留窗口內(nèi)的那幾百行所以你別想回頭sheet.GetRow(0)去改第一行——那時(shí)候它已經(jīng)在臨時(shí)文件里了GetRow直接返回null。需要回頭改的東西合計(jì)行、頁腳匯總要么放最后寫要么在窗口還沒刷出去之前處理掉。這個(gè)限制踩過一次就記住了。還有一個(gè)反直覺的點(diǎn)讀文件時(shí)判斷格式不要靠文件后綴用WorkbookFactory.Create(stream)讓它自己嗅探。業(yè)務(wù)方發(fā)過來的“對(duì)賬單.xls”里裝著的其實(shí)是 HTML 表格這種事我一年能遇到兩回。2.2 示例工程的分層與目錄結(jié)構(gòu)示例工程我按“核心邏輯不依賴 UI、不依賴文件系統(tǒng)”來切目錄長(zhǎng)這樣NpoiExcelDemo/ ├── NpoiExcelDemo.sln ├── src/ │ ├── NpoiExcelDemo.Core/ # 只做 Excel 讀寫不放業(yè)務(wù) │ │ ├── ExcelReader.cs │ │ ├── ExcelWriter.cs │ │ ├── ExcelStyleFactory.cs │ │ ├── ExcelColumnAttribute.cs │ │ └── Models/OrderRow.cs │ ├── NpoiExcelDemo.Console/ # 命令行入口跑兩個(gè)示例 │ │ └── Program.cs │ └── NpoiExcelDemo.Tests/ # xUnit用內(nèi)存流做往返測(cè)試 │ └── RoundTripTests.cs ├── samples/ │ ├── legacy.xls # 老格式樣本 │ └── modern.xlsx # 新格式樣本 └── templates/ └── 對(duì)賬單模板.xlsxCore里我堅(jiān)持不讓IWorkbook泄漏出去。對(duì)外方法簽名一律是Stream進(jìn)、Stream或ListT出業(yè)務(wù)層根本不需要using NPOI.SS.UserModel;。這么做有兩個(gè)直接好處單測(cè)里傳一個(gè)MemoryStream就能跑完整鏈路不落盤Web 上傳場(chǎng)景拿到IFormFile.OpenReadStream()可以直接喂進(jìn)去不用先存臨時(shí)文件再刪。samples目錄的作用容易被低估。.xls和.xlsx在單元格類型、日期序列號(hào)、公式緩存上的行為并不完全一致光靠猜沒用必須有一份真實(shí)的舊格式文件反復(fù)驗(yàn)證。templates目錄則是給“模板填充”這種需求準(zhǔn)備的——表頭、樣式、合并單元格都在模板里做好代碼只負(fù)責(zé)往里塞數(shù)據(jù)行改樣式的時(shí)候不用改代碼。3. 從零跑通裝包、寫第一個(gè) xlsx、再讀回 xls這一章的操作照著敲就能跑起來目標(biāo)是把“寫出去”和“讀進(jìn)來”這兩條鏈路都走通一遍中間不留黑匣子。3.1 建工程與引包# 建解決方案和兩個(gè)項(xiàng)目 dotnet new sln -n NpoiExcelDemo dotnet new classlib -n NpoiExcelDemo.Core -o src/NpoiExcelDemo.Core dotnet new console -n NpoiExcelDemo.Console -o src/NpoiExcelDemo.Console # 掛到解決方案下 dotnet sln add src/NpoiExcelDemo.Core src/NpoiExcelDemo.Console # NPOI 只需要裝在 Core 里Console 通過項(xiàng)目引用拿到 dotnet add src/NpoiExcelDemo.Core package NPOI dotnet add src/NpoiExcelDemo.Console reference src/NpoiExcelDemo.Core這里面幾個(gè)參數(shù)值得說明。-o是指定輸出目錄把項(xiàng)目塞進(jìn)src/是習(xí)慣不塞也能跑。dotnet add package NPOI不寫版本號(hào)默認(rèn)拉最新穩(wěn)定版如果目標(biāo)框架是netstandard2.0要給老項(xiàng)目引用加-f netstandard2.0或者直接改 csproj 里的TargetFramework。Framework 4.x 的老項(xiàng)目不走 CLI在包管理器里裝完記得看一眼依賴項(xiàng)——NPOI 會(huì)順帶拉一個(gè)壓縮庫發(fā)布的時(shí)候別只拷了NPOI.dll就以為完事了缺依賴的報(bào)錯(cuò)信息通常很含糊只說“未能加載文件或程序集”排查起來全靠猜。提示目標(biāo)框架選net8.0還是netstandard2.0取決于調(diào)用方。庫給多個(gè)項(xiàng)目共用就選netstandard2.0純新項(xiàng)目選net8.0能用上Span之類的新 API。3.2 寫出第一個(gè) .xlsxNPOI 的層級(jí)就四層工作簿 → 工作表 → 行 → 單元格。下面這段是最小閉環(huán)using NPOI.SS.UserModel; using NPOI.XSSF.UserModel; public static void WriteSimple(string path) { // 1. 工作簿XSSF 對(duì)應(yīng) .xlsx IWorkbook workbook new XSSFWorkbook(); ISheet sheet workbook.CreateSheet(對(duì)賬單); // 2. 表頭行 IRow header sheet.CreateRow(0); string[] titles { 訂單號(hào), 客戶, 金額, 下單時(shí)間 }; for (int i 0; i titles.Length; i) { header.CreateCell(i).SetCellValue(titles[i]); } // 3. 數(shù)據(jù)行 IRow row sheet.CreateRow(1); row.CreateCell(0).SetCellValue(SO-2024001); row.CreateCell(1).SetCellValue(某客戶); row.CreateCell(2).SetCellValue(1280.50); // 數(shù)值走 double 重載 row.CreateCell(3).SetCellValue(DateTime.Now); // 日期直接給 DateTime // 4. 列寬單位是 1/256 個(gè)字符寬度20 * 256 20 字符 sheet.SetColumnWidth(0, 20 * 256); using var fs new FileStream(path, FileMode.Create, FileAccess.Write); workbook.Write(fs); }逐段說一下。CreateSheet傳的名字就是 Excel 底部的標(biāo)簽名超過 31 個(gè)字符或含[]:*?/\會(huì)直接拋異常。CreateCell(i)的索引從 0 開始跳著創(chuàng)建也允許比如只創(chuàng)建第 0 和第 5 個(gè)中間的空單元格讀回來是CellType.Blank。金額這一行是關(guān)鍵SetCellValue(1280.50)存的是數(shù)值Excel 里能參與求和如果圖省事寫成SetCellValue(1280.50)存的是文本Excel 會(huì)在左上角給你標(biāo)個(gè)綠色小三角用戶一點(diǎn)“轉(zhuǎn)換為數(shù)字”全部格式又亂掉血淚經(jīng)驗(yàn)。日期同理SetCellValue(DateTime)會(huì)把它轉(zhuǎn)成序列號(hào)存儲(chǔ)顯示格式由單元格樣式的DataFormat決定不設(shè)樣式就是默認(rèn)的日期顯示。最后workbook.Write(fs)這個(gè)重載在不同版本上行為有差異有的會(huì)把流關(guān)掉有的不會(huì)。不確定的話就在Write之后立刻fs.Flush()并且不要指望后面還能繼續(xù)往這個(gè)流里寫東西。3.3 用 WorkbookFactory 統(tǒng)一讀 .xls 和 .xlsx讀這邊最容易犯的錯(cuò)是寫死new XSSFWorkbook(fs)遇到.xls就拋Invalid header signature。正確姿勢(shì)是工廠加接口using NPOI.SS.UserModel; public static void ReadAny(string path) { using var fs new FileStream(path, FileMode.Open, FileAccess.Read); // 關(guān)鍵工廠根據(jù)文件頭自動(dòng)選 HSSF 還是 XSSF IWorkbook workbook WorkbookFactory.Create(fs); for (int s 0; s workbook.NumberOfSheets; s) { ISheet sheet workbook.GetSheetAt(s); // LastRowNum 是最后一行索引空表返回 -1不能直接當(dāng)行數(shù) for (int r sheet.FirstRowNum; r sheet.LastRowNum; r) { IRow row sheet.GetRow(r); if (row null) continue; // 整行被刪過就是 null不判會(huì) NRE for (int c 0; c row.LastCellNum; c) { ICell cell row.GetCell(c); Console.Write(ExcelReader.GetCellText(cell) \t); } Console.WriteLine(); } } }WorkbookFactory.Create支持傳Stream或FileInfo內(nèi)部會(huì)讀文件頭判斷格式比看后綴靠譜得多。FirstRowNum和LastRowNum都返回索引空表或者全空行的情況下LastRowNum可能是-1、0或者你以為的行數(shù)寫for循環(huán)時(shí)用并且判row null這兩道保險(xiǎn)缺一不可。GetSheetAt是按順序取GetSheet(名字)是按名取。名字取不到會(huì)返回null而不是拋異常后面直接.GetRow()就炸了所以按名取的時(shí)候記得判空。3.4 跑起來看一眼dotnet run --project src/NpoiExcelDemo.Console -- ./out/demo.xlsx ./samples/legacy.xls參數(shù)依次是輸出路徑和要讀的舊格式樣本。跑完先確認(rèn)三件事out/demo.xlsx能被正常打開、金額那一列右對(duì)齊且能求和、legacy.xls的中文沒有亂碼。這三條過了說明環(huán)境、依賴、編碼都沒問題后面再改代碼就是純業(yè)務(wù)活了。4. 核心模塊拆解取值、樣式、大文件、格式差異這一段是真正要反復(fù)用的東西。示例里那幾個(gè)方法寫短是因?yàn)榘阉锌佣际者M(jìn)了這幾個(gè)方法里。4.1 單元格取值CellType 分支一個(gè)都不能漏讀 Excel 最典型的故障是“日期變成 45000 這種數(shù)字”根子在CellType.Numeric—— 日期在底層就是數(shù)字靠樣式區(qū)分。所以取值方法必須寫成這樣public static string GetCellText(ICell cell) { if (cell null) return string.Empty; switch (cell.CellType) { case CellType.String: return cell.StringCellValue; case CellType.Numeric: // 日期底層是序列號(hào)必須靠單元格樣式判斷直接 ToString 會(huì)得到 45000 if (DateUtil.IsCellDateFormatted(cell)) return cell.DateCellValue?.ToString(yyyy-MM-dd HH:mm:ss) ?? ; return cell.NumericCellValue.ToString(); case CellType.Boolean: return cell.BooleanCellValue ? TRUE : FALSE; case CellType.Formula: // 公式要按緩存結(jié)果類型再分一次支不能直接取 StringCellValue switch (cell.CachedFormulaResultType) { case CellType.Numeric: return DateUtil.IsCellDateFormatted(cell) ? cell.DateCellValue?.ToString(yyyy-MM-dd) ?? : cell.NumericCellValue.ToString(); case CellType.String: return cell.StringCellValue; default: return cell.ToString() ?? ; } case CellType.Blank: return string.Empty; case CellType.Error: // 把 #DIV/0! 這類錯(cuò)誤碼還原成可讀文本 return FormulaError.ForInt(cell.ErrorCellValue).String; default: return cell.ToString() ?? string.Empty; } }三個(gè)地方值得單獨(dú)講。DateUtil.IsCellDateFormatted(cell)是個(gè)靜態(tài)工具方法內(nèi)部讀的是單元格樣式的DataFormat字符串判斷是不是日期/時(shí)間格式比自己寫正則靠譜。CellType.Formula分支里必須先看CachedFormulaResultType—— 公式單元格的StringCellValue只有在緩存結(jié)果是字符串時(shí)才有效緩存是數(shù)字你卻去取字符串拿到的是空串或者直接拋異常這種問題在日志里只表現(xiàn)為“某幾列讀出來是空的”非常難定位。FormulaError.ForInt把0x07這種錯(cuò)誤碼轉(zhuǎn)成#DIV/0!報(bào)表里帶著錯(cuò)誤碼有時(shí)候反而是有用的信息別急著當(dāng)成異常吞掉。注意DateCellValue在較新版本里是DateTime?老版本可能是DateTime。如果編譯報(bào)“無法將 DateTime 轉(zhuǎn)換為 DateTime?”說明你手上的版本比較舊去掉?.就行。4.2 樣式復(fù)用ICellStyle 是共享池不是隨手 new 的樣式是 NPOI 里最容易被寫成性能問題的模塊。工作簿內(nèi)部維護(hù)一個(gè)樣式池你每CreateCellStyle()一次就多占一個(gè)槽位.xls上限大約 4000 個(gè).xlsx大約 64000 個(gè)超了直接拋異常而且文件體積會(huì)以肉眼可見的速度膨脹——見過一個(gè)導(dǎo)出的表 800KB 數(shù)據(jù)配 60MB 樣式就是這么來的。正確做法是做個(gè)樣式工廠按 key 緩存public sealed class ExcelStyleFactory { private readonly IWorkbook _wb; private readonly Dictionarystring, ICellStyle _cache new(); public ExcelStyleFactory(IWorkbook wb) _wb wb; public ICellStyle Money(string format #,##0.00) { if (_cache.TryGetValue(format, out var cached)) return cached; var style _wb.CreateCellStyle(); // 每調(diào)一次就占一個(gè)樣式槽 style.DataFormat _wb.CreateDataFormat().GetFormat(format); style.Alignment HorizontalAlignment.Right; style.BorderBottom BorderStyle.Thin; style.VerticalAlignment VerticalAlignment.Center; _cache[format] style; return style; } }CreateDataFormat().GetFormat(#,##0.00)里的格式串跟 Excel 自定義格式語法一致0.00%、yyyy/m/d、#,##0;(#,##0)這些都能直接用格式串本身也是被緩存的同一個(gè)串多次調(diào)用返回同一個(gè)對(duì)象。Money方法用格式串當(dāng)緩存 key是因?yàn)橥粋€(gè)工作簿里不同列可能需要不同小數(shù)位用字符串做 key 天然支持多套格式共存。用法上先取一次樣式循環(huán)里反復(fù)賦給不同單元格var styles new ExcelStyleFactory(workbook); var moneyStyle styles.Money(); foreach (var item in rows) { var cell row.CreateCell(2); cell.SetCellValue(item.Amount); cell.CellStyle moneyStyle; // 賦值不是 new }4.3 SXSSF 流式導(dǎo)出十萬行不能再用 XSSF數(shù)據(jù)量上去以后XSSFWorkbook把所有行都留在內(nèi)存里十萬行乘以十幾列堆基本就撐不住了。換成 SXSSFpublic static void WriteLarge(string path, IEnumerableOrderRow rows, int windowSize 500) { // windowSize內(nèi)存里保留的行數(shù)超出的會(huì)被刷到磁盤臨時(shí)文件 var workbook new SXSSFWorkbook(windowSize); try { var sheet workbook.CreateSheet(明細(xì)); int r 0; foreach (var item in rows) { var row sheet.CreateRow(r); row.CreateCell(0).SetCellValue(item.OrderNo); row.CreateCell(1).SetCellValue(item.CustomerName); row.CreateCell(2).SetCellValue(item.Amount); // 注意這一行一旦被刷出去后面 GetRow(r) 就取不到了 } using var fs new FileStream(path, FileMode.Create, FileAccess.Write); workbook.Write(fs); fs.Flush(); } finally { workbook.Close(); workbook.Dispose(); // 必須顯式調(diào)用否則臨時(shí)文件會(huì)留在系統(tǒng)臨時(shí)目錄 } }windowSize這個(gè)參數(shù)是內(nèi)存和磁盤 IO 的平衡點(diǎn)。設(shè)太小比如 100刷盤頻繁寫十萬行能明顯感覺到慢設(shè)太大比如 5000內(nèi)存優(yōu)勢(shì)就沒那么明顯了。我一般按 500 起步實(shí)測(cè)導(dǎo)出耗時(shí)偏高再往上調(diào)。Dispose()這一步不能省。SXSSF 在系統(tǒng)臨時(shí)目錄里建的文件只有Dispose才會(huì)清理進(jìn)程長(zhǎng)時(shí)間跑批又不釋放臨時(shí)目錄遲早被塞滿然后你會(huì)收獲一堆“磁盤空間不足”的告警排查半天發(fā)現(xiàn)是自己導(dǎo)出的表。4.4 兩種格式的行為差異能力.xlsHSSF.xlsxXSSF / SXSSF單表最大行655361048576單表最大列25616384單元格樣式上限約 4000約 64000文件本質(zhì)二進(jìn)制復(fù)合文檔zip 包 若干 xml新函數(shù)支持只有老函數(shù)集基本都能用讀入內(nèi)存占用相對(duì)低相對(duì)高這張表最有用的兩行是行數(shù)上限和樣式上限。行數(shù)超了不會(huì)報(bào)錯(cuò)會(huì)直接截?cái)嘁话偃f條數(shù)據(jù)導(dǎo)出成.xls最后只剩六萬五而且沒有任何提示——這種 bug 上線之后才被發(fā)現(xiàn)返工成本極高。樣式上限則是另一個(gè)方向.xls到 4000 就拋InvalidOperationException堆棧里看不到你的業(yè)務(wù)代碼只看到 NPOI 內(nèi)部的Workbook.CreateCellStyle。5. 避坑與排查五個(gè)真踩過的問題5.1 日期讀出來是 45000 這樣的整數(shù)現(xiàn)象導(dǎo)入的對(duì)賬單里時(shí)間列全是五位數(shù)用戶以為數(shù)據(jù)錯(cuò)了。 原因CellType.Numeric分支直接NumericCellValue.ToString()沒判斷日期格式。日期在 Excel 里本質(zhì)是從 1900-01-01 起算的天數(shù)45000就是某個(gè)真實(shí)日期。 解決取值統(tǒng)一走 4.1 那個(gè)GetCellTextNumeric分支先DateUtil.IsCellDateFormatted(cell)再?zèng)Q定是格式化日期還是原樣輸出數(shù)字。5.2 導(dǎo)出的文件打不開提示“發(fā)現(xiàn)不可讀取的內(nèi)容”現(xiàn)象瀏覽器下載下來的 xlsxExcel 打開報(bào)修復(fù)提示點(diǎn)“是”之后內(nèi)容可能還在也可能丟了。 原因九成是流被提前關(guān)掉或者Position沒歸零。workbook.Write(stream)在某些版本會(huì)關(guān)閉傳入的流之后Response.Body再寫就寫不進(jìn)去了另一種是同一個(gè)MemoryStream寫完沒Position 0就直接當(dāng)讀的源用。 解決寫文件的流自己using管好生命周期別依賴庫來關(guān)Web 場(chǎng)景用MemoryStream寫完先ToArray()再輸出讀之前一律stream.Position 0。5.3 大批量導(dǎo)出時(shí)內(nèi)存飆升甚至 OOM現(xiàn)象導(dǎo)五萬行的時(shí)候進(jìn)程內(nèi)存漲到 2G 以上容器直接被 kill。 原因用了XSSFWorkbook所有行和單元格對(duì)象都駐留在堆里一個(gè)單元格對(duì)象幾十字節(jié)五萬行乘二十列就是一千萬個(gè)對(duì)象。 解決換成SXSSFWorkbook窗口設(shè) 500 左右順手檢查一下是不是在循環(huán)里CreateCellStyle那個(gè)也是內(nèi)存大戶。5.4 讀 .xls 報(bào) Invalid header signature現(xiàn)象文件后綴明明是.xlsnew XSSFWorkbook(fs)直接拋異常。 原因一種是用錯(cuò)了實(shí)現(xiàn)類.xls得用 HSSF另一種更陰——某些系統(tǒng)導(dǎo)出的“xls”其實(shí)是 HTML 表格或者 CSV 改了后綴二進(jìn)制頭根本不是 OLE 復(fù)合文檔。 解決讀入口統(tǒng)一用WorkbookFactory.Create(fs)讓庫自己判斷如果工廠也認(rèn)不出來用十六進(jìn)制工具看一眼文件頭D0 CF 11 E0是真的 xlsPK是 xlsxhtml或者table就是偽裝的得先當(dāng)文本解析再轉(zhuǎn)。5.5 單元格樣式莫名不生效現(xiàn)象設(shè)置了邊框和背景色打開文件發(fā)現(xiàn)只有第一行有后面全是白板。 原因ICellStyle是工作簿級(jí)別的共享對(duì)象但很多人習(xí)慣在循環(huán)里CreateCellStyle()之后只對(duì)當(dāng)前單元格賦值同時(shí)又在別處CloneStyleFrom覆蓋了屬性結(jié)果樣式對(duì)象被復(fù)用后互相污染。 解決樣式只在工廠里創(chuàng)建一次循環(huán)里只做cell.CellStyle cachedStyle賦值確實(shí)需要“繼承再加一點(diǎn)差異”的用CloneStyleFrom克隆出一個(gè)新對(duì)象并單獨(dú)緩存別在原對(duì)象上改。6. 二次開發(fā)把示例收成一層能復(fù)用的導(dǎo)入導(dǎo)出示例代碼寫到后面你會(huì)發(fā)現(xiàn)每個(gè)業(yè)務(wù)實(shí)體都在重復(fù)“讀表頭 → 找列 → 轉(zhuǎn)類型”這套動(dòng)作。我一般會(huì)加一個(gè)特性加反射的映射層讓業(yè)務(wù)代碼只寫實(shí)體。[AttributeUsage(AttributeTargets.Property)] public sealed class ExcelColumnAttribute : Attribute { public ExcelColumnAttribute(string title) Title title; public string Title { get; } } public sealed class OrderRow { [ExcelColumn(訂單號(hào))] public string OrderNo { get; set; } ; [ExcelColumn(金額)] public decimal Amount { get; set; } [ExcelColumn(下單時(shí)間)] public DateTime CreatedAt { get; set; } }讀取端靠表頭文本反查屬性允許列順序和實(shí)體屬性順序不一致public static ListT ReadT(Stream stream) where T : new() { var map typeof(T).GetProperties() .Select(p (Prop: p, Attr: p.GetCustomAttributeExcelColumnAttribute())) .Where(x x.Attr ! null) .ToDictionary(x x.Attr!.Title, x x.Prop); IWorkbook wb WorkbookFactory.Create(stream); ISheet sheet wb.GetSheetAt(0); IRow header sheet.GetRow(sheet.FirstRowNum); // 表頭文本 - 列索引 var index new Dictionarystring, int(); for (int c 0; c header.LastCellNum; c) { var title ExcelReader.GetCellText(header.GetCell(c)).Trim(); if (!string.IsNullOrEmpty(title) map.ContainsKey(title)) index[title] c; } var list new ListT(); for (int r sheet.FirstRowNum 1; r sheet.LastRowNum; r) { var row sheet.GetRow(r); if (row null) continue; var entity new T(); foreach (var (title, prop) in map) { if (!index.TryGetValue(title, out var c)) continue; var text ExcelReader.GetCellText(row.GetCell(c)); if (string.IsNullOrWhiteSpace(text)) continue; // 可空類型要?jiǎng)円粚覥onvert.ChangeType 不認(rèn) NullableT var target Nullable.GetUnderlyingType(prop.PropertyType) ?? prop.PropertyType; prop.SetValue(entity, Convert.ChangeType(text, target)); } list.Add(entity); } return list; }改完之后業(yè)務(wù)側(cè)就一行var rows ExcelImporter.ReadOrderRow(stream);字段增減只改實(shí)體上的特性不用碰解析代碼。驗(yàn)證方式我用往返測(cè)試不落盤、跑得快[Fact] public void Xlsx_RoundTrip_ShouldKeepAmount() { var ms new MemoryStream(); using (var wb new XSSFWorkbook()) { var sheet wb.CreateSheet(t); var head sheet.CreateRow(0); head.CreateCell(0).SetCellValue(訂單號(hào)); head.CreateCell(1).SetCellValue(金額); var data sheet.CreateRow(1); data.CreateCell(0).SetCellValue(SO-1); data.CreateCell(1).SetCellValue(99.5); wb.Write(ms); } ms.Position 0; // 不歸零讀出來就是空的 var rows ExcelImporter.ReadOrderRow(ms); Assert.Single(rows); Assert.Equal(99.5m, rows[0].Amount); }這個(gè)測(cè)試我建議再補(bǔ)三個(gè)邊界樣本一個(gè)帶合并單元格的表頭、一個(gè)日期列為空的行、一個(gè)金額列是公式的表。前兩個(gè)驗(yàn)證判空邏輯第三個(gè)驗(yàn)證CachedFormulaResultType分支。這三個(gè)樣本跑通線上八成的導(dǎo)入投訴基本能提前擋掉。從那以后我每次接 Excel 相關(guān)的需求都會(huì)先問清三句話讀進(jìn)來的是什么格式、寫出去給誰用、最大多少行然后才動(dòng)手寫第一行代碼。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取 C# NPOI 操作 Excel：選型、流式導(dǎo)出與避坑
簡(jiǎn)介面向正在用 C# 處理 Excel 的 .NET 開發(fā)者這份資料圍繞 NPOI 庫給出可直接參考的讀寫示例覆蓋舊版 .xls 與新版 .xlsx 兩種格式既適合剛接觸 NPOI 的新手入門也適合需要封裝通用工具類的中級(jí)開發(fā)者對(duì)照借鑒。壓縮包共 15 個(gè)文件以 12 個(gè) dll 依賴庫為主另有 2 個(gè) cs 源碼與 1 個(gè) xml 配置整體約 2.19MBdll 提供 NPOI 各模塊及 JSON、壓縮等支撐能力cs 文件則呈現(xiàn)工具類的組織方式。內(nèi)容涉及工作簿與工作表創(chuàng)建、單元格寫入與遍歷讀取、字體邊框?qū)R等樣式設(shè)置、文件保存和異常處理并按 2012Version 與 201607Version 分版本實(shí)現(xiàn)便于比較不同 NPOI 版本下的 API 差異及 HSSF、XSSF 兩套模型。已有 6358 人學(xué)習(xí)可為項(xiàng)目中的 Excel 導(dǎo)入導(dǎo)出、報(bào)表生成與工具類封裝提供參考。1. 別急著裝 Office先看清 C# NPOI 操作Excel 到底解決什么問題后臺(tái)要導(dǎo)一份對(duì)賬單服務(wù)器上沒裝 OfficeMicrosoft.Office.Interop.Excel一跑就拋 0x800A03EC這個(gè)場(chǎng)景我見過不止一次。換個(gè)角度看C# NPOI 操作Excel 最省心的地方恰恰是它根本不碰 Office——純托管庫在進(jìn)程里直接拼 xls/xlsx 的二進(jìn)制結(jié)構(gòu)服務(wù)器裝不裝 Office 都能跑。它一套 API 覆蓋兩種格式老的.xls走 HSSF新的.xlsx走 XSSF數(shù)據(jù)量大再換 SXSSF 流式寫十萬行也不至于把內(nèi)存吃穿。適合做報(bào)表導(dǎo)出、批量數(shù)據(jù)導(dǎo)入、模板填充的后臺(tái)服務(wù)、桌面工具和接口項(xiàng)目如果你只是偶爾手動(dòng)改個(gè)表那確實(shí)沒必要上它。2. 技術(shù)選型與工程結(jié)構(gòu)HSSF、XSSF、SXSSF 三套模型怎么分工打開 NPOI 的命名空間會(huì)看到一堆HSSF開頭的類第一反應(yīng)通常是“這不是 Java 那套的翻版嗎”。確實(shí)接口模型沿用了IWorkbook/ISheet/IRow/ICell這層抽象好處是同一份業(yè)務(wù)代碼換個(gè)實(shí)現(xiàn)類就能讀寫不同格式壞處是新手很容易在new的那一行就把類型寫死后面想兼容.xls就得大改。選型這一步基本決定了后面會(huì)不會(huì)返工所以拆代碼之前先把模型說清楚。2.1 三種工作簿模型的邊界模型對(duì)應(yīng)格式內(nèi)存形態(tài)適用量級(jí)主要限制HSSFWorkbook.xls全量駐留內(nèi)存幾萬行以內(nèi)單表 65536 行、256 列XSSFWorkbook.xlsxDOM 全量駐留十萬行內(nèi)看堆大小行數(shù)越多內(nèi)存線性上漲SXSSFWorkbook.xlsx滑動(dòng)窗口 磁盤臨時(shí)文件百萬行級(jí)已刷出的行不能再改、不能刪行我的默認(rèn)規(guī)則很粗暴對(duì)方?jīng)]明確要求.xls一律XSSFWorkbook導(dǎo)出預(yù)估超過五萬行直接上SXSSFWorkbook只有對(duì)接老系統(tǒng)、對(duì)方還在用舊版表格軟件時(shí)才回頭用HSSF。這條規(guī)則能省掉九成的兼容性扯皮。SXSSF 的代價(jià)必須提前說清楚。它把已經(jīng)寫出去的行刷到磁盤臨時(shí)文件內(nèi)存里只留窗口內(nèi)的那幾百行所以你別想回頭sheet.GetRow(0)去改第一行——那時(shí)候它已經(jīng)在臨時(shí)文件里了GetRow直接返回null。需要回頭改的東西合計(jì)行、頁腳匯總要么放最后寫要么在窗口還沒刷出去之前處理掉。這個(gè)限制踩過一次就記住了。還有一個(gè)反直覺的點(diǎn)讀文件時(shí)判斷格式不要靠文件后綴用WorkbookFactory.Create(stream)讓它自己嗅探。業(yè)務(wù)方發(fā)過來的“對(duì)賬單.xls”里裝著的其實(shí)是 HTML 表格這種事我一年能遇到兩回。2.2 示例工程的分層與目錄結(jié)構(gòu)示例工程我按“核心邏輯不依賴 UI、不依賴文件系統(tǒng)”來切目錄長(zhǎng)這樣NpoiExcelDemo/ ├── NpoiExcelDemo.sln ├── src/ │ ├── NpoiExcelDemo.Core/ # 只做 Excel 讀寫不放業(yè)務(wù) │ │ ├── ExcelReader.cs │ │ ├── ExcelWriter.cs │ │ ├── ExcelStyleFactory.cs │ │ ├── ExcelColumnAttribute.cs │ │ └── Models/OrderRow.cs │ ├── NpoiExcelDemo.Console/ # 命令行入口跑兩個(gè)示例 │ │ └── Program.cs │ └── NpoiExcelDemo.Tests/ # xUnit用內(nèi)存流做往返測(cè)試 │ └── RoundTripTests.cs ├── samples/ │ ├── legacy.xls # 老格式樣本 │ └── modern.xlsx # 新格式樣本 └── templates/ └── 對(duì)賬單模板.xlsxCore里我堅(jiān)持不讓IWorkbook泄漏出去。對(duì)外方法簽名一律是Stream進(jìn)、Stream或ListT出業(yè)務(wù)層根本不需要using NPOI.SS.UserModel;。這么做有兩個(gè)直接好處單測(cè)里傳一個(gè)MemoryStream就能跑完整鏈路不落盤Web 上傳場(chǎng)景拿到IFormFile.OpenReadStream()可以直接喂進(jìn)去不用先存臨時(shí)文件再刪。samples目錄的作用容易被低估。.xls和.xlsx在單元格類型、日期序列號(hào)、公式緩存上的行為并不完全一致光靠猜沒用必須有一份真實(shí)的舊格式文件反復(fù)驗(yàn)證。templates目錄則是給“模板填充”這種需求準(zhǔn)備的——表頭、樣式、合并單元格都在模板里做好代碼只負(fù)責(zé)往里塞數(shù)據(jù)行改樣式的時(shí)候不用改代碼。3. 從零跑通裝包、寫第一個(gè) xlsx、再讀回 xls這一章的操作照著敲就能跑起來目標(biāo)是把“寫出去”和“讀進(jìn)來”這兩條鏈路都走通一遍中間不留黑匣子。3.1 建工程與引包# 建解決方案和兩個(gè)項(xiàng)目 dotnet new sln -n NpoiExcelDemo dotnet new classlib -n NpoiExcelDemo.Core -o src/NpoiExcelDemo.Core dotnet new console -n NpoiExcelDemo.Console -o src/NpoiExcelDemo.Console # 掛到解決方案下 dotnet sln add src/NpoiExcelDemo.Core src/NpoiExcelDemo.Console # NPOI 只需要裝在 Core 里Console 通過項(xiàng)目引用拿到 dotnet add src/NpoiExcelDemo.Core package NPOI dotnet add src/NpoiExcelDemo.Console reference src/NpoiExcelDemo.Core這里面幾個(gè)參數(shù)值得說明。-o是指定輸出目錄把項(xiàng)目塞進(jìn)src/是習(xí)慣不塞也能跑。dotnet add package NPOI不寫版本號(hào)默認(rèn)拉最新穩(wěn)定版如果目標(biāo)框架是netstandard2.0要給老項(xiàng)目引用加-f netstandard2.0或者直接改 csproj 里的TargetFramework。Framework 4.x 的老項(xiàng)目不走 CLI在包管理器里裝完記得看一眼依賴項(xiàng)——NPOI 會(huì)順帶拉一個(gè)壓縮庫發(fā)布的時(shí)候別只拷了NPOI.dll就以為完事了缺依賴的報(bào)錯(cuò)信息通常很含糊只說“未能加載文件或程序集”排查起來全靠猜。提示目標(biāo)框架選net8.0還是netstandard2.0取決于調(diào)用方。庫給多個(gè)項(xiàng)目共用就選netstandard2.0純新項(xiàng)目選net8.0能用上Span之類的新 API。3.2 寫出第一個(gè) .xlsxNPOI 的層級(jí)就四層工作簿 → 工作表 → 行 → 單元格。下面這段是最小閉環(huán)using NPOI.SS.UserModel; using NPOI.XSSF.UserModel; public static void WriteSimple(string path) { // 1. 工作簿XSSF 對(duì)應(yīng) .xlsx IWorkbook workbook new XSSFWorkbook(); ISheet sheet workbook.CreateSheet(對(duì)賬單); // 2. 表頭行 IRow header sheet.CreateRow(0); string[] titles { 訂單號(hào), 客戶, 金額, 下單時(shí)間 }; for (int i 0; i titles.Length; i) { header.CreateCell(i).SetCellValue(titles[i]); } // 3. 數(shù)據(jù)行 IRow row sheet.CreateRow(1); row.CreateCell(0).SetCellValue(SO-2024001); row.CreateCell(1).SetCellValue(某客戶); row.CreateCell(2).SetCellValue(1280.50); // 數(shù)值走 double 重載 row.CreateCell(3).SetCellValue(DateTime.Now); // 日期直接給 DateTime // 4. 列寬單位是 1/256 個(gè)字符寬度20 * 256 20 字符 sheet.SetColumnWidth(0, 20 * 256); using var fs new FileStream(path, FileMode.Create, FileAccess.Write); workbook.Write(fs); }逐段說一下。CreateSheet傳的名字就是 Excel 底部的標(biāo)簽名超過 31 個(gè)字符或含[]:*?/\會(huì)直接拋異常。CreateCell(i)的索引從 0 開始跳著創(chuàng)建也允許比如只創(chuàng)建第 0 和第 5 個(gè)中間的空單元格讀回來是CellType.Blank。金額這一行是關(guān)鍵SetCellValue(1280.50)存的是數(shù)值Excel 里能參與求和如果圖省事寫成SetCellValue(1280.50)存的是文本Excel 會(huì)在左上角給你標(biāo)個(gè)綠色小三角用戶一點(diǎn)“轉(zhuǎn)換為數(shù)字”全部格式又亂掉血淚經(jīng)驗(yàn)。日期同理SetCellValue(DateTime)會(huì)把它轉(zhuǎn)成序列號(hào)存儲(chǔ)顯示格式由單元格樣式的DataFormat決定不設(shè)樣式就是默認(rèn)的日期顯示。最后workbook.Write(fs)這個(gè)重載在不同版本上行為有差異有的會(huì)把流關(guān)掉有的不會(huì)。不確定的話就在Write之后立刻fs.Flush()并且不要指望后面還能繼續(xù)往這個(gè)流里寫東西。3.3 用 WorkbookFactory 統(tǒng)一讀 .xls 和 .xlsx讀這邊最容易犯的錯(cuò)是寫死new XSSFWorkbook(fs)遇到.xls就拋Invalid header signature。正確姿勢(shì)是工廠加接口using NPOI.SS.UserModel; public static void ReadAny(string path) { using var fs new FileStream(path, FileMode.Open, FileAccess.Read); // 關(guān)鍵工廠根據(jù)文件頭自動(dòng)選 HSSF 還是 XSSF IWorkbook workbook WorkbookFactory.Create(fs); for (int s 0; s workbook.NumberOfSheets; s) { ISheet sheet workbook.GetSheetAt(s); // LastRowNum 是最后一行索引空表返回 -1不能直接當(dāng)行數(shù) for (int r sheet.FirstRowNum; r sheet.LastRowNum; r) { IRow row sheet.GetRow(r); if (row null) continue; // 整行被刪過就是 null不判會(huì) NRE for (int c 0; c row.LastCellNum; c) { ICell cell row.GetCell(c); Console.Write(ExcelReader.GetCellText(cell) \t); } Console.WriteLine(); } } }WorkbookFactory.Create支持傳Stream或FileInfo內(nèi)部會(huì)讀文件頭判斷格式比看后綴靠譜得多。FirstRowNum和LastRowNum都返回索引空表或者全空行的情況下LastRowNum可能是-1、0或者你以為的行數(shù)寫for循環(huán)時(shí)用并且判row null這兩道保險(xiǎn)缺一不可。GetSheetAt是按順序取GetSheet(名字)是按名取。名字取不到會(huì)返回null而不是拋異常后面直接.GetRow()就炸了所以按名取的時(shí)候記得判空。3.4 跑起來看一眼dotnet run --project src/NpoiExcelDemo.Console -- ./out/demo.xlsx ./samples/legacy.xls參數(shù)依次是輸出路徑和要讀的舊格式樣本。跑完先確認(rèn)三件事out/demo.xlsx能被正常打開、金額那一列右對(duì)齊且能求和、legacy.xls的中文沒有亂碼。這三條過了說明環(huán)境、依賴、編碼都沒問題后面再改代碼就是純業(yè)務(wù)活了。4. 核心模塊拆解取值、樣式、大文件、格式差異這一段是真正要反復(fù)用的東西。示例里那幾個(gè)方法寫短是因?yàn)榘阉锌佣际者M(jìn)了這幾個(gè)方法里。4.1 單元格取值CellType 分支一個(gè)都不能漏讀 Excel 最典型的故障是“日期變成 45000 這種數(shù)字”根子在CellType.Numeric—— 日期在底層就是數(shù)字靠樣式區(qū)分。所以取值方法必須寫成這樣public static string GetCellText(ICell cell) { if (cell null) return string.Empty; switch (cell.CellType) { case CellType.String: return cell.StringCellValue; case CellType.Numeric: // 日期底層是序列號(hào)必須靠單元格樣式判斷直接 ToString 會(huì)得到 45000 if (DateUtil.IsCellDateFormatted(cell)) return cell.DateCellValue?.ToString(yyyy-MM-dd HH:mm:ss) ?? ; return cell.NumericCellValue.ToString(); case CellType.Boolean: return cell.BooleanCellValue ? TRUE : FALSE; case CellType.Formula: // 公式要按緩存結(jié)果類型再分一次支不能直接取 StringCellValue switch (cell.CachedFormulaResultType) { case CellType.Numeric: return DateUtil.IsCellDateFormatted(cell) ? cell.DateCellValue?.ToString(yyyy-MM-dd) ?? : cell.NumericCellValue.ToString(); case CellType.String: return cell.StringCellValue; default: return cell.ToString() ?? ; } case CellType.Blank: return string.Empty; case CellType.Error: // 把 #DIV/0! 這類錯(cuò)誤碼還原成可讀文本 return FormulaError.ForInt(cell.ErrorCellValue).String; default: return cell.ToString() ?? string.Empty; } }三個(gè)地方值得單獨(dú)講。DateUtil.IsCellDateFormatted(cell)是個(gè)靜態(tài)工具方法內(nèi)部讀的是單元格樣式的DataFormat字符串判斷是不是日期/時(shí)間格式比自己寫正則靠譜。CellType.Formula分支里必須先看CachedFormulaResultType—— 公式單元格的StringCellValue只有在緩存結(jié)果是字符串時(shí)才有效緩存是數(shù)字你卻去取字符串拿到的是空串或者直接拋異常這種問題在日志里只表現(xiàn)為“某幾列讀出來是空的”非常難定位。FormulaError.ForInt把0x07這種錯(cuò)誤碼轉(zhuǎn)成#DIV/0!報(bào)表里帶著錯(cuò)誤碼有時(shí)候反而是有用的信息別急著當(dāng)成異常吞掉。注意DateCellValue在較新版本里是DateTime?老版本可能是DateTime。如果編譯報(bào)“無法將 DateTime 轉(zhuǎn)換為 DateTime?”說明你手上的版本比較舊去掉?.就行。4.2 樣式復(fù)用ICellStyle 是共享池不是隨手 new 的樣式是 NPOI 里最容易被寫成性能問題的模塊。工作簿內(nèi)部維護(hù)一個(gè)樣式池你每CreateCellStyle()一次就多占一個(gè)槽位.xls上限大約 4000 個(gè).xlsx大約 64000 個(gè)超了直接拋異常而且文件體積會(huì)以肉眼可見的速度膨脹——見過一個(gè)導(dǎo)出的表 800KB 數(shù)據(jù)配 60MB 樣式就是這么來的。正確做法是做個(gè)樣式工廠按 key 緩存public sealed class ExcelStyleFactory { private readonly IWorkbook _wb; private readonly Dictionarystring, ICellStyle _cache new(); public ExcelStyleFactory(IWorkbook wb) _wb wb; public ICellStyle Money(string format #,##0.00) { if (_cache.TryGetValue(format, out var cached)) return cached; var style _wb.CreateCellStyle(); // 每調(diào)一次就占一個(gè)樣式槽 style.DataFormat _wb.CreateDataFormat().GetFormat(format); style.Alignment HorizontalAlignment.Right; style.BorderBottom BorderStyle.Thin; style.VerticalAlignment VerticalAlignment.Center; _cache[format] style; return style; } }CreateDataFormat().GetFormat(#,##0.00)里的格式串跟 Excel 自定義格式語法一致0.00%、yyyy/m/d、#,##0;(#,##0)這些都能直接用格式串本身也是被緩存的同一個(gè)串多次調(diào)用返回同一個(gè)對(duì)象。Money方法用格式串當(dāng)緩存 key是因?yàn)橥粋€(gè)工作簿里不同列可能需要不同小數(shù)位用字符串做 key 天然支持多套格式共存。用法上先取一次樣式循環(huán)里反復(fù)賦給不同單元格var styles new ExcelStyleFactory(workbook); var moneyStyle styles.Money(); foreach (var item in rows) { var cell row.CreateCell(2); cell.SetCellValue(item.Amount); cell.CellStyle moneyStyle; // 賦值不是 new }4.3 SXSSF 流式導(dǎo)出十萬行不能再用 XSSF數(shù)據(jù)量上去以后XSSFWorkbook把所有行都留在內(nèi)存里十萬行乘以十幾列堆基本就撐不住了。換成 SXSSFpublic static void WriteLarge(string path, IEnumerableOrderRow rows, int windowSize 500) { // windowSize內(nèi)存里保留的行數(shù)超出的會(huì)被刷到磁盤臨時(shí)文件 var workbook new SXSSFWorkbook(windowSize); try { var sheet workbook.CreateSheet(明細(xì)); int r 0; foreach (var item in rows) { var row sheet.CreateRow(r); row.CreateCell(0).SetCellValue(item.OrderNo); row.CreateCell(1).SetCellValue(item.CustomerName); row.CreateCell(2).SetCellValue(item.Amount); // 注意這一行一旦被刷出去后面 GetRow(r) 就取不到了 } using var fs new FileStream(path, FileMode.Create, FileAccess.Write); workbook.Write(fs); fs.Flush(); } finally { workbook.Close(); workbook.Dispose(); // 必須顯式調(diào)用否則臨時(shí)文件會(huì)留在系統(tǒng)臨時(shí)目錄 } }windowSize這個(gè)參數(shù)是內(nèi)存和磁盤 IO 的平衡點(diǎn)。設(shè)太小比如 100刷盤頻繁寫十萬行能明顯感覺到慢設(shè)太大比如 5000內(nèi)存優(yōu)勢(shì)就沒那么明顯了。我一般按 500 起步實(shí)測(cè)導(dǎo)出耗時(shí)偏高再往上調(diào)。Dispose()這一步不能省。SXSSF 在系統(tǒng)臨時(shí)目錄里建的文件只有Dispose才會(huì)清理進(jìn)程長(zhǎng)時(shí)間跑批又不釋放臨時(shí)目錄遲早被塞滿然后你會(huì)收獲一堆“磁盤空間不足”的告警排查半天發(fā)現(xiàn)是自己導(dǎo)出的表。4.4 兩種格式的行為差異能力.xlsHSSF.xlsxXSSF / SXSSF單表最大行655361048576單表最大列25616384單元格樣式上限約 4000約 64000文件本質(zhì)二進(jìn)制復(fù)合文檔zip 包 若干 xml新函數(shù)支持只有老函數(shù)集基本都能用讀入內(nèi)存占用相對(duì)低相對(duì)高這張表最有用的兩行是行數(shù)上限和樣式上限。行數(shù)超了不會(huì)報(bào)錯(cuò)會(huì)直接截?cái)嘁话偃f條數(shù)據(jù)導(dǎo)出成.xls最后只剩六萬五而且沒有任何提示——這種 bug 上線之后才被發(fā)現(xiàn)返工成本極高。樣式上限則是另一個(gè)方向.xls到 4000 就拋InvalidOperationException堆棧里看不到你的業(yè)務(wù)代碼只看到 NPOI 內(nèi)部的Workbook.CreateCellStyle。5. 避坑與排查五個(gè)真踩過的問題5.1 日期讀出來是 45000 這樣的整數(shù)現(xiàn)象導(dǎo)入的對(duì)賬單里時(shí)間列全是五位數(shù)用戶以為數(shù)據(jù)錯(cuò)了。 原因CellType.Numeric分支直接NumericCellValue.ToString()沒判斷日期格式。日期在 Excel 里本質(zhì)是從 1900-01-01 起算的天數(shù)45000就是某個(gè)真實(shí)日期。 解決取值統(tǒng)一走 4.1 那個(gè)GetCellTextNumeric分支先DateUtil.IsCellDateFormatted(cell)再?zèng)Q定是格式化日期還是原樣輸出數(shù)字。5.2 導(dǎo)出的文件打不開提示“發(fā)現(xiàn)不可讀取的內(nèi)容”現(xiàn)象瀏覽器下載下來的 xlsxExcel 打開報(bào)修復(fù)提示點(diǎn)“是”之后內(nèi)容可能還在也可能丟了。 原因九成是流被提前關(guān)掉或者Position沒歸零。workbook.Write(stream)在某些版本會(huì)關(guān)閉傳入的流之后Response.Body再寫就寫不進(jìn)去了另一種是同一個(gè)MemoryStream寫完沒Position 0就直接當(dāng)讀的源用。 解決寫文件的流自己using管好生命周期別依賴庫來關(guān)Web 場(chǎng)景用MemoryStream寫完先ToArray()再輸出讀之前一律stream.Position 0。5.3 大批量導(dǎo)出時(shí)內(nèi)存飆升甚至 OOM現(xiàn)象導(dǎo)五萬行的時(shí)候進(jìn)程內(nèi)存漲到 2G 以上容器直接被 kill。 原因用了XSSFWorkbook所有行和單元格對(duì)象都駐留在堆里一個(gè)單元格對(duì)象幾十字節(jié)五萬行乘二十列就是一千萬個(gè)對(duì)象。 解決換成SXSSFWorkbook窗口設(shè) 500 左右順手檢查一下是不是在循環(huán)里CreateCellStyle那個(gè)也是內(nèi)存大戶。5.4 讀 .xls 報(bào) Invalid header signature現(xiàn)象文件后綴明明是.xlsnew XSSFWorkbook(fs)直接拋異常。 原因一種是用錯(cuò)了實(shí)現(xiàn)類.xls得用 HSSF另一種更陰——某些系統(tǒng)導(dǎo)出的“xls”其實(shí)是 HTML 表格或者 CSV 改了后綴二進(jìn)制頭根本不是 OLE 復(fù)合文檔。 解決讀入口統(tǒng)一用WorkbookFactory.Create(fs)讓庫自己判斷如果工廠也認(rèn)不出來用十六進(jìn)制工具看一眼文件頭D0 CF 11 E0是真的 xlsPK是 xlsxhtml或者table就是偽裝的得先當(dāng)文本解析再轉(zhuǎn)。5.5 單元格樣式莫名不生效現(xiàn)象設(shè)置了邊框和背景色打開文件發(fā)現(xiàn)只有第一行有后面全是白板。 原因ICellStyle是工作簿級(jí)別的共享對(duì)象但很多人習(xí)慣在循環(huán)里CreateCellStyle()之后只對(duì)當(dāng)前單元格賦值同時(shí)又在別處CloneStyleFrom覆蓋了屬性結(jié)果樣式對(duì)象被復(fù)用后互相污染。 解決樣式只在工廠里創(chuàng)建一次循環(huán)里只做cell.CellStyle cachedStyle賦值確實(shí)需要“繼承再加一點(diǎn)差異”的用CloneStyleFrom克隆出一個(gè)新對(duì)象并單獨(dú)緩存別在原對(duì)象上改。6. 二次開發(fā)把示例收成一層能復(fù)用的導(dǎo)入導(dǎo)出示例代碼寫到后面你會(huì)發(fā)現(xiàn)每個(gè)業(yè)務(wù)實(shí)體都在重復(fù)“讀表頭 → 找列 → 轉(zhuǎn)類型”這套動(dòng)作。我一般會(huì)加一個(gè)特性加反射的映射層讓業(yè)務(wù)代碼只寫實(shí)體。[AttributeUsage(AttributeTargets.Property)] public sealed class ExcelColumnAttribute : Attribute { public ExcelColumnAttribute(string title) Title title; public string Title { get; } } public sealed class OrderRow { [ExcelColumn(訂單號(hào))] public string OrderNo { get; set; } ; [ExcelColumn(金額)] public decimal Amount { get; set; } [ExcelColumn(下單時(shí)間)] public DateTime CreatedAt { get; set; } }讀取端靠表頭文本反查屬性允許列順序和實(shí)體屬性順序不一致public static ListT ReadT(Stream stream) where T : new() { var map typeof(T).GetProperties() .Select(p (Prop: p, Attr: p.GetCustomAttributeExcelColumnAttribute())) .Where(x x.Attr ! null) .ToDictionary(x x.Attr!.Title, x x.Prop); IWorkbook wb WorkbookFactory.Create(stream); ISheet sheet wb.GetSheetAt(0); IRow header sheet.GetRow(sheet.FirstRowNum); // 表頭文本 - 列索引 var index new Dictionarystring, int(); for (int c 0; c header.LastCellNum; c) { var title ExcelReader.GetCellText(header.GetCell(c)).Trim(); if (!string.IsNullOrEmpty(title) map.ContainsKey(title)) index[title] c; } var list new ListT(); for (int r sheet.FirstRowNum 1; r sheet.LastRowNum; r) { var row sheet.GetRow(r); if (row null) continue; var entity new T(); foreach (var (title, prop) in map) { if (!index.TryGetValue(title, out var c)) continue; var text ExcelReader.GetCellText(row.GetCell(c)); if (string.IsNullOrWhiteSpace(text)) continue; // 可空類型要?jiǎng)円粚覥onvert.ChangeType 不認(rèn) NullableT var target Nullable.GetUnderlyingType(prop.PropertyType) ?? prop.PropertyType; prop.SetValue(entity, Convert.ChangeType(text, target)); } list.Add(entity); } return list; }改完之后業(yè)務(wù)側(cè)就一行var rows ExcelImporter.ReadOrderRow(stream);字段增減只改實(shí)體上的特性不用碰解析代碼。驗(yàn)證方式我用往返測(cè)試不落盤、跑得快[Fact] public void Xlsx_RoundTrip_ShouldKeepAmount() { var ms new MemoryStream(); using (var wb new XSSFWorkbook()) { var sheet wb.CreateSheet(t); var head sheet.CreateRow(0); head.CreateCell(0).SetCellValue(訂單號(hào)); head.CreateCell(1).SetCellValue(金額); var data sheet.CreateRow(1); data.CreateCell(0).SetCellValue(SO-1); data.CreateCell(1).SetCellValue(99.5); wb.Write(ms); } ms.Position 0; // 不歸零讀出來就是空的 var rows ExcelImporter.ReadOrderRow(ms); Assert.Single(rows); Assert.Equal(99.5m, rows[0].Amount); }這個(gè)測(cè)試我建議再補(bǔ)三個(gè)邊界樣本一個(gè)帶合并單元格的表頭、一個(gè)日期列為空的行、一個(gè)金額列是公式的表。前兩個(gè)驗(yàn)證判空邏輯第三個(gè)驗(yàn)證CachedFormulaResultType分支。這三個(gè)樣本跑通線上八成的導(dǎo)入投訴基本能提前擋掉。從那以后我每次接 Excel 相關(guān)的需求都會(huì)先問清三句話讀進(jìn)來的是什么格式、寫出去給誰用、最大多少行然后才動(dòng)手寫第一行代碼。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取