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