简介：面向.NET开发者的一份C#结合NPOI操作Excel的实例包，适合需要处理.xls与.xlsx文件的初中级开发人员，也可作为项目内封装Excel工具类的参考。压缩包共15个文件，以12个dll依赖库、2个cs示例源码和1个xml配置为主，整体约2.19MB，可快速对照依赖组织与调用方式。已有6358人学习下载，说明其在Excel读写场景中具备一定参考价值。内容围绕工作簿创建、工作表与行列读写、单元格样式设置、文件保存以及不同Excel格式的兼容处理展开，并提供两套版本示例，便于比较接口差异与复用思路；读者可从中梳理NPOI的常用API、工具类封装方式和基础异常处理路径，减少在导入导出、报表生成等任务中的试错成本。
1. 后台报表绕不开的那张表，我用 NPOI 把它拆成了六个方法
运营每周上传一张门店销售表，系统解析入库，再把统计结果导出去，这类需求在 C# 后台里几乎躲不掉。很多人第一反应是装 Office 用 Interop，结果服务器上 EXCEL.EXE 杀不干净。C# NPOI 操作 Excel 这套组合的价值就在这里：不依赖 Office 安装环境，.xls和.xlsx共用一套IWorkbook接口，十万行也能流式写出去。这份例子把打开工作簿、按类型取值、反射映射成对象、样式复用、合并单元格与下拉框、大数据量导出拆成互相独立的方法，适合正在做报表导入导出、被日期格式和内存占用折腾过的 .NET 开发者照着抄。
2. 技术选型与工程骨架：HSSF、XSSF、SXSSF 三套实现怎么分工
NPOI 内部并不是一个工作簿类包打天下，而是按文件格式分了三套：HSSFWorkbook对应 BIFF8 的.xls，XSSFWorkbook对应 OOXML 的.xlsx，SXSSFWorkbook是 XSSF 的流式写版本。它们都实现了IWorkbook、ISheet、IRow、ICell这组接口，所以业务代码只要面向接口写，格式差异就能被挡在工厂方法后面。这一章先把选型理由和工程骨架定下来，后面几章的读写代码才有地方放。
2.1 为什么这套例子不用 Interop、OleDb 和 OpenXML SDK
Interop 是最像“人在操作 Excel”的方案，录制宏再翻译成 C# 几乎不用思考。代价也很直接：服务器必须装 Office，进程里容易残留 EXCEL.EXE，IIS 应用池身份一收紧就报权限错误。我在一个定时任务里见过这种写法，跑三天之后任务管理器里堆了四十多个隐藏进程，机器内存一路涨——这种翻车不是配置能救的，是方案本身不适合服务端。
OleDb 走的是数据库思路，把 Sheet 当表来查。读还行，写几乎没法用，还要在目标机器上配对应位数的驱动，32 位和 64 位不匹配时报的错还特别模糊。OpenXML SDK 是官方的 OOXML 实现，规范严谨，但代码啰嗦得厉害，写一个单元格要 new 一串对象，而且它只认.xlsx，老系统导出的.xls完全不支持。
NPOI 的定位正好卡在中间。它把 Java 那套 POI 移植过来，读取、写入、样式、公式、数据验证都有对应 API，纯托管实现，容器里不用装 Office。前些年另一个同类开源库改了授权协议之后，不少团队又迁回 NPOI，生态和文档也就更全了。
| 方案 | 运行依赖 | 支持格式 | 主要问题 |
|---|---|---|---|
| Interop | 必须安装 Office | xls / xlsx | 进程残留、权限敏感、不适合 Web |
| OleDb | 需要对应位数驱动 | 以 xls 为主 | 只能读、写入能力弱、类型靠猜 |
| OpenXML SDK | 无 | 仅 xlsx | API 偏底层、不支持老格式 |
| NPOI HSSF / XSSF | 无 | xls / xlsx | 全量加载，大文件吃内存 |
| NPOI SXSSF | 无 | 仅 xlsx | 只能写不能读，需要清理临时文件 |
2.2 依赖引入与目录结构
建工程的部分没什么玄学，两个项目就够：一个类库放封装，一个控制台负责跑例子验证。NPOI 通过 NuGet 装，一个包里面已经包含了 HSSF、XSSF、SXSSF 三套实现，不需要额外引用别的包。
# 解决方案 + 类库 + 控制台示例 dotnet new sln -n ExcelKit dotnet new classlib -o src/ExcelKit.Core -f net8.0 dotnet new console -o src/ExcelKit.Demo -f net8.0 dotnet sln add src/ExcelKit.Core src/ExcelKit.Demo # 示例项目引用类库，类库引用 NPOI dotnet add src/ExcelKit.Demo reference src/ExcelKit.Core dotnet add src/ExcelKit.Core package NPOI-f net8.0换成你手上的 LTS 版本即可，NPOI 对框架版本不挑。装完之后目录我一般这么切，读和写分开，转换逻辑单独抽出来，这样后面加csv导出或者换别的库都不会牵一发动全身：
ExcelKit/ ├── ExcelKit.sln ├── src/ │ ├── ExcelKit.Core/ │ │ ├── Abstractions/ExcelOptions.cs # 表头行、起始行、是否跳过空行 │ │ ├── Attributes/ExcelColumnAttribute.cs # 列名和属性的映射 │ │ ├── Internal/CellValueConverter.cs # 原始值到 CLR 类型的转换 │ │ ├── Internal/StyleCache.cs # 样式缓存，避免超上限 │ │ ├── Reading/ExcelReader.cs # 打开、遍历、反射赋值 │ │ ├── Writing/ExcelWriter.cs # xls / xlsx 常规导出 │ │ └── Writing/SxssfExcelWriter.cs # 大数据量流式导出 │ └── ExcelKit.Demo/ │ ├── Program.cs │ ├── Models/OrderRow.cs │ └── samples/ # 放测试用的 xls、xlsx| 文件 | 职责 | 关键点 |
|---|---|---|
ExcelOptions.cs | 表头行号、数据起始行、空行策略 | 不同来源的表头位置经常不一样 |
ExcelColumnAttribute.cs | 列名到属性的映射 | 表头改名不影响实体 |
CellValueConverter.cs | 日期、数字、布尔、枚举的转换 | 所有类型判断集中在一处 |
ExcelReader.cs | 读工作簿并映射成List<T> | 处理空行、空单元格 |
ExcelWriter.cs | 常规导出、样式、合并、下拉 | 样式必须缓存复用 |
SxssfExcelWriter.cs | 十万行级导出 | Dispose负责清临时文件 |
2.3 一个能跑通的最小闭环
在拆细节之前，先让读写跑通一次，确认包引用没问题。下面这段是示例项目里Program.cs的核心，负责按扩展名创建工作簿、保存、再打开读回来：
using NPOI.HSSF.UserModel; using NPOI.SS.UserModel; using NPOI.XSSF.UserModel; // 按扩展名选择实现：.xls 走 HSSF，.xlsx 走 XSSF static IWorkbook CreateWorkbook(string path) { var ext = Path.GetExtension(path).ToLowerInvariant(); return ext switch { ".xls" => new HSSFWorkbook(), // BIFF8，最多 65536 行、256 列 ".xlsx" => new XSSFWorkbook(), // OOXML，最多 1048576 行 _ => throw new NotSupportedException($"不支持的扩展名: {ext}") }; } // 先写临时文件再替换，避免目标文件被占用时把原文件写坏 static void SaveWorkbook(IWorkbook workbook, string path) { var tmp = path + ".tmp"; using (var fs = new FileStream(tmp, FileMode.Create, FileAccess.Write)) { workbook.Write(fs); // Write 不会替你关闭传入的流 fs.Flush(); } File.Move(tmp, path, overwrite: true); } // 打开时交给工厂方法读文件头自动判断格式 static IWorkbook OpenWorkbook(string path) => WorkbookFactory.Create(File.OpenRead(path));CreateWorkbook的意义在于把“用哪套实现”这件事收敛到一个地方，业务代码只拿到IWorkbook。SaveWorkbook里那个临时文件加File.Move的写法是血泪经验：目标文件正被 Excel 打开时，直接FileMode.Create会抛IOException，更糟的是有些情况下文件被截断了才失败，用户拿到一个打不开的 xlsx。走临时文件至少保证原文件完好。
WorkbookFactory.Create接受流，它自己读魔数判断是 BIFF 还是 ZIP 包，所以读取端完全不用关心扩展名——顺带说一句，用户把.xlsx改成.xls传上来的情况真有，工厂方法能兜住，按扩展名判断的写法就翻车了。
提示：
WorkbookFactory.Create(Stream)之后不要立刻把流 Dispose 掉，工作簿内部还引用着它，后续操作可能报“无法访问已关闭的流”。
3. 读取链路拆解：从工作簿到单元格，把 Excel 当半结构化数据源
读取看着简单，实际是坑最集中的一段。Excel 不是数据库，没有列类型，单元格里存的可能是文本、可能是数字、可能是公式，日期还是个伪装成数字的 double。这一章按“定位 Sheet → 取值 → 映射成对象”三步走，每一步都给可直接用的代码。
3.1 定位 Sheet 与遍历有效行
第一步是把 Sheet 拿到手。用户传上来的文件里常有隐藏 Sheet、说明页、汇总页，按名字取最稳，取不到再退回第一个：
// 名字优先；名字为空或找不到时退回第一个 Sheet public static ISheet GetSheet(IWorkbook wb, string? name) => (string.IsNullOrWhiteSpace(name) ? null : wb.GetSheet(name)) ?? wb.GetSheetAt(0);遍历行的时候有两个属性容易混：LastRowNum是最后一行的索引（0 基，空表返回 -1），PhysicalNumberOfRows是实际有内容的行数。很多人拿PhysicalNumberOfRows当循环上界，遇到中间夹了空行就少读一截。正确姿势是用FirstRowNum到LastRowNum闭区间遍历，然后对每一行判空：
var sheet = GetSheet(wb, "明细"); if (sheet.PhysicalNumberOfRows == 0) return new List<OrderRow>(); var first = sheet.FirstRowNum; // 通常就是表头行 var last = sheet.LastRowNum; // 注意：被格式化过的空行也会算进来 for (var r = first + 1; r <= last; r++) { var row = sheet.GetRow(r); // 越界或没内容的行会返回 null if (row is null) continue; // ... 逐格取值 }GetRow返回 null 这件事必须处理，LastRowNum会把“只设过格式没填过值”的行也算进去，表格末尾拖了一片带边框的空行是常态。不加判空，线上就会收到一堆NullReferenceException，堆栈还指在业务代码里，排查起来像个黑匣子。
3.2 单元格取值：类型分支是绕不过去的
ICell的CellType决定了你能调哪个属性。对着一个文本单元格取NumericCellValue，抛的是InvalidOperationException，消息还只告诉你类型不对。更麻烦的是公式单元格：它的CellType是Formula，真实结果藏在CachedFormulaResultType里，得先看缓存类型再决定怎么取。
public static object? GetValue(ICell? cell) { if (cell is null) return null; // 公式单元格不能直接按 CellType 分支，要先看缓存结果的类型 var type = cell.CellType == CellType.Formula ? cell.CachedFormulaResultType : cell.CellType; switch (type) { case CellType.String: return cell.StringCellValue; case CellType.Boolean: return cell.BooleanCellValue; case CellType.Numeric: // 日期在文件里就是个 double，只能靠单元格格式判断 return DateUtil.IsCellDateFormatted(cell) ? DateUtil.GetJavaDate(cell.NumericCellValue) : cell.NumericCellValue; case CellType.Blank: return null; case CellType.Error: // #DIV/0!、#N/A 这类错误值，转成字符串保留原始信息 return FormulaError.ForInt(cell.ErrorCellValue).String; default: return cell.ToString(); } }DateUtil.IsCellDateFormatted判断的是单元格的显示格式，不是值本身——同样是45000，格式是日期就是 2023 年某天，格式是常规就还是个数字。这个判断一定要在取NumericCellValue之前做，反过来先取值再判断，得到的已经是 double 了，没有格式信息可查。
DateUtil.GetJavaDate名字里带 Java 是历史遗留，返回的是 .NET 的DateTime，直接用就行。它按 1900 日期系统换算，Excel 那个“1900 年不是闰年”的历史 bug NPOI 已经处理了，不用自己补一天。
如果只是要把内容原样展示（比如做预览），还有个更省事的办法：new DataFormatter().FormatCellValue(cell)，它按单元格格式渲染成字符串，0.00%、¥#,##0.00这些格式都能还原。缺点是拿到的是字符串，后续做数值计算还得再转一次，我一般只在日志和预览里用。
3.3 反射映射成对象：让表头变化不影响实体
逐格GetValue再手写赋值，字段一多就容易错位。用一个特性标出列名，读取时按表头建索引，属性顺序调整、中间插列都不会影响结果：
[AttributeUsage(AttributeTargets.Property)] public sealed class ExcelColumnAttribute : Attribute { public ExcelColumnAttribute(string header) => Header = header; public string Header { get; } public bool Required { get; init; } } public sealed class OrderRow { [ExcelColumn("门店名称", Required = true)] public string StoreName { get; set; } = ""; [ExcelColumn("订单日期")] public DateTime OrderDate { get; set; } [ExcelColumn("金额")] public decimal Amount { get; set; } [ExcelColumn("状态")] public string? Status { get; set; } }映射逻辑本身不复杂，难点在容错：表头可能有空格、可能有合并单元格留下的空列、类型转换可能失败。
public static List<T> ReadSheet<T>(ISheet sheet, ExcelOptions options) where T : new() { var headerRow = sheet.GetRow(options.HeaderRowIndex) ?? throw new InvalidDataException("表头行不存在"); // 列索引 -> 属性，忽略表头里的空白列 var map = new Dictionary<int, PropertyInfo>(); for (var c = headerRow.FirstCellNum; c < headerRow.LastCellNum; c++) { var header = GetValue(headerRow.GetCell(c))?.ToString()?.Trim(); if (string.IsNullOrEmpty(header)) continue; var prop = typeof(T).GetProperties() .FirstOrDefault(p => p.GetCustomAttribute<ExcelColumnAttribute>()?.Header == header); if (prop is not null) map[c] = prop; } var list = new List<T>(); for (var r = options.DataStartRowIndex; r <= sheet.LastRowNum; r++) { var row = sheet.GetRow(r); if (row is null) continue; var item = new T(); var hasValue = false; foreach (var (col, prop) in map) { var raw = GetValue(row.GetCell(col, MissingCellPolicy.CREATE_NULL_AS_BLANK)); if (raw is null || raw is string s && s.Length == 0) continue; prop.SetValue(item, CellValueConverter.Convert(raw, prop.PropertyType)); hasValue = true; } if (hasValue) list.Add(item); // 整行全空就丢掉 } return list; }几个参数值得说：MissingCellPolicy.CREATE_NULL_AS_BLANK让不存在的单元格返回一个 Blank 单元格而不是 null，省掉一层判空；options.HeaderRowIndex和DataStartRowIndex分开配置，是因为有些模板第一行是大标题、第二行才是表头。
Convert方法里要处理Nullable<T>、枚举、decimal的InvariantCulture转换。金额字段最容易出事：源文件里是1234.56，服务器区域设置是德语，Convert.ToDecimal会把点当千分位，读出 123456。统一用CultureInfo.InvariantCulture转换，能省掉一大半“数据对不上”的工单。
4. 写入与导出：样式缓存、合并单元格和十万行的流式写法
写比读更容易埋雷，因为很多问题不会当场报错，而是等用户用 Excel 打开时才提示“发现不可读取的内容”。这一章按常规导出、表头样式与交互元素、大数据量三条线拆，重点讲样式复用和 SXSSF 的窗口机制。
4.1 样式缓存：别在循环里 CreateCellStyle
NPOI 的ICellStyle是工作簿级别的对象，每个工作簿能创建的样式数量有上限，.xls是 4000 左右，.xlsx是 64000。你写row.CreateCell(0).CellStyle = wb.CreateCellStyle()放在一万行的循环里，前几千行没问题，后面直接抛异常，报错信息还只说“样式数量超出限制”。字体同理，CreateFont也是有限额的。
正确做法是按用途缓存，整个工作簿复用同一份：
public sealed class StyleCache { private readonly IWorkbook _wb; private readonly Dictionary<string, ICellStyle> _cache = new(); public StyleCache(IWorkbook wb) => _wb = wb; public ICellStyle GetHeaderStyle() { if (_cache.TryGetValue("header", out var cached)) return cached; var style = _wb.CreateCellStyle(); style.Alignment = HorizontalAlignment.Center; style.VerticalAlignment = VerticalAlignment.Center; style.FillForegroundColor = IndexedColors.Grey25Percent.Index; style.FillPattern = FillPattern.SolidForeground; style.BorderBottom = BorderStyle.Thin; style.WrapText = true; var font = _wb.CreateFont(); font.IsBold = true; font.FontHeightInPoints = 11; style.SetFont(font); _cache["header"] = style; return style; } public ICellStyle GetDateStyle() { if (_cache.TryGetValue("date", out var cached)) return cached; var style = _wb.CreateCellStyle(); style.DataFormat = _wb.CreateDataFormat().GetFormat("yyyy-mm-dd"); _cache["date"] = style; return style; } }DataFormat那段也值得单独拎出来：日期列如果不设格式，写进去的DateTime打开后显示成一串45123，用户第一反应是系统坏了。CreateDataFormat().GetFormat(...)返回的是格式索引，同一个格式字符串重复调用会得到同一个索引，所以缓存不是强制的，但样式对象必须缓存。
4.2 合并单元格、冻结窗格、下拉框与公式
报表类导出的“专业感”基本靠这几样堆出来：标题行合并居中、表头冻结、状态列给下拉框、合计行用公式。这些 API 在 HSSF 和 XSSF 上是同一套接口，只有底层实现不同，所以代码不用分叉。
var sheet = wb.CreateSheet("明细"); // 第一行放大标题，合并 A1:F1 var titleRow = sheet.CreateRow(0); titleRow.CreateCell(0).SetCellValue("门店销售明细"); sheet.AddMergedRegion(new CellRangeAddress(0, 0, 0, 5)); // 首行, 末行, 首列, 末列 // 冻结前两行，横向滚动时列头还在 sheet.CreateFreezePane(0, 2); // 状态列给下拉框，范围到第 5000 行 var helper = sheet.GetDataValidationHelper(); var constraint = helper.CreateExplicitListConstraint(new[] { "待审核", "已审核", "已驳回" }); var validation = helper.CreateValidation(constraint, new CellRangeAddressList(2, 5000, 5, 5)); validation.ShowErrorBox = true; validation.CreateErrorBox("取值不合法", "请从下拉列表里选择状态"); sheet.AddValidationData(validation); // 合计行走公式，让 Excel 自己算，比在服务端算好再写死更灵活 var totalRow = sheet.CreateRow(sheet.LastRowNum + 1); totalRow.CreateCell(0).SetCellValue("合计"); totalRow.CreateCell(3).SetCellFormula($"SUM(D3:D{totalRow.RowNum})");CellRangeAddress的参数顺序是行在前、列在后，四个值分别是首行、末行、首列、末列，全部 0 基。合并时如果只写了左上角单元格的值，其余单元格留空，某些版本的 Excel 打开会警告，稳妥做法是给合并区域每个格子都建出来再设值。
公式单元格写进去之后，CachedFormulaResultType在你这边是空的——NPOI 不做计算。所以别的系统读这个文件时如果直接取缓存值，拿到的是 0 或者空。要么在服务端算好写成值，要么在文件打开时让 Excel 重算一次（设置wb.ForceFormulaRecalculation = true就能让 Excel 打开时算一遍）。
注意：
CreateFreezePane(0, 2)的第一个参数是冻结的列数，传 0 表示只冻行，别把行列顺序记反了。
4.3 SXSSF 流式导出：十万行不该进内存
XSSFWorkbook是全内存模型，一行十列，十万行大概要吃掉几百兆，加上 GC 压力，服务器上很容易直接 OOM。SXSSFWorkbook的思路是滑动窗口：内存里只保留最近 N 行，超出的部分刷到临时文件，最后合并成一个 xlsx 包。窗口大小在构造函数里指定：
public void ExportLarge(string path, IEnumerable<OrderRow> rows, int window = 500) { // window 是内存中保留的行数，超过就刷到磁盘临时文件 using var wb = new SXSSFWorkbook(window); // Dispose 时会删掉临时文件 wb.CompressTemporaryFiles = true; var sheet = wb.CreateSheet("明细"); var styles = new StyleCache(wb); var headerStyle = styles.GetHeaderStyle(); var dateStyle = styles.GetDateStyle(); var r = 0; var header = sheet.CreateRow(r++); string[] headers = { "门店名称", "订单日期", "金额", "状态" }; for (var c = 0; c < headers.Length; c++) { var cell = header.CreateCell(c); cell.SetCellValue(headers[c]); cell.CellStyle = headerStyle; } foreach (var item in rows) { var row = sheet.CreateRow(r++); row.CreateCell(0).SetCellValue(item.StoreName); var dateCell = row.CreateCell(1); dateCell.SetCellValue(item.OrderDate); dateCell.CellStyle = dateStyle; // 日期列套格式，否则显示成数字 row.CreateCell(2).SetCellValue((double)item.Amount); row.CreateCell(3).SetCellValue(item.Status ?? ""); } using var fs = new FileStream(path, FileMode.Create, FileAccess.Write); wb.Write(fs); }窗口大小不是越大越好。设成 500，内存里最多五百行，临时文件会多一点；设成 50000，内存优势就不明显了。我一般按单行宽度估：十列左右的表，500 到 1000 是比较平衡的值。
using那句不能省。SXSSFWorkbook在%TEMP%下建临时文件，只有Dispose才会清理。少写一个using，跑一周之后磁盘告警，DBA 找过来你还得先解释这不是日志文件。另外 SXSSF 只能写不能读，AutoSizeColumn也只在设置了TrackAllColumnsForAutoSizing之后才有意义，宽表上还特别慢，我一般直接按内容估算列宽写死。
5. 避坑与排查：NPOI 上线后必然撞上的 5 个问题
下面五条都是踩过之后写进回归用例的，遇到报错别急着搜异常消息，先按现象对一遍。
5.1 报“文件正由另一进程使用”或读出来是空表
现象：导出时抛IOException: The process cannot access the file，或者读文件时PhysicalNumberOfRows是 0，但用 Excel 打开明明有数据。
原因：写路径上目标文件正被 Excel 或预览服务打开；读路径上是File.OpenRead之后又用using提前释放了流，WorkbookFactory.Create内部还引用着它，读到一半拿到空数据。
解决：写走临时文件加File.Move(tmp, path, overwrite: true)；读的时候让流的生命周期覆盖工作簿的整个使用期，要么不用using，要么改成先把整个文件读进MemoryStream再创建。上传接口还有个常见原因：前端传的是 0 字节文件，Length == 0直接拦掉，别让它走到 NPOI 里。
5.2 日期读成 45000 多，金额多出几位小数
现象：OrderDate字段全是45123这种数字；金额1234.56读成123456，或者变成1234.5600000000001。
原因：日期在 xlsx 里本来就是个 double，没走DateUtil.IsCellDateFormatted判断就当成普通数字返回了；金额问题一半来自double的二进制精度，一半来自区域设置——服务器用逗号做小数点时，decimal.Parse会按当地习惯解析。
解决：取值前先判日期格式；金额一律Convert.ToDecimal(raw, CultureInfo.InvariantCulture)，实体里的金额字段用decimal不用double。反方向导出时也一样，写double进去再读出来对比，最后一位对不上就是精度问题。
5.3 十万行导出内存飙升，进程被 OOM 杀掉
现象：导出任务跑到一半容器重启，日志里没有任何异常堆栈，只有一条退出码。
原因：用了XSSFWorkbook全量加载，每行每格都是完整对象，十万行轻松几百兆；叠加并发导出，内存直接顶到容器上限。
解决：超过两万行走SXSSFWorkbook，窗口设 500 到 1000；同时限制并发导出数量（用信号量控制在两三个），导出任务改成后台队列加下载链接，别让用户点一下就在请求线程里同步跑完。另外注意SXSSFWorkbook的临时文件目录，容器里/tmp默认可能只有几百兆。
5.4 样式超出上限，或者 Excel 打开提示“发现不可读取的内容”
现象：小数据量导出正常，行数一多就抛样式超限异常；或者文件能生成，用 Excel 打开弹修复提示。
原因：循环里CreateCellStyle没有复用；修复提示多半是合并区域和已有数据重叠、Sheet 名超过 31 个字符、或者.xls里用了只有.xlsx支持的写法。
解决：样式统一走缓存类，字体也一样；写之前校验 Sheet 名长度和非法字符（[]:*?/\）；.xls导出时把行数控制在 65536 以内，超了直接给用户提示换 xlsx，别等HSSFWorkbook写到一半抛异常。
5.5 容器里 AutoSizeColumn 抛异常或整列宽度变成 0
现象：本地 Windows 跑得好好的，部署到 Linux 容器后AutoSizeColumn抛异常，或者列宽全变成默认值。
原因：自动列宽需要测量文字渲染宽度，较新的 NPOI 用纯托管的字体库，容器镜像里没装对应字体就测不出来；用老版本的话还会依赖系统图形库，Linux 上直接报libgdiplus找不到。
解决：镜像里装一套基础字体（比如开源的中文字体包）；或者干脆放弃自动宽度，按列的字符数手动SetColumnWidth(c, Math.Min(255, maxLen * 256))，稳定又不受环境影响。
6. 二次开发：把散落各处的 NPOI 调用收成一个导出服务
接手过的几个项目里，NPOI 的调用最后都会散成一地：A 类里一个new XSSFWorkbook()，B 服务里又一份样式代码，C 接口为了加一列改了三处。改造方向很明确——只暴露一个IExcelService，入参是数据集合和一个配置对象，出参是byte[]或临时文件路径，业务层不该出现ICell、ICellStyle这些类型。
public interface IExcelService { byte[] Export<T>(IReadOnlyList<T> data, ExcelExportOptions? options = null); List<T> Import<T>(Stream stream, ExcelOptions? options = null) where T : new(); }实现里把前面几章的东西拼起来：ExcelExportOptions带上格式（xls / xlsx）、Sheet 名、是否冻结表头、列宽策略；导出时按数据量自动切XSSFWorkbook和SXSSFWorkbook；列定义全部来自ExcelColumnAttribute，加字段不用改导出代码。改造前后差别很明显：
| 改造前 | 改造后 |
|---|---|
| 每个接口各写一份样式 | 样式只在StyleCache里定义一次 |
| 加一列改三处代码 | 实体加个特性即可 |
| 数据量一大就 OOM | 按行数自动走 SXSSF |
| 表头改名导致导入失败 | 按列名匹配，找不到列直接报错并指出列名 |
验证方法我一般用金标准对比：准备一份人工核对过的样本表，跑导入后序列化成 JSON 存进仓库，作为回归基线；导出则把生成的文件再读回来，逐格对比关键字段。这样做的好处是日期格式、空行、合并单元格这些玄学问题都能被自动兜住，而不是等运营反馈。
改的时候有个技巧：先别动业务代码，在原来的调用点上加一层IExcelService适配，用旧逻辑实现接口，跑通之后再换内部实现。这样出问题时能立刻切回去，不用回滚整个分支。
从那以后我每次接报表需求，都先把表头、空行、日期格式这三件事写成回归用例再动手，比事后加班查数据对不上划算多了。希望帮到你。
本文还有配套的精品资源，点击获取
