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 管 .xls，XSSF 管 .xlsx，HWPF 管 .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 与新主线到底差在哪

光说不如一张表看得快，我把关键的差异按选型时关心的点列出来：

表格要结合场景读：如果你的服务器还是 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\ExportService，DLL 放在同盘 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 就选 net40，4.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 如果被提前 close，xlsx 文件很可能是一个只有 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/256，10表示约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 用 XSSFWorkbook，xls 用 HSSFWorkbook；把 FileStream 的 using 范围扩大到 Write 结束，别让流提前释放。还有一招，写完后用压缩工具打开生成的 xlsx，如果能看到里面没有规范目录结构，基本就是类型搞混了。

5.3 单元格显示长数字变科学计数法，靠文本格式救不回来

现象：订单号存进去是 18 位数字，Excel 打开变成 3.02014E+17，设置单元格格式也没用。原因：业务把它当文本，但 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 也没什么丢人的；真正要警惕的是，新需求一进来就要大文件、新框架，那双旧鞋就会成为最大的瓶颈。这是我被老版本救过也坑过后总结出来的习惯——先锁定影响半径，再决定是否换鞋。希望帮到你。

本文还有配套的精品资源，点击获取