简介NPOI 1.2.5 DLL组件包为.NET开发者在项目中处理Office文档提供了核心依赖无需安装Microsoft Office即可实现Excel与Word的创建、读取、编辑、格式设置及数据批量处理等常见办公自动化操作兼容.NET Framework与.NET Core跨平台项目。包体共收纳245个文件以102个cs源码文件、48个csproj工程配置和6个dll动态库为主另含示例xls、config配置文件、exe可执行程序等辅助资源整体约5.98MB便于快速下载部署。目前已有225人学习使用。除核心DLL外资源还附带大量示例代码与项目配置覆盖创建工作簿与工作表、添加行列、单元格样式、公式使用等核心功能并演示了大数据量场景下的内存流处理与性能优化思路可帮助开发者快速掌握NPOI各类API的调用方式尤其适合需要生成Excel报表、处理Word文档的.NET人员直接引用或对照学习省去自行查阅文档和整理依赖的时间。1. 为什么一套NPOI 1.25 DLL值得单独收藏先解决“拿得到却用不起”做.NET报表导出NPOI基本是绕不开的名字。我手头这个项目组最近被一个奇怪的问题折腾了两天线上导出.xlsx总在打开时提示内容损坏用旧版NPOI的DLL没问题换成网上某个“最新版1.25”的压缩包就翻车。后来发现不是API的问题而是压缩包里少了NPOI.OpenXmlFormats.dllXSSFWorkbook直接在new的时候抛异常。NPOI 1.2.5/1.25这套版本号在不同渠道写法不一样但程序集版本是一致的。这套DLL对.NET Framework 4.5和.NET Core/5/6的开发者都适用尤其是离线环境、内网开发、以及想避开2.x包引入的新依赖时。这篇笔记我把校验清单、引用姿势、读写参数和常见坑一起写掉方便直接照着复现。2. 先确认手里的NPOI是完整包程序集清单、版本号与目标框架很多下载包里文件名写着“NPOI最新版1.25”解压出来却只有两个DLL。直接引用到项目里编译能过运行时才报错。这一章先解决两个问题怎么确认版本号没写错以及一套能用的NPOI至少需要哪些文件。2.1 版本号“1.25”还是“1.2.5”先统一命名避免搞混版本号写法的分歧是最容易踩的玄学点。NuGet上搜索NPOI显示的版本是1.2.5而一些下载站写成1.25博客里也常写“NPOI 1.25”。这其实指向同一个东西NPOI 1.2.5.0版本的程序集。判断标准不应该是文件名而是程序集的版本号。拿到DLL后在PowerShell里先跑这两条命令$dll Get-Item NPOI.dll $dll.VersionInfo.FileVersion [System.Reflection.AssemblyName]::GetAssemblyName(NPOI.dll).Version第一条输出文件版本第二条输出程序集版本。多数情况下两者一致都是1.2.5.0如果发现不一致以程序集版本为准因为程序集加载器匹配的是AssemblyVersion。检查时不需要管理员权限唯一要求是当前PowerShell工作目录能访问到DLL或者把路径写成绝对路径。我一般会把这个脚本存成check-npoi.ps1发到项目组几个同事手里避免有人从不同渠道拿到的DLL版本不一致最后互相甩锅。这里还有一个容易忽略的点如果项目里已经通过NuGet引用了NPOI 2.x再手动把1.2.5的DLL拷到bin目录PowerShell查文件版本显示的还是1.2.5但运行时加载器可能优先加载高版本程序集。所以校验要在干净的目录里做bin目录里如果有多个NPOI.dll说明项目本身就已经混了。2.2 核心程序集与依赖清单缺了哪一个都会在运行时翻车一套完整的NPOI 1.2.5包至少包含五个关键程序集。这一节配一张表哪个文件管什么是先要知道的程序集职责缺失时典型报错NPOI.dll基础类型、SS公共接口、HSSF(.xls)编译期直接红叉NPOI.OOXML.dllXSSF(.xlsx)读写实现调用xlsx接口时TypeLoadExceptionNPOI.OpenXml4Net.dllOpenXML打包容器读取new XSSFWorkbook时FileFormatExceptionNPOI.OpenXmlFormats.dllXLSX内部schema序列化与上一项一起报错ICSharpCode.SharpZipLib.dllZIP压缩解压打开文件时数据损坏/无法读取我在不同下载包里见过只放前两个的压缩包体积小看着干净但一旦用到xlsx就报“文件不是有效的OpenXML格式”。这不是文件坏了而是OpenXml4Net没被带进项目输出目录。常见做法是检查项目里每个NPOI相关引用的“复制本地”属性或者手动把缺的DLL放到bin目录。更稳妥的做法是用NuGet安装自动带依赖后面第三章会细讲。还有一点是关于ICSharpCode.SharpZipLib.dll的这个不是NPOI项目本身的代码而是第三方压缩库。有些精简包会把它的逻辑并进NPOI.OpenXml4Net里这种情况在旧版出现过但1.2.5这套依然独立依赖。如果你在部署时遇到“FileNotFound: ICSharpCode.SharpZipLib”说明打包方漏掉了这个第三方文件。值得注意的是这个DLL自身版本号很高可能与项目里其他用到的SharpZipLib冲突到时需要统一版本。另外正规压缩包里通常还带一份license.txt和README前者是Apache 2.0许可后者会标注编译环境。如果下载包只有DLL没有许可文件倒不影响使用但公司法务审代码时可能会追问。个人使用无所谓企业内部建议保留原始文件避免来路不明的DLL混进版本库。2.3 目标框架选择net40、netstandard2.0与调用方的兼容边界NPOI 1.2.5的发布包常见带net20、net40、netstandard2.0三个目录。很多老项目还在.NET Framework 4.0看到netstandard2.0不敢下新项目用.NET 6却找不到netstandard2.0目录只能拿net40硬怼。我自己的选择标准如下调用方目标框架推荐选择原因.NET Framework 4.0/4.5net40目录的DLL不引入兼容性API缺失问题.NET Framework 4.7.2netstandard2.0后续升级到.NET Core更平滑.NET Core/.NET 5必须用netstandard2.0net40程序集在跨平台运行时会因API缺失启动失败选择错误最常见的结果不是编译报错而是运行时在Linux容器里抛“Method not found”。某次我把net40版直接复制给一台.NET 8的Linux服务启动时没异常一调用XSSFWorkbook就崩后来查日志发现是net40里调用了Framework专属的加密接口。所以动手前先确认项目目标框架再有选择地复制对应子目录。确认目标框架的办法很简单右键项目属性看“目标框架”下拉框.NET Core项目看csproj里的TargetFramework字段。如果是老式.csproj直接搜索 。选好目录后把对应DLL统一放到项目libs目录并在版本控制里提交同时写一个README说明来源和版本。很多项目就是忽略了这一步半年后再维护时根本不知道bin里NPOI从哪里来。3. 把NPOI 1.2.5接进项目的三条路线引用、NuGet替换与私有化合并确认包完整之后就是让项目跑起来。这一章给三条路线分别应对离线开发、在线包管理和交付给第三方的场景。每条路线我都踩过或看到别人踩过重点已经写进参数里。3.1 路线一在csproj里直接引用本地方案如果项目无法联网最直接的方式是在csproj里加Reference节点。以传统.NET Framework项目为例常见写法是Reference IncludeNPOI HintPath..\packages\NPOI\NPOI.dll/HintPath PrivateTrue/Private /ReferenceHintPath是编译时查找DLL的路径Private决定生成后是否把DLL复制到bin目录。这里最容易犯的错是漏写Private结果开发机上有DLL部署服务器上找不到。我之前给某个内部工具做维护时就栽过本机编译运行都正常拷到服务器就报FileNotFoundException原因就是Private没设bin目录里没有NPOI.dll。另一件值得留意的事是HintPath里的路径分隔符在Windows下用\没问题项目被放到Linux CI上编译时尽量用/或者把依赖统一放一个目录减少兼容性意外。添加引用的另一种方式是在VS里右键项目“添加引用-浏览”选择NPOI.dllIDE会生成类似的Reference节点。但这种方式在多人协作时容易带出本地绝对路径比如HintPath写成了“C:\Users\某开发者\libs\NPOI.dll”队友拉代码编译直接失败。我一般会把第三方DLL统一放到仓库的libs目录并使用相对路径。这是离线项目组最稳的做法。如果项目是SDK风格Reference同样有效但有时候会提示重复引用此时删除重复节点即可。对于新项目我更建议用下一节的方式交给NuGet统一管理。3.2 路线二NuGet安装并锁死版本能联网时最省事的是用包管理器装Install-Package NPOI -Version 1.2.5.NET Core风格的SDK项目则用dotnet add package NPOI --version 1.2.5这里的关键是“-Version”参数不加这个参数会直接拉当前最新大版本比如2.x导致项目里现有代码虽然命名空间一致但行为变化很大。例如2.x里SXSSFWorkbook的构造方式做了一点调整老代码可能编译不过。装完之后用Get-Package -ProjectName 你的项目看看有没有出现两个NPOI版本。如果之前手动拷过DLL先移除再安装否则bin目录混入新老两个程序集运行时按加载顺序随机用一个这就是典型的“同一套代码有人报错有人不报”的根源。NuGet路线的额外好处是依赖项自动带进项目不需要手工找SharpZipLib。但要注意NuGet上1.2.5的包可能只带net20和net40不一定有netstandard2.0资产所以.NET Core项目用这条命令时要看包的依赖兼容性。我一般在安装后检查项目下obj/project.assets.json搜索“NPOI”看编译资产里解析到哪个目标框架目录。这一步骤只需几秒钟能省下一整天的“为什么单元测试跑不过”。3.3 路线三用ILMerge把依赖并进一个DLL如果你做的是给第三方调用的组件或者对方不希望输出目录有一堆DLL可以用ILMerge合并成一个ILMerge.exe /out:MyNPOI.dll NPOI.dll NPOI.OOXML.dll NPOI.OpenXml4Net.dll NPOI.OpenXmlFormats.dll ICSharpCode.SharpZipLib.dll /targetplatform:v4/out指定合并输出文件名/targetplatform指定目标平台。合并后调用方只需要引用MyNPOI.dll。这个方案有两个坑第一合并后的程序集如果有强名称要求需要重新签名否则放到要求签名程序集的项目里会拒绝加载第二NPOI内部有些通过反射读取类型的操作合并后类型路径变了早期版本经常报“Could not load type”。我只有在组件只用标准写Excel接口时才合并其余情况宁愿多带几个DLL。合并之前最好先确认NPOI需要的所有依赖都在ILMerge命令参数里。漏掉一个文件合并过程不报错运行时照样报错。如果遇到合并后运行时报错可以把NPOI.OOXML.dll排除在合并之外只合并主程序集中的公共逻辑虽然输出目录多一个文件但稳定性明显提升。合并之后用6.2节的sn命令检查签名如果能提取公钥令牌说明签名有效。如果合并后类型加载异常可以尝试改用Costura.Fody等插件内嵌程序集它对NPOI的兼容性比ILMerge稍好但会多一些页面配置。4. 实际读写Excel的关键参数Workbook选型、内存控制与样式表设置这一章进入真正写代码的阶段。NPOI能读写xls和xlsx但API入口不同参数细节也不少。我把选型、大文件写、样式和读操作四块拆开讲。4.1 选型HSSFWorkbook还是XSSFWorkbook一张表说清读写Excel第一件事就是选Workbook实现。NPOI里HSSFWorkbook对应Office 97-2003的.xlsXSSFWorkbook对应.xlsx。两者对比如下对比项HSSFWorkbookXSSFWorkbook扩展名.xls.xlsx最大行数655361048576最大列数25516384内存开销较低较高依赖程序集只需要NPOI.dll需要OOXML等四个程序集选择的核心是看业务文件格式。如果系统导出一向是.xls用户用WPS打开继续用HSSFWorkbook最保险如果要支持.xlsx新特性比如下拉列表、数据透视、更大的行数换XSSFWorkbook。我在项目里同时封装了两个入口尽量不把Workbook实现写死在业务代码里using NPOI.HSSF.UserModel; using NPOI.XSSF.UserModel; using NPOI.SS.UserModel; public static IWorkbook CreateWorkbook(string extension) { if (extension.Equals(.xlsx, StringComparison.OrdinalIgnoreCase)) return new XSSFWorkbook(); if (extension.Equals(.xls, StringComparison.OrdinalIgnoreCase)) return new HSSFWorkbook(); throw new NotSupportedException(不支持的文件类型: extension); }这里返回IWorkbook后续创建Sheet、Row、Cell的代码与具体实现无关。但要注意XSSFWorkbook和HSSFWorkbook的单元格样式不通用如果同一份模板要兼容两种格式样式代码要分别处理。另一点是HSSFWorkbook在Linux服务器上生成.xls时通常没问题但读取某些被WPS修订过的.xls可能遇到兼容性异常老格式的黑匣子只能靠升级版本缓解。4.2 大数据量写入SXSSFWorkbook的窗口参数 windowSize超过几万行的xlsx导出用XSSFWorkbook全部放内存很容易吃掉几百兆。NPOI提供了SXSSFWorkbook本质是滑动窗口指定滑动行数后前面的行会被刷入临时文件using NPOI.XSSF.UserModel; using NPOI.SS.UserModel; SXSSFWorkbook workbook new SXSSFWorkbook(100); ISheet sheet workbook.CreateSheet(大数据); for (int i 0; i 100000; i) { IRow row sheet.CreateRow(i); row.CreateCell(0).SetCellValue(行 i); } using (FileStream fs File.Create(C:\temp\big.xlsx)) { workbook.Write(fs); } workbook.Dispose();SXSSFWorkbook的构造函数参数100就是windowSize表示内存中保留100行。它有两个特性要记住一它是单向的只能写不能读别指望用SXSSFWorkbook读文件二写入过程中磁盘会生成临时文件写完后必须调用Dispose删除临时文件否则服务器磁盘会被这些临时文件塞满。我见过一次生产事故定时任务导出3万行连续跑了半年C盘被NPOI临时文件占掉十几个GB就是因为漏了Dispose。windowSize调大可以减少磁盘IO但内存峰值变高调小相反。一般以500为参考值写10万行以内时效果都不错。4.3 列宽与日期格式两个最容易遭吐槽的参数列宽和日期格式是导出Excel里最常被提问题的细节。列宽单位是字符宽度的1/256所以想让某列容纳30个字符要这样写ISheet sheet workbook.CreateSheet(示例); sheet.SetColumnWidth(0, 30 * 256);如果不乘256设置的值很小列窄得看不见内容。日期格式则要手动绑定DataFormatICellStyle dateStyle workbook.CreateCellStyle(); dateStyle.DataFormat workbook.CreateDataFormat().GetFormat(yyyy-MM-dd HH:mm:ss); IRow row sheet.CreateRow(0); ICell cell row.CreateCell(0); cell.SetCellValue(DateTime.Now); cell.CellStyle dateStyle;这里常见误用是只SetCellValue(DateTime.Now)而不设置CellStyleExcel里显示出一串序列数字如44271.1234。要记住NPOI里日期本质是数值显示成日期全靠Style.DataFormat。另一个容易踩的是SetCellType把单元格先设成字符串再设数值NPOI的API可能在你设值后就覆盖了类型所以顺序一般是先SetCellValue再设置风格。如果公式单元格需要文本不要依赖Excel自动转换背后很多转码问题都出在CellType与SetCellValue的交互上。4.4 读取已有文件WorkbookFactory.Create与流关闭的坑读取用户上传的Excel也需要版本匹配。与其自己判断扩展名不如用WorkbookFactoryusing NPOI.SS.UserModel; using (FileStream fs File.OpenRead(C:\temp\upload.xlsx)) { IWorkbook workbook WorkbookFactory.Create(fs); ISheet sheet workbook.GetSheetAt(0); Console.WriteLine(sheet.GetRow(0).GetCell(0).StringCellValue); }WorkbookFactory.Create会根据文件头自动选择HSSFWorkbook或XSSFWorkbook不需要自己判断扩展名。但要注意如果inputStream是一个FileStream打开后不要过早用using关闭流否则后续保存或读取单元格可能访问已关闭的流。我一般在读取时直接把FileStream的生命周期延长到Workbook处理完也就是放在同一个using块里。WorkbookFactory在解析大文件时同样会把整本读进内存遇到几百MB的xlsx考虑用拆分或转CSV的方式降低峰值。5. 避坑记录NPOI 1.2.5使用中的五个高频翻车点前面几章讲的是怎么选、怎么接这一章把高频翻车点整理成“现象-原因-解决”的记录。每一条我都见过至少两次代码层面的问题往往都在这里。5.1 现象打开导出的xlsx提示“Package should contain a content type”原因这个报错看起来像文件损坏实际是文件内部的[Content_Types].xml缺失或路径不合法。常见于代码里用了HSSFWorkbook生成数据却把文件扩展名写成.xlsx。HSSF生成的是BIFF8的复合文档不是OpenXML的zip包用Excel打开时被当成xlsx解析自然找不到content type。也有情况是手动用File.Create后没有关闭流就再次读取导致文件不完整。解决确认Workbook实现与扩展名一致。用XSSFWorkbook就存.xlsx用HSSFWorkbook就存.xls如果调用方非要用.xlsx就老老实实换成XSSFWorkbook。写入完成后在返回文件前重新打开一次做完整性校验我一般用FileStream的Length属性大于0还不够要再new XSSFWorkbook读一次读不通过不发出去。5.2 现象下载文件时文件名中文乱码Excel单元格里的中文变成问号原因前者多半是HTTP响应头没做URL编码。Web端导出时浏览器根据Content-Disposition里的文件名识别编码如果直接拼中文浏览器按ASCII解析就乱码。后者单元格中文变问号则可能是模板里字体指定了不支持中文的字符集或者代码里用了旧编码转字符串。解决文件名用System.Net.WebUtility.UrlEncode编码后再放进Content-Disposition单元格文本写入前保持.NET字符串原生Unicode不要手动转换到GB2312再赋给SetCellValue。如果目标是用Excel打开需要把单元格字体设置成可以覆盖中文的字体比如“宋体”或“微软雅黑”。这个问题和NPOI版本关系不大更多是周围代码的编码习惯。5.3 现象用SetCellValue写入公式后打开Excel显示#VALUE!原因NPOI写入公式时只写公式字符串不重新计算公式也不一定有上一次计算缓存。Excel打开时通常会重新计算但如果文件中公式依赖的单元格类型不对或者公式区域有合并单元格就会直接显示#VALUE!。另一个原因是写入公式时少了前缀等号NPOI的SetCellFormula自动处理等号但如果自己拼字符串时带了一个等号旧版NPOI会把两个等号写进公式也会翻车。解决写公式统一用cell.SetCellFormula别自己拼“”。写完公式后用公式求值器强制计算一次XSSFFormulaEvaluator evaluator new XSSFFormulaEvaluator(workbook); evaluator.EvaluateAll();这会缓存计算结果打开文件时即使Excel不重算也能看到值。但要注意这会将文件里所有公式都计算一遍耗时随公式数量增加建议只在导出后处理时调用。5.4 现象导出超过5万行内存占用飙升到2G甚至OOM原因XSSFWorkbook把所有行数据实体都放在内存导出行数大每行有多个单元格引用类型和样式表也会累积。SXSSFWorkbook虽然存在但很多人不敢换怕API与现有代码不兼容。这个顾虑可以理解但5万行以上用XSSF基本属于自杀式写法。解决写入侧切到SXSSFWorkbook并设置200的窗口读取侧遇到大文件不要用WorkbookFactory.Create直接全量读NPOI没有成熟的流式读取模型实用做法是把xlsx拆成多个小文件再用XSSFWorkbook逐个处理或者把需要读取的区域先转成CSV。如果业务必须全量读至少在每个分页导出后释放引用调用GC.Collect只能缓解不能根治。5.5 现象运行时抛“未能加载文件或程序集 NPOI, Version1.2.5.0”原因同一个进程里出现了两个不同版本的NPOI程序集。最常见的是项目A引用了NuGet的1.2.5项目B直接拷了2.x的DLL最终bin目录里两个NPOI.dll并存加载器随机挑一个。如果是.NET Framework项目app.config里可能还缺少bindingRedirect导致编译用的1.2.5运行时被强制加载不存在的2.5。解决用Everything搜索整个解决方案目录确认只有一份NPOI.dll所有项目统一版本。用NuGet管理的项目在app.config里加bindingRedirectdependentAssembly assemblyIdentity nameNPOI publicKeyToken04b0db5e7e0c5a5b cultureneutral / bindingRedirect oldVersion0.0.0.0-2.5.0.0 newVersion1.2.5.0 / /dependentAssembly这个公钥令牌是从DLL提取出来的如果项目里的是被重新签名的DLL令牌可能不同。其实更省事的办法是删除手动拷贝全部改用NuGet引用同一个版本避免各种不知来源的DLL混进来。6. 拿到DLL后的三条自查命令与一个最小用例先验证再上线最后一章分享我从这套DLL里学到的习惯任何下载的NPOI包先做三条验证再跑一个最小用例确认通过后才进仓库和上线。6.1 用PowerShell核对程序集版本防止货不对板[System.Reflection.AssemblyName]::GetAssemblyName(NPOI.dll).Version如果输出是1.2.5.0说明版本对如果是2.x说明文件名是骗人的。这个命令只需要DLL在本地存在不会加载到进程所以安全。6.2 用强名称工具查看签名防止缺依赖在VS开发者命令行里执行sn -T NPOI.dll如果得到一段公钥令牌说明程序集有强名称改动过的DLL需要重签如果提示“无符号程序集”那么项目引用时要注意签名策略。顺带再用ILDasm或直接解包检查是否有NPOI.OOXML.dll避免只有主程序集。6.3 最小用例30行C#生成并读回xlsx最后写个最小控制台生成一个xlsx再读回来验证整个过程IWorkbook wb new XSSFWorkbook(); ISheet sh wb.CreateSheet(t); IRow r sh.CreateRow(0); r.CreateCell(0).SetCellValue(hello); using (var fs File.Create(unit.xlsx)) { wb.Write(fs); } using (var fs File.OpenRead(unit.xlsx)) { IWorkbook wb2 new XSSFWorkbook(fs); Console.WriteLine(wb2.GetSheet(t).GetRow(0).GetCell(0).StringCellValue); }如果这条程序输出hello说明DLL完整性、依赖链、读写路径都正常。这个用例我在每次升级NPOI时都会跑跑完再进代码仓库。从那以后我每次拿到新的NPOI DLL无论文件名写着多新的版本都会先执行6.1和6.2再跑6.3确认版本、签名和读写闭环后才替换到项目里。这个习惯救过我至少三次一次是下载包少DLL一次是名字写错版本号一次是网上的包被二次编译过。希望帮到你。本文还有配套的精品资源点击获取