NPOI 1.25 DLL 详解：版本辨析、Excel读写与升级迁移指南

简介在.NET开发中Excel文件的程序化读写是一项高频需求。许多老系统至今仍依赖NPOI 1.2.5常被网盘简称为“1.25 DLL”这类纯C#类库无需安装Office即可生成xlsx或读取旧xls文件。理解版本号的真实含义、正确引用DLL并管理log4net等依赖项是避免运行期异常的关键。本文从基础概念切入梳理1.2.5与2.x新主线在目标框架、内存模型和API上的差异并给出创建xlsx、读取xls、样式与公式设置等落地代码同时针对程序集加载失败、文件损坏、大文件内存暴涨等高频故障提供排查路径。最终结合数据自校验与三步替换法为开发者提供一个从旧版本平滑迁移到新版NPOI的决策框架适合维护老项目的.NET工程师参考。1. NPOI 1.25 DLL一个文件搞定的 Excel 读写为什么还有人守着旧版本NPOI 1.25 DLL 这个关键词说出来就自带一股怀旧气息。很多做 .NET 的老开发手里压着一堆老系统导出 Excel 用的就是 NPOI 1.2.5 的 DLL一放就是五六年没动过。它凭一个几 MB 的类库就能让 C# 程序直接生成 xlsx、读取老 xls不用装 Office也不用担心服务器上有没有 Excel 环境。今天这篇笔记不打算替这个版本吹价值而是按一线干活的路子把怎么拿到这个 DLL、装进项目、读写文件、排查问题讲透最后给你一条从旧版本迁到新主线的退路。适不适合你看完全文再下结论。2. 先把版本号拆开看1.25 是哪条线的包项目该不该用它这里要弄清楚一个特别容易翻车的点你搜到“NPOI 最新版 1.25 DLL”时绝大多数情况是指 1.2.5而不是 1.25.0。官方版本号是点分三段1.2.5 表示主版本 1、次版本 2、修订 5传到网盘的人为了省事把文件名写成 NPOI_1.25 或者 NPOI 1.25 DLL点号被吞掉才会出现这个说不清道不明的版本号。如果你在包管理器里按 1.25 直接搜索大概率是空手而归正确写法是 1.2.5。2.1 版本号陷阱什么时候 1.25 等于 1.2.5什么时候不是为什么说“大多数情况”因为我确实见过有项目在引用一个 1.25.0 的私有打包版那是某个中间人把 1.2.5 的源码做了一点改动后重新编译的产物只在自己内部流传。这种包最大的问题是没人维护、没人和官方对应出了问题连源码都找不到。判断方法很简单看 DLL 的文件版本和产品版本右键属性里能看到 1.2.5.0 之类的数字如果显示 1.25.0.0而文件名又正好叫 1.25那基本可以确定不是官方发行版。文件名里的版本号不是公约DLL 上的签名才是。NPOI 1.2.5 是 API 还比较收敛的版本主要分三大块HSSF 管 .xlsXSSF 管 .xlsxHWPF 管 .doc。这个版本之后官方把 API 往深了重构命名空间和类名整体变动很多老代码在新版里需要改 using 和类型。所以“最新版 1.25 DLL”这个说法本身是矛盾的——它不是最新只是一个被别人写在文件名里的旧版本。真正官方路线走的是 2.x 后面的迭代如果你拿到的是一个宣称“最新”的 1.25 打包版第一反应应该是警惕而不是兴奋。2.2 这个版本适合的三种项目和我会直接劝退的三种项目适合的场景我按这几年见到的项目归纳一下第一类是还在 .NET Framework 4.5 附近跑的传统 Web 应用比如老后台管理系统定时任务项目WinForm 工具。这类项目升级框架成本高NPOI 1.2.5 又能满足需求没必要为了追新而追新。第二类是只需要读写 xls 老格式的系统比如财务模块对接 Excel 2003 版本导出HSSF 在这条路上最稳定1.2.5 的 HSSF 代码在论坛上沉淀了大量案例遇到问题容易搜到答案。第三类是纯内网、不联网的服务器没有外网拉包的条件把 DLL 直接拷进进程靠着老版本跑完生命周期。而真正该劝退的是这几种一是 .NET Core / .NET 5 的新项目1.2.5 的 DLL 是基于 .NET Framework 编译的直接引用经常给你表演一个“未能加载文件或程序集”何必折磨自己。二是要生成超大 xlsx 的项目比如几万行以上的流水表1.2.5 的 XSSFWorkbook 会把行数据全放内存导出几万行就敢吃几百 MB。三是刚开始接触 NPOI 的新人我建议直接学新版本别让老 API 形成肌肉记忆后面再改很别扭。这个选择没有标准答案只有风险最低的路径。2.3 认准这张选型对照表老 DLL 与新主线到底差在哪光说不如一张表看得快我把关键的差异按选型时关心的点列出来对比项NPOI 1.2.5常见“1.25 DLL”NPOI 2.x 以后的新主线目标框架.NET Framework 2.0/4.x.NET Framework / NetStandard 2.0 以上xlsx 支持XSSF 可用大文件性能差XSSF SXSSF 流式写入内存友好依赖项需要额外带 log4net、SharpZipLib依赖项大幅收敛大多打包解决命名空间NPOI.SS.UserModel、NPOI.XSSF.UserModel基本一致但类型有扩展维护状态老版本停止演进持续更新Bug 修复及时表格要结合场景读如果你的服务器还是 Windows Server 2008 R2、项目也锁死在 .NET Framework 4.0那 1.2.5 能跑就是胜利别乱升。如果项目能上 .NET 6哪怕只是新写一个小服务我也建议你用新版 NPOI省掉后面一堆兼容性麻烦。选型不是比版本号新鲜而是比项目生命周期里哪个方向风险更低。这个决定一旦做错后面每次发版都会在环境搭建上多花两小时。3. 把 1.25 的 DLL 装进项目三种引用方式与依赖项检查这一章解决的是“我拿到压缩包之后往项目里怎么放”的问题。老手可能觉得这是点两下鼠标的事但实际翻车最多的一步就是只复制了 NPOI.dll 却没带上依赖项编译能过运行直接崩。所以下面三种方式我都给了操作路径最后还附了一份依赖项检查清单。3.1 方式一复制 DLL 并手工添加引用老项目的常规操作先去官方发布页或已经下载好的压缩包里找到对应 .NET Framework 版本的 DLL。我一般会先把压缩包里的 lib 目录整个解压出来而不是只挑 NPOI.dll。以最常见的目录结构为例里面一般会有 net20、net40 或 net45 子目录按目标框架选。把整个子目录放到项目的 Libs/NPOI 文件夹下然后在解决方案资源管理器里右键引用添加引用浏览到刚才那个目录手动勾选需要的 DLL注意不要勾到 net20 的版本放到 net45 项目里。# 假设项目在 D:\Work\ExportServiceDLL 放在同盘 Libs 目录 $source D:\Downloads\NPOI_1.2.5\lib\net40 $target D:\Work\ExportService\Libs\NPOI Copy-Item -Path $source\*.dll -Destination $target -Recurse这段 PowerShell 命令把整个 net40 目录下的 DLL 一次性复制进项目 Libs 目录。要注意的是net40 和 net45 的选择不是随便挑的如果目标项目是 .NET Framework 4.0 就选 net404.5 及以上选 net45 更保险老框架版本跑新编译的 DLL 会直接报找不到入口。复制完成后再在项目里添加引用确保所有文件都在同一个文件夹后续部署时整个目录一起发。命令里 Path 和 Destination 两个参数按实际路径改就行Recurse 保证子目录结构也复制到位。我见过有人手滑把源码目录当成 lib 复制进去编译时引用了十几个 pdb 文件纯属浪费力气如果你解压出来有源码目录别拷它只拷 DLL。另外注意有些压缩包会有中文路径PowerShell 处理起来偶尔会乱最简单的方式是先解压到一个全英文路径再执行复制。3.2 方式二用包管理器按指定版本安装命令与参数说明如果你想避开手工复制带来的依赖遗漏最稳的就是用包管理器安装。这里要强调一句包管理器里的版本号是 1.2.5不是 1.25。执行下面的命令前先把项目默认目标框架确认好因为旧包在 .NET Framework 项目里才正常。Install-Package NPOI -Version 1.2.5在开发环境的“包管理器控制台”里跑这一行安装成功后项目引用里会多出 NPOI 以及它自动带上的依赖项。这里有一个细节包管理器帮你带依赖的能力取决于这个版本的清单文件写得全不全老版本包有时候依赖项写得比较粗安装完仍然需要手工补引用。所以我哪怕用了这条命令也依然会去 bin 目录看一眼实际带出来的文件。-Version 参数必须写在包名后面严格区分大小写。如果你直接写 Install-Package NPOI那装的是当前源里面的最新版跟本文说的 1.2.5 就不是一回事了。装完之后注意看输出窗口里有没有“成功安装 NPOI 1.2.5”这一句不要只看绿色的提示框就以为完事。假如你用的是国内镜像源老版本包可能没有被同步完整这时候与其折腾镜像不如回到方式一手工放置 DLL。3.3 依赖项不是玄学DLL 清单检查清单老版本 NPOI 最让人头疼的就是依赖项。我把检查顺序列出来你照着做能少熬夜第一看 NPOI.dll 引用了哪些程序集用反编译工具打开 NPOI.dll展开引用列表看到 log4net 和 ICSharpCode.SharpZipLib 是正常的。第二去你的输出目录确认这两个 DLL 是不是和 NPOI.dll 待在同一层。第三如果项目里已经从别的地方引用了不同版本的 log4net马上会撞版本后面单独讲。# 在输出目录里检查关键依赖是否存在 $bin D:\Work\ExportService\bin\Debug Get-ChildItem $bin -Filter *.dll | Where-Object { $_.Name -match NPOI|log4net|SharpZipLib } | Select-Object Name, Length这条命令的过滤器里把 log4net 和 SharpZipLib 都带上是因为这两个是老 NPOI 跑起来绕不开的依赖。如果输出里只有 NPOI.dll 一个文件说明要么复制时漏了要么项目里用到了别的方式引用依赖。缺哪个补哪个别把从网上下载的杂牌同名 DLL 塞进去版本冲突比缺文件更难查。还有一个小习惯我会把输出目录里的所有 NPOI 相关文件按修改时间排个序这样能一眼看出是不是有旧文件没被覆盖部署时最容易踩的就是这个坑。提示手工引用 DLL 的项目建议在版本管理工具里把 Libs 目录一并提交不要只在本地放着。否则同事拉代码后只有引用没有文件编译会直接红一排。4. 用 NPOI 1.25 DLL 读写 Excel从创建 xlsx 到读取老 xls 的落地代码版本选完、DLL 装完接下来才是真正干活的环节。我先把最常见的两张脸谱写出来一个是生成全新的 xlsx一个是读取老项目留下的 xls。这两段代码在 NPOI 1.2.5 里都能直接编译过也不依赖新版 API。后面再补样式、日期、列宽这些高频参数的调整方式。4.1 生成 xlsx最简创建工作簿与写盘代码老 NPOI 生成新 Excel 的标准步子是这样先 new 出一个 XSSFWorkbook再拿到 ISheet给行和单元格设置值最后用 FileStream 把工作簿写进文件。注意1.2.5 里 XSSFWorkbook 没有自带 Save 方法所有输出都是通过 workbook.Write(stream) 完成这一点和很多从旧版走过来的经验一致。// C# - 使用 NPOI 1.2.5 生成 xlsx using NPOI.SS.UserModel; using NPOI.XSSF.UserModel; using System.IO; var workbook new XSSFWorkbook(); // 1.2.5 默认构造函数 ISheet sheet workbook.CreateSheet(出货单); IRow header sheet.CreateRow(0); // 第一行是表头 ICell cell header.CreateCell(0); cell.SetCellValue(订单号); // 第二行写数据 IRow row sheet.CreateRow(1); row.CreateCell(0).SetCellValue(SO-2024-001); row.CreateCell(1).SetCellValue(上海仓); // 中文直接 write不用手动转码 using (var fs new FileStream(D:\out\出货单.xlsx, FileMode.Create, FileAccess.Write)) { workbook.Write(fs); // 关键一步写流不是写文件路径 }这段代码有两个容易看漏的细节一是 CreateRow 和 CreateCell 的行列索引都是从 0 开始如果你习惯从 1 数导出的表头会跑到第二行。二是 workbook.Write(fs) 之后原始 FileStream 如果被提前 closexlsx 文件很可能是一个只有 0 字节或者半截的空壳。我用 using 包住 FileStream就是让流在 Write 之后再释放。参数说明一下CreateSheet 的参数是工作表标签名标签可以重名但最好保持唯一否则 Excel 打开时会提示这里的路径如果目录不存在FileStream 会直接抛异常这不是 NPOI 的锅是操作系统不给写。另外补充一个常见误用有人会把 workbook.Write(fs) 写成 workbook.Write(new MemoryStream())然后把 MemoryStream 写成文件多绕了一圈还给大文件带来翻倍的内存开销。直接 FileStream 写磁盘就行。1.2.5 的 XSSFWorkbook 类位于 NPOI.XSSF.UserModel而 ISheet、IRow、ICell 这些接口在 NPOI.SS.UserModel 里。如果你的项目里同时引用了 HSSF 和 XSSF别用别名混用接口统一走 SS.UserModel 最稳。4.2 读取 xls老版本 HSSF 的兼容路径处理老系统遗留下来的 xls 文件是 NPOI 1.2.5 的看家本领。HSSF 对应的就是 Excel 2003 的二进制格式读取代码比生成还要短但有一个绕不开的坑单元格类型必须一层层判断不能上来就调 StringCellValue。// C# - 用 HSSFWorkbook 读取 xls using NPOI.HSSF.UserModel; using NPOI.SS.UserModel; using System.IO; using (var fs new FileStream(D:\in\历史订单.xls, FileMode.Open, FileAccess.Read, FileShare.Read)) { var workbook new HSSFWorkbook(fs); ISheet sheet workbook.GetSheetAt(0); IRow row sheet.GetRow(0); if (row ! null) { ICell cell row.GetCell(0); string value; switch (cell.CellType) { case CellType.STRING: value cell.StringCellValue; break; case CellType.NUMERIC: value cell.NumericCellValue.ToString(); break; default: value cell.ToString(); break; } } }这段代码给你拦下了一个最常见的翻车点如果单元格是数字类型你硬调 StringCellValue 会直接抛 InvalidOperationException。所以 switch 判断 CellType是每个用 NPOI 读格子的人都必须养成的习惯。FileShare.Read 是为了防止文件被别的进程占用之后导致读取失败老服务器上的财务文件经常被另一个 Excel 进程拽着不放。GetSheetAt(0) 拿的是第一个工作表如果文件里表顺序不固定最好用 workbook.GetSheet(Sheet1) 这种按名取表的方式表名通常比位置更可靠。如果你读取的是 xlsx 而不是 xls只需要把 HSSFWorkbook 换成 XSSFWorkbook其余接口一致。这个替换看起来简单但有一个前提xlsx 本质是 zip 包如果你遇到的是一个被其它程序改坏后缀的 xls用 XSSFWorkbook 会报“无效的压缩文件”这时候别纠结先确认原文件真实格式。4.3 常用 API 参数样式、日期、列宽和公式这样调才稳上面两段代码能跑通基础读写但你实际交付给业务部门时经常会要求“加个颜色、日期显示成 yyyy-MM-dd、列宽别挤在一起”。这里我把高频参数集中过一遍。// C# - 样式与常用参数 using NPOI.SS.UserModel; using NPOI.XSSF.UserModel; var workbook new XSSFWorkbook(); ISheet sheet workbook.CreateSheet(样式示例); sheet.SetColumnWidth(0, 10 * 256); // 列宽单位是字符宽度的1/25610表示约10个字符 ICellStyle style workbook.CreateCellStyle(); style.BorderBottom BorderStyle.THIN; // 底部边框 style.DataFormat BuiltinFormats.GetBuiltinFormat(yyyy/m/d); // 1.2.5 中日期格式可以直接指定但需要配合单元格 SetCellValue(DateTime) IRow row sheet.CreateRow(0); ICell cell row.CreateCell(0); cell.SetCellValue(new DateTime(2024, 5, 18)); cell.CellStyle style; // 公式 ICell total sheet.CreateRow(1).CreateCell(0); total.SetCellFormula(SUM(A2:A10));列宽这里有一个单位上的习惯SetColumnWidth 的第一个参数是列索引第二个参数的单位是 1/256 个字符。10 * 256 就是大约 10 个字符的宽度如果直接填 10你会发现列宽窄到看不见。DataFormat 如果想显示成“yyyy-MM-dd”直接用 NPOI 内置格式并不总有对应常量我一般就写成 BuiltinFormats.GetBuiltinFormat(yyyy/m/d)有些版本认这种写法。公式设置成 SetCellFormula导出的文件里公式也保留Excel 打开会重新计算。注意 1.2.5 对公式函数名的支持没有新版全遇到不识别的情况先看是不是函数名拼写差异。字体和背景色也是高频需求但老版本里颜色枚举和 CSS 习惯完全不一样BorderStyle.THIN 只是边框粗细的一种。我给你的建议是在做复杂样式前先在一个临时文件里把样式跑通再用到真实数据上别在业务代码里试错那样排查起来既慢又容易误伤数据。5. NPOI 1.25 避坑现场五个最容易翻车的问题与排查方法前面把正常路径跑通了这一章把我在支持各类项目时见过的坑集中写出来。每一条都是“现象、原因、解决”的结构方便你排查的时候直接按症状定位。这些不是玄学都是能复现的现场。5.1 复制 DLL 后运行就报程序集加载失败现象项目编译没问题一运行就抛 FileLoadException 或者“未能加载文件或程序集 ICSharpCode.SharpZipLib”。原因只把 NPOI.dll 放进了输出目录压缩包里其他依赖没有被复制或者你从别的项目复制了一个统一命名的 SharpZipLib 高版本程序集签名对不上。解决回到压缩包把 lib 目录整体复制进项目并确认输出目录里有 NPOI.dll、log4net.dll、ICSharpCode.SharpZipLib.dll。如果项目里已有 log4net比较它的版本和 NPOI 需要的版本不一致时优先做绑定重定向而不是替换 DLL。5.2 生成的文件打开提示损坏Excel 要修复现象代码跑完没报错Excel 打开时提示“文件格式和扩展名不匹配”或直接要求修复。原因最常见的是用 HSSFWorkbook 生成了 xlsx 后缀的文件或者 workbook.Write 之后没有 flush/close 就继续写其他内容导致文件尾部被截断。解决严格匹配工作簿类型和扩展名xlsx 用 XSSFWorkbookxls 用 HSSFWorkbook把 FileStream 的 using 范围扩大到 Write 结束别让流提前释放。还有一招写完后用压缩工具打开生成的 xlsx如果能看到里面没有规范目录结构基本就是类型搞混了。5.3 单元格显示长数字变科学计数法靠文本格式救不回来现象订单号存进去是 18 位数字Excel 打开变成 3.02014E17设置单元格格式也没用。原因业务把它当文本但 Excel 打开时会自动尝试把字符串识别成数字并转科学计数法。解决显式把单元格格式设为文本也就是 DataFormat 设为 并且用 StringCellValue 写入完整业务编号。还有一个土办法在字符串前面加一个制表符Excel 会把它当文本处理但这样会污染数据不太推荐。处理 ERP 单号时这个坑几乎是必踩导完立刻肉眼检查一行最稳妥。5.4 同项目撞版本NPOI 1.2.5 和 NPOI 2.x 冲突现象项目里本来有一个组件带了 NPOI 2.x你引 1.2.5 后编译时各种类型不匹配运行时更可能报“发现同一程序集的不同版本”。原因1.2.5 和 2.x 程序集名称一样很多类型签名不同程序集加载器无法区分。解决如果新组件必须用新版就把老代码统一升到 2.x如果没得选为 2.x 组件做隔离或者单独建一个服务进程调用。站在项目全局看两个版本共存是成本最高的一条路不如花两个晚上升级。以后再看到一个项目里同时出现两个版本第一反应应该是“这里迟早要出事”。5.5 导出大文件内存暴涨挂掉前没有任何日志现象导出 5 万行的 xlsx内存飙到 1GB 以上开始出现 OutOfMemoryException日志里什么都没有。原因1.2.5 的 XSSFWorkbook 在工作簿未关闭前把每一行、每个单元格都保存在内存对象模型里行数越大吃内存越离谱。解决先明确业务上是否真的需要 xlsx如果只是后端导出给财务改成 CSV 也是出路如果一定要 xlsx就升级到带 SXSSFWorkbook 的新版用流式写入控制单行驻留内存。这个坑验证了一件事老版本省了维护成本新的需求早晚会把它逼到墙角。6. 验证导出结果再决定要不要升到新版一个收敛的进阶路径到了最后我还是建议你不要停在“能生成文件”的层面。交付前用程序再读一遍自己生成的文件比肉眼打开看靠谱得多同时把要不要升新版的判断落在一个具体指标上。6.1 用数据对比脚本验证导出的行数和关键字段我有个习惯导出完立刻用 NPOI 自己读回来对比行数和几个关键字段全程自动化。// C# - 导出后自校验读回同一文件统计行数 using NPOI.XSSF.UserModel; using System.IO; using (var fs new FileStream(D:\out\出货单.xlsx, FileMode.Open, FileAccess.Read)) { var wb new XSSFWorkbook(fs); var sheet wb.GetSheetAt(0); int lastRow sheet.LastRowNum; string cellValue sheet.GetRow(1).GetCell(0)?.StringCellValue; Console.WriteLine($Rows: {lastRow}, FirstCell: {cellValue}); }对比脚本的价值在于把“看起来对不对”变成“数据对不对”。以前我总靠人眼打开文件抽查后来吃过一次亏漏了一列数据抽查的三行恰好都有值上线后业务才发现。从那以后我习惯在导出逻辑后顺手写一个校验断言至少卡住行数和主键字段。6.2 从 1.25 迁到新主线的三步替换法如果你已经动了升级的心别一步到位把整项目翻新。我常用的路线是第一步把 NPOI 升级到 2.x 里最接近当前 .NET Framework 的版本先解决编译报错。第二步逐个替换命名空间里被改名或移动的类比如部分流类型和对单元格样式枚举的写法。第三步把 XSSFWorkbook 替换成 SXSSFWorkbook 处理大文件再跑一遍上面那个自校验脚本。如果项目里只有 1000 行以内的小表、服务器也不准备动那继续守着 1.25 也没什么丢人的真正要警惕的是新需求一进来就要大文件、新框架那双旧鞋就会成为最大的瓶颈。这是我被老版本救过也坑过后总结出来的习惯——先锁定影响半径再决定是否换鞋。希望帮到你。本文还有配套的精品资源点击获取