简介面向ASP.NET Core WebAPI开发者的Excel处理工具包基于EPPlus与ExcelDataReader两大开源库解决Web应用中Excel读取、导出及避免服务器安装Office的常见需求适用于需要构建数据导入导出接口的中高级.NET后端工程师。压缩包共208个文件约21.89MB内含Visual Studio解决方案与项目源码.cs、.csproj、.sln以及配套的dll运行库、json配置文件等其中dll为EPPlus、ExcelDataReader等依赖程序集cs为控制器与业务逻辑示例json为应用配置整体是一个可直接打开运行的完整WebAPI项目。已有400人学习下载资源提供从文件流创建、读取Excel行数据到生成xlsx并返回客户端的完整代码路径涵盖流式处理、MIME类型与Content-Disposition响应头设置、内存高效利用等要点并包含上传校验、分批处理等扩展思路可帮助开发者快速集成Excel功能并规避常见坑点。1. Excel 读写这件小事为什么 Web API 里最容易翻车的反而是它用 ASP.NET Core Web API 做订单管理后台时Excel 导入导出一开始被当成边角料功能排期永远在最后。结果上线第一周翻车最多的恰恰是它EPPlus 导出的文件在 WPS 里打开提示格式异常ExcelDataReader 读老系统导出的 .xls 文件全是乱码两万行订单导出让进程内存一路飙到 600MB。后来我把这套 excel-handler 方案拆出来重做原则很简单导出统一走 EPPlus导入统一走 ExcelDataReader。它解决的不是「能不能读写」这种入门问题而是服务端批量读写时的真实边界内存流怎么给才不损坏文件、中文文件名响应头怎么写、老格式编码怎么注册、日期序列号怎么转换、大数据量怎么控内存。适合正在做管理后台、报表模块或数据导入功能的 ASP.NET Core 开发者尤其是被 Excel 兼容性问题坑过、想找一份能直接照抄参考实现的人。2. 选型与架构EPPlus 和 ExcelDataReader 一个写一个读边界在哪2.1 两个库的定位导出与解析各管一段先说结论能用 EPPlus 写就不拿它读能用 ExcelDataReader 读就不拿它写。这两条边界在 excel-handler 里是强制的因为这俩库的擅长方向天然互补硬要一个库干两件事迟早要在某个数据量级上吃亏。EPPlus 的主场是写。单元格样式、合并、公式、图表、模板填充这些导出链路里高频用到的能力它的 API 设计最顺手。但它的读取能力相对弱读操作会把整个工作表一次性载入内存文件稍大就吃不消而且 EPPlus 5.x 起改了授权模式非商业场景必须显式设置 LicenseContext商业场景要严格按授权要求购买。选型时这一条要先确认清楚别等代码写完才想起来。ExcelDataReader 的主场是读。它按流式逐行解析文件不会把整个 Excel 一次性塞进内存同时支持 .xls 和 .xlsx 两种格式老系统的二进制 BIFF 文件也能解。缺点是完全没有写能力定位就是纯解析器。把 ExcelDataReader 读出来的 DataSet 再写回 Excel得自己拼列拼行极其别扭。对比项EPPlusExcelDataReader定位导出为主读取为辅读取为主不支持写格式.xlsx新版不读 .xls.xls 与 .xlsx 均可内存模型整表载入内存流式逐行解析扩展能力样式、公式、合并、模板无授权5.x 起需设置 LicenseContext宽松许可无额外约束我也试过用 NPOI 一把梭的方案读写都靠它但复杂表头样式写起来太啰嗦维护成本高还见过有人在服务器上直接开 COM 调 Excel 接口这在容器化环境基本跑不通依赖桌面组件不说并发一高就崩。选两库分立本质是把「流的解析能力」和「样式的生成能力」各自发挥到极致。NuGet 装包很直接四个包一次装齐dotnet add package EPPlus dotnet add package ExcelDataReader dotnet add package ExcelDataReader.DataSet dotnet add package System.Text.Encoding.CodePagesExcelDataReader.DataSet 是独立包提供 AsDataSet() 扩展方法把工作表转成 DataSet 用System.Text.Encoding.CodePages 是给 .xls 老文件用的没它读 GBK 编码的中文必乱码第 4 章会展开。装完包如果是 EPPlus 5.x 及以上Program.cs 里第一件事就是把 LicenseContext 设好// Program.cs using OfficeOpenXml; ExcelPackage.LicenseContext LicenseContext.NonCommercial;这行不写new ExcelPackage() 直接抛异常。国内很多教程停留在 4.x 时代不写这行照抄到新版本就翻车。提示NonCommercial 只覆盖非商业场景商业项目请按 EPPlus 的授权条款确认后再上线别心存侥幸。2.2 接口设计读、写、模板下载三件事拆开做我一开始想把读和写揉进同一个 Service后来发现不行两者的异常处理、参数校验、日志关注点完全不同。读入要处理空行、类型转换、重复数据导出要处理样式、列宽、大结果集。揉在一起改一处崩另一处。最终拆成三个接口对应三个真实场景GET /api/excel/export按条件导出数据POST /api/excel/import上传并解析 ExcelGET /api/excel/template下载带格式的导入模板对应的项目结构excel-handler/ Controllers/ ExcelController.cs Services/ IExcelExportService.cs ExcelExportService.cs IExcelImportService.cs ExcelImportService.cs Models/ ExportRequest.cs ImportResult.csController 只做参数接收和校验真正逻辑在 Service接口抽象就两个public interface IExcelExportService { Taskbyte[] BuildOrderExcelAsync(DateTime startDate, DateTime endDate); } public interface IExcelImportService { TaskImportResult ParseOrderExcelAsync(Stream stream); }导出 Service 返回 byte[]Controller 拿到字节数组直接拼 File 响应导入 Service 接收 Stream返回 ImportResult里面装着成功行数、失败行数和每行的错误原因前端拿这份明细提示用户修正。这样 Controller 永远不用知道 Excel 长什么样后续想在导出前加工数据、导入后落库都不用动接口层。三个接口里「下载模板」最容易被忽略但实际价值很大模板里把列名、必填项、单元格格式都预设好用户在源头就少出错导入端也省掉很多脏数据清理。我通常会把模板版本号放进文件名比如 order_import_v2.xlsx避免用户拿旧模板传新数据。3. 用 EPPlus 导出内存流、响应头与大数据量的三个注意点3.1 导出接口代码骨架从数据到 ExcelPackage先看最常用的导出接口把订单数据按时间范围导出成 xlsx[HttpGet(export)] public async TaskIActionResult ExportOrders( [FromQuery] DateTime startDate, [FromQuery] DateTime endDate) { var data await _orderRepository.GetForExportAsync(startDate, endDate); using var package new ExcelPackage(); var sheet package.Workbook.Worksheets.Add(订单明细); // 表头 string[] headers { 订单号, 客户名称, 金额, 下单时间, 状态 }; for (int col 0; col headers.Length; col) { sheet.Cells[1, col 1].Value headers[col]; } // 数据从第 2 行开始写 int row 2; foreach (var order in data) { sheet.Cells[row, 1].Value order.OrderNo; sheet.Cells[row, 2].Value order.CustomerName; sheet.Cells[row, 3].Value order.Amount; sheet.Cells[row, 4].Value order.CreatedAt.ToString(yyyy-MM-dd HH:mm:ss); sheet.Cells[row, 5].Value order.StatusText; row; } // 按内容自适应列宽 sheet.Cells[1, 1, row - 1, headers.Length].AutoFitColumns(); // 一次性转成字节数组返回 var bytes package.GetAsByteArray(); var fileName $订单导出_{DateTime.Now:yyyyMMdd_HHmmss}.xlsx; return File(bytes, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, fileName); }几个关键点。using var package保证 ExcelPackage 用完即释放导出不释放会有文件句柄滞留问题。package.GetAsByteArray()是这里最不容易出错的做法它把内存流内部数据完整序列化出来完全不用操心流的当前位置。新手最常见的错误是拿package.Stream直接传给File()返回时流位置不对下载下来的文件打不开——这个坑后文还会展开。日期字段我建议写入时就格式化成字符串。直接赋 DateTime 类型也能显示但客户端打开后的格式依赖本机区域设置不如ToString(yyyy-MM-dd HH:mm:ss)稳定。金额字段保持数值类型别先ToString(0.00)再赋值否则 Excel 里是文本型数字后续做 SUM 会得到 0。提示凡是导出的文件打不开先检查 Content-Type 和流的 Position 两件事九成问题出在这。3.2 响应头里的中文文件名Content-Disposition 的坑File(bytes, contentType, fileName)会自动生成 Content-Disposition 响应头但对中文文件名框架会分两段写filenameexport.xlsx 和 filename*UTF-8%E8%AE%A2%E5%8D%95...。现代浏览器和 WPS 会读 filename* 那段于是中文文件名正常显示但少数老客户端只读 filename 段拿到的就是 export.xlsx。我一般显式控制这个响应头保证降级路径也可读var cd new System.Net.Http.Headers.ContentDispositionHeaderValue(attachment); cd.FileNameStar fileName; // UTF-8 编码的完整文件名客户端优先读这段 cd.FileName export.xlsx; // ASCII 兜底文件名老客户端读这段 Response.Headers.ContentDisposition cd.ToString();FileNameStar 赋值中文没问题标准库会自动做 URL 编码。Content-Type 也要配对xlsx 和 xls 的 MIME 类型不一样写错轻则浏览器不渲染重则被安全网关直接拦下文件格式MIME 类型.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet.xlsapplication/vnd.ms-excel.csvtext/csv导出接口最好再显式声明[Produces(application/vnd.openxmlformats-officedocument.spreadsheetml.sheet)]避免内容协商出意外。如果接口协商到 JSON 或默认格式客户端收到 406 之类的响应会一脸懵。3.3 大数据量导出别逐行赋值也别无脑 AutoFit导出几千行时逐行 Cells 赋值没问题但到了五万行以上逐行赋值加每次设样式耗时和内存都会明显上涨。数据量大时我一般把数据装进 DataTable再一次性灌入工作表var dt new DataTable(); dt.Columns.Add(订单号, typeof(string)); dt.Columns.Add(金额, typeof(decimal)); dt.Columns.Add(下单时间, typeof(string)); foreach (var order in data) { dt.Rows.Add(order.OrderNo, order.Amount, order.CreatedAt.ToString(yyyy-MM-dd HH:mm:ss)); } using var package new ExcelPackage(); var sheet package.Workbook.Worksheets.Add(订单明细); sheet.Cells[A1].LoadFromDataTable(dt, true);LoadFromDataTable的第二个参数表示是否把 DataTable 列名作为表头写出传 true 即可。它内部按数组批量写入比逐行设单元格值快实测几万行差距能到三倍以上。代价是样式控制弱一些表头格式、列宽得写完后单独处理。另一个经验是AutoFitColumns()慎用在大表上。这个方法是逐个单元格量宽度再算最优列宽五万行十列就是五十万次测量导出接口响应时间肉眼可见地变慢。我的习惯是小表几百行用 AutoFit大表直接手写列宽或者干脆不设列宽让用户自己拉。最后是物理边界Excel 单表上限 1048576 行超过这个数之前就要做分片导出或提示用户缩小查询范围硬塞进去 Excel 会直接报错这是导出的底线躲不开。真遇到百万级数据别走 Excel 了直接生成 CSV 压缩包更现实。4. 用 ExcelDataReader 导入流式解析、类型映射与 .xls 兼容4.1 上传接口与 DataSet 转换先落盘还是先读流导入接口接收 IFormFile标准做法是拷贝到 MemoryStream 后用 ExcelDataReader 解析[HttpPost(import)] [RequestSizeLimit(50 * 1024 * 1024)] public async TaskIActionResult ImportOrders(IFormFile file) { if (file null || file.Length 0) return BadRequest(文件为空); var ext Path.GetExtension(file.FileName).ToLowerInvariant(); if (ext is not (.xls or .xlsx)) return BadRequest(仅支持 .xls 或 .xlsx 文件); // .xls 老格式需要注册编码提供程序否则中文乱码 Encoding.RegisterProvider(CodePagesEncodingProvider.Instance); using var stream new MemoryStream(); await file.CopyToAsync(stream); stream.Position 0; using var reader ExcelReaderFactory.CreateReader(stream); var ds reader.AsDataSet(new ExcelDataSetConfiguration { ConfigureDataTable _ new ExcelDataTableConfiguration { UseHeaderRow true } }); var rows ParseDataTable(ds.Tables[0]); return Ok(new { total rows.Count, rows rows.Take(100) }); }CopyToAsync 到 MemoryStream 之后必须stream.Position 0不然 CreateReader 从流尾部开始读读出来是空数据集。这个细节很多人踩过。ext is not (.xls or .xlsx)是 C# 9 的模式匹配写法老项目里换成等价的原生判断即可。超过 50MB 的大文件拷进 MemoryStream 会占掉 50MB 内存再用 AsDataSet 全量转 DataTable内存峰值轻松到几百 MB。我的取舍是50MB 以下走内存流操作最简洁以上先落盘到临时文件再用文件流读取GC 压力小很多var tempPath Path.Combine(Path.GetTempPath(), ${Guid.NewGuid():N}{ext}); using (var fs System.IO.File.Create(tempPath)) { await file.CopyToAsync(fs); } using var stream System.IO.File.OpenRead(tempPath); using var reader ExcelReaderFactory.CreateReader(stream); // 后续解析逻辑与上面一致临时文件用完记得删建议用 try-finally 或注册一个后台清理任务不然 temp 目录会被导入文件塞满。4.2 类型映射日期序列号、空值和文本数字ExcelDataReader 按单元格类型把值读成 double、string、bool 或 DateTime。最容易翻车的是日期源文件单元格是「日期」格式时读出来是 DateTime源文件里是手敲的 44562 这种数字时读出来是 double要手动转。我一般在 Service 里做一层统一转换private static DateTime? ConvertToDateTime(object? raw) { if (raw null || raw DBNull.Value) return null; if (raw is DateTime dt) return dt; // OADate 序列号Excel 内部以 1900-01-01 为起点的天数计数 if (raw is double oaDate) return DateTime.FromOADate(oaDate); if (DateTime.TryParse(raw.ToString(), out var parsed)) return parsed; return null; }DateTime.FromOADate是 Excel 日期序列号的标准转换函数。Excel 的 1900 闰年 bug 会导致 1900 年 2 月 29 日这种不存在的日期也能被表示业务里极少遇到但要清楚有这个历史遗留。另一个高频坑是文本型数字和数值型数字。身份证号、订单号这类超过 15 位的数字Excel 的 double 精度只保留 15 位有效数字源文件里一旦是数值格式第 16 位开始就丢了。这种数据必须在源头约束导出端把这类列设为文本格式导入端校验时看类型——是 double 且位数超 15 就直接报错让用户回源文件改格式。// 导出身份证列时提前把单元格格式设为文本 sheet.Cells[row, 4].Style.Numberformat.Format ; sheet.Cells[row, 4].Value order.IdCard;数字格式标记让 Excel 把后续写入的值当文本处理导入端读出来就是 string不丢精度。4.3 .xls 兼容与上传限制编码、格式嗅探与请求上限ExcelDataReader 不靠扩展名判断格式它读文件头签名来判断是 OOXML 还是 BIFF所以扩展名改错了也能读。但有两个前提一是 .xls 老文件的字符串编码依赖本地区域设置必须注册 CodePagesEncodingProvider否则中文变乱码二是文件本身损坏或伪造扩展名时 CreateReader 可能抛异常接口要捕获并返回友好错误别让解析异常直接变成 500。我还会在 Program.cs 里统一限制上传体积防恶意大文件拖垮进程// Program.cs builder.Services.ConfigureMicrosoft.AspNetCore.Http.Features.FormOptions(options { options.MultipartBodyLengthLimit 50 * 1024 * 1024; });这个配置和 Controller 上的[RequestSizeLimit]是两道独立限制。另外新版 ASP.NET Core 的 Kestrel 默认请求体上限约 30MB如果没放开MaxRequestBodySize请求在到达 Controller 之前就被 Kestrel 拦下你在 Controller 里设的 50MB 根本不生效。三个限制一起确认才算把上传边界锁死。注意MultipartBodyLengthLimit、RequestSizeLimit、Kestrel MaxRequestBodySize 是三个独立限制要同时放开。5. 避坑指南这套 excel-handler 里的五个典型翻车现场以下五个问题都是我在落地这套方案过程中真实遇到过、并且花时间查过根因的按现象到解决的顺序记录。5.1 EPPlus 5.x 一启动就抛 LicenseException现象new ExcelPackage() 直接抛异常项目跑不起来。原因EPPlus 5.x 起授权策略变更要求应用在启动时显式声明 LicenseContext不声明就按非法状态处理。解决Program.cs 顶部加ExcelPackage.LicenseContext LicenseContext.NonCommercial;。注意 NonCommercial 定义是「非商业免费」商业项目要按授权条款自行确认。我见过有项目引用了老封装再升级 EPPlus整个导出模块集体罢工查了半天就是 LicenseContext 没设。5.2 导出的文件在客户端打开提示格式损坏现象接口返回 200文件也下载成功但用户用 Excel 或 WPS 打开弹「文件格式或扩展名无效」。原因九成是 Content-Type 写成了 application/octet-stream或者用了package.Stream直接返回——流位置没归零客户端拿到的是截断数据。解决统一用package.GetAsByteArray()转字节数组再走File(bytes, contentType, fileName)手动控制响应头时确保 Content-Type 是标准值。后来我在导出 Service 里加了一道自检每次导出后先看字节数组前四个字节确认存在 PK\x03\x04 的 zip 签名再返回从那以后这个坑再没出现。5.3 .xls 上传文件中文乱码现象老系统导出的 .xls 文件导入后中文字段变成「锟斤拷」或「鎴戠殑」这类乱码。原因.xls 是二进制 BIFF 格式字符串按系统代码页常见 GBK存储ExcelDataReader 默认只注册了 UTF-8 相关编码字节被按错误编码解释了。解决在 Program.cs 或接口开头调用Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);注册完整代码页支持。注册必须发生在 CreateReader 之前全应用注册一次最省心。把 .xls 另存为 .xlsx 能绕开但作为接收方你没有控制权服务端必须兼容。5.4 数字列读出来变成科学计数法现象导入的金额 12345678.9 读出来是 1.23456789E7身份证号读出来是 1.23456E17精度已经丢了。原因ExcelDataReader 把数值型单元格读成 doubledouble 对 15 位以上有效数字精度不足。科学计数法只是 ToString 的默认形式精度丢失才是真问题。解决分两层。身份证号等长数字必须源头做成文本列导出设Numberformat.Format 导入端读到 double 且位数超长直接拒绝金额等数值类型读取后转 decimal 再入库JSON 序列化也精确。导入端拿到 double 序列化回 JSON 大概率以科学计数法出现要么 Service 层统一转 string/decimal要么在 DTO 上用序列化特性控制。5.5 上传大文件后内存只涨不跌现象连续导入几个 80MB 的 xlsx进程内存冲到 1GBGC 后也降不下来。原因IFormFile 全量拷进 MemoryStreamAsDataSet 又把整个表加载成 DataTable一份文件在内存里存了三份加上异常路径流没释放内存自然只涨不跌。解决超过 50MB 落盘再读。数据本身大时不用 AsDataSet改流式逐行读取边读边批量写库using var stream System.IO.File.OpenRead(tempPath); using var reader ExcelReaderFactory.CreateReader(stream); // 第一行作为表头 var headers new Liststring(); if (reader.Read()) { for (int i 0; i reader.FieldCount; i) headers.Add(reader.GetValue(i)?.ToString() ?? $列{i 1}); } var buffer new ListDictionarystring, object?(); int rowCount 0; while (reader.Read()) { var record new Dictionarystring, object?(); for (int i 0; i reader.FieldCount; i) record[headers[i]] reader.GetValue(i); buffer.Add(record); rowCount; // 每 500 条批量落库一次避免一直积在内存里 if (buffer.Count 500) { await _orderRepository.BatchInsertAsync(buffer); buffer.Clear(); } } if (buffer.Count 0) await _orderRepository.BatchInsertAsync(buffer);流式模式的内存占用基本恒定跟文件大小无关。这已经是我处理大文件导入的默认形态小文件才走 AsDataSet 的省事路线。6. 进阶模板导出、合并表头与一个导入补救技巧6.1 预置模板把样式交给运营而不是代码有些导出要求带指定列宽、颜色、页眉用代码一点一点设太累。我的做法是先在 Excel 里做好模板放到 wwwroot/templates 下EPPlus 加载模板后填值using var package new ExcelPackage(new FileInfo(wwwroot/templates/order_template.xlsx)); var sheet package.Workbook.Worksheets[0]; sheet.Cells[C2].Value companyName; // 模板里预留的命名单元格 sheet.Cells[C3].Value DateTime.Now.ToString(yyyy-MM-dd); int startRow 5; // 模板预留的明细起始行 for (int i 0; i items.Count; i) { sheet.Cells[startRow i, 1].Value items[i].OrderNo; sheet.Cells[startRow i, 2].Value items[i].Amount; } return File(package.GetAsByteArray(), application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 模板导出.xlsx);收益是样式改动不用发布代码。建议给模板关键单元格提前命名代码用sheet.Names[CompanyName]定位比硬编码行列号更耐插行。6.2 合并单元格、公式与表头错位的补救汇总报表常用合并标题和合计公式EPPlus 两行代码搞定sheet.Cells[1, 1, 1, 4].Merge true; // 合并第 1 行 1~4 列 sheet.Cells[1, 1].Value 月度订单汇总; sheet.Cells[1, 1].Style.HorizontalAlignment ExcelHorizontalAlignment.Center; int totalRow startRow items.Count; sheet.Cells[totalRow, 2].Formula $SUM(B{startRow}:B{totalRow - 1}); package.Workbook.Calculate(); // 5.x 后走 workbook 级重算写公式必须调用 Calculate 重算一次否则打开文件可能显示 0。EPPlus 4.x 用的是 worksheet.Calculate()5.x 之后推荐 workbook 级计算老代码升级时注意这个 API 变化。另一个高频场景是导入模板第一行是合并大标题、第二行才是列名UseHeaderRowtrue 会把标题当表头列名全部错位。补救办法是关掉自动表头手动取第 1 行做列名、第 2 行起做数据把表头行号做成配置项而不是写死。对接第三方模板时尤其有用——对方的 Excel 通常都有封面行、说明行列名位置不规范是常态。从那以后我做 Excel 相关改动上线前都会强制走一遍自检导出先本地打开看格式再模拟客户端下载看响应头最后用一份带脏数据的模板跑导入看类型转换报错。这套流程帮我挡掉过好几次线上事故希望帮到你。本文还有配套的精品资源点击获取