简介面向ASP.NET Core开发者的Excel处理示例项目演示在WebAPI中结合EPPlus与ExcelDataReader完成Excel文件的读取与导出避免Office Interop依赖适合需要在上传下载、数据导入导出等场景中处理xlsx/xls的中高级开发者。包体共208个文件约21.89MB以dll运行库、cs源码、json与config配置为主附带pdb调试符号和构建缓存解压后可通过.sln直接加载运行按Controller、Service等层次组织便于理解工程结构。资源内包含控制器导出Excel的完整示例代码覆盖ExcelPackage创建工作表、单元格赋值、MemoryStream写出以及设置MIME类型与Content-Disposition响应头等关键步骤读取侧则演示通过FileStream结合ExcelReaderFactory.CreateReader进行流式遍历适用于大型文件导入场景。整体可以作为不依赖Office环境的Excel上传导出模板也可作为深入理解OpenXML写入与老版本流式读取差异的参考。另外可根据业务需求扩展错误处理、数据校验与性能优化目前已有399人学习下载适合.NET WebAPI开发者直接复用或二次改造。1. 从“Excel导入导出”到“excel-handler”这个WebAPI项目把两条老路都走通了搜索 excel-handler 的人大概率不是来学 C# 语法而是被 WebAPI 里的 Excel 折磨过读大文件内存爆掉、日期变成一串数字、合并单元格读到一半是空的、导出报表样式全丢。这个资源的思路很直接把读和写拆成两条独立管线——用 ExcelDataReader 做流式读取负责上传解析用 EPPlus 做模板化导出生报表。我拆完最大的感受是不再在 Controller 里硬啃字节流也不用把整个工作簿加载进内存之后发现样式、公式、列宽一个都控制不住。适合用 ASP.NET Core 做前后端分离的后端开发也适合手里有大量 .xls 老文件要兼容的业务系统。2. 选型拆解为什么读与写要各用一个库而不是拿 EPPlus 一把梭很多人一搜“C# Excel”会同时碰到 NPOI、ClosedXML、EPPlus、ExcelDataReader 一串库各教程各说各话实际照抄进 ASP.NET Core WebAPI 里就翻车。问题不在库本身而是读取和导出在底层是两码事读取的关键词是“流式、兼容老格式、类型转换”导出的关键词是“模板、样式、可控”。下面拆开讲。2.1 EPPlus 管导出OpenXML 封装带来的模板能力EPPlus 本质上是 OpenXML 的封装层生成 .xlsx 等于在服务端打一个格式包。单元格样式、列宽、合并区域、数据验证、自动筛选都有对象模型不需要手写 XML接口稳定文档量大搜“epplus 导出 excel”能翻到大量案例。这是它在导出场景不可替代的原因。但 EPPlus 5.0 之后 License 政策变了商用项目要买授权。我的处理方式是开发环境在入口处设LicenseContext.NonCommercial商用评估阶段再走商务签。这个成本要提前算进去否则项目上线后法务找上来比代码 bug 更难受。那能不能用 ExcelDataReader 写导出不行这个库只读不写。所以不管怎么选读和写天然需要两个库除非你愿意用 NPOI 从零维护样式代码。2.2 ExcelDataReader 管读取流式模型与老格式兼容WebAPI 服务端更稳ExcelDataReader 读 .xlsx 是流式的一行一行往下拉不会把整个工作簿塞进内存这对大文件上传场景很重要。另一个价值是它同时支持 .xlsBIFF和 CSV老系统导出的 .xls 文件EPPlus、ClosedXML 都不认但 ExcelDataReader 能打开。这一点我在医院项目里体会很深那边业务系统导出的全是 .xls 历史文件新报表是 .xlsx一个读取库全兼容省去写两套解析逻辑。还有一点容易被忽略——它是IExcelDataReader的流式接口读一行映射一行 DTOWebAPI 服务端用完即弃GC 压力小不像某些库会把整张表加载到 DataTable 里撑着。2.3 边界在哪什么时候换用 ClosedXML、NPOI 或干脆用 pandas做过 Python 的人经常说“pandas 读写 excel 文件一把梭”但这个习惯别搬到 ASP.NET Core 服务端——pandas 在 Python 里也是整个文件进 DataFrame服务端这么干的结果就是内存和 GC 双高。C# 这边的常见做法就是流式处理。至于网上搜到的“c 打开 excel 文件写入”之类的提问基本都是 C/ C 场景和 WebAPI 不是一个赛道参考价值有限。做个简单的对比表方便你按项目状态选库擅长场景明显短板License 注意点EPPlus导出 .xlsx、复杂样式、模板填充读取大文件吃力5.0 后商用收费ExcelDataReader流式读取 .xlsx / .xls / CSV不支持写入开源免费ClosedXML轻量读写 .xlsx老格式 .xls 不支持MITNPOI兼容 .xls 的读写样式 API 偏底层Apache 2.0我这边的结论是新项目读用 ExcelDataReader写用 EPPlus两者通过服务层隔离以后要换 ClosedXML 只改实现类不动 Controller。3. 搭建 excel-handler依赖注入、上传限制与最简读写接口这一章从空目录开始把项目跑起来。目标是先搭出两个接口一个接收上传的 Excel一个生成导出的 Excel。中途会把上传限制和 EPPlus License 两个隐形坑一起处理掉。3.1 从空项目到服务注册生命周期选 Scoped 的理由先建一个 ASP.NET Core WebAPI 项目我用的是 .NET 6/8 都兼容的写法。核心在 Program.cs 里注册服务using ExcelHandler.Services; var builder WebApplication.CreateBuilder(args); // EPPlus 5 之后必须设置 LicenseContext否则运行时直接抛 LicenseException ExcelPackage.LicenseContext LicenseContext.NonCommercial; builder.Services.AddScopedIExcelReaderService, ExcelReaderService(); builder.Services.AddScopedIExcelExporterService, ExcelExporterService(); builder.Services.AddControllers(); var app builder.Build(); app.MapControllers(); app.Run();两个服务都注册为Scoped不是Singleton也不是Transient。原因是读取服务内部会持有当前请求的文件流引用单例会导致一次请求结束后流被释放下次请求复用直接翻车Transient 则每次注入都新建实例对无状态服务没问题但读取服务里可能会缓存表头映射配置Scoped 是“一次请求内稳定”的最小单位正好匹配。3.2 上传接口与请求体限制Kestrel、IIS 和 413 的来龙去脉上传接口用IFormFile接收文件最基本的版本长这样[HttpPost(import)] public async TaskIActionResult Import(IFormFile file) { // 空文件直接拒绝避免下游 reader 拿到 0 字节流后行为不确定 if (file null || file.Length 0) return BadRequest(上传文件为空); var ext Path.GetExtension(file.FileName).ToLower(); if (ext ! .xlsx ext ! .xls) return BadRequest(仅支持 .xlsx 或 .xls 文件); // 用 MemoryStream 包一层防止 IFormFile 底层流被 ExcelDataReader 读完一次后失效 using var ms new MemoryStream(); await file.CopyToAsync(ms); ms.Position 0; var rows _reader.Read(ms); return Ok(new { count rows.Count, data rows }); }这里有个必踩的坑IFormFile.OpenReadStream()返回的流不一定可 seekExcelDataReader 按流式读到底之后第二次读就是异常或者空数据。所以我习惯先CopyToAsync到 MemoryStream再Position 0读。小文件没问题大文件稍微费点内存但在上传限流的前提下可接受。请求体限制是另一道门槛。默认 Kestrel 对请求体大小限制是 30MB超过直接 413前端看到的是“请求实体过大”。配置项需要同时考虑 Kestrel 和 IIS 两层设置位置配置内容作用appsettings.jsonKestrel:Limits:MaxRequestBodySizeKestrel 独立托管时生效Program.csbuilder.WebHost.ConfigureKestrel(...)代码里更直观可按环境区分IIS 的 web.configrequestLimits maxAllowedContentLengthIIS 反向代理时必须一起改FormOptionsMultipartBodyLengthLimitASP.NET Core 表单绑定层的限制我一般把 Excel 上传上限设成 20MB理由有两个一是 Excel 纯数据文件超过 20MB 说明原始数据就有问题二是 MemoryStream 拷贝大文件时翻倍占内存服务器并行请求一多容易 OOM。3.3 License 配置EPPlus 5 之后必须处理的第一件事EPPlus 4.x 还是 LGPL5.0 之后变成双授权。非商用可以用LicenseContext.NonCommercial但要注意这个设置是进程级的不是每个 package 单独设。我见过有人放在某个 Service 构造函数里设结果并行请求下第一次初始化正常、第二次抛异常的怪事——因为静态属性被并发覆盖了。正确做法是在 Program.cs 最开头、builder.Build()之前全局设置一次。另外判断自己是不是商业用途的标准不是“公司有没有付钱”而是“这个服务有没有被商业业务使用”。内部管理系统也算商用。不确认就去 EPPlus 官网看授权说明别赌。4. 导出 Excel让报表“能打开、能看、能交差”导出接口看着简单实际“能打开”只是及格线。业务方要的报表往往要求列宽、筛选、冻结表头、特定格式这些才是 EPPlus 真正擅长的地方。4.1 最小导出服务从内存流到浏览器下载先写一个最小版本理解 EPPlus 的 API 结构[HttpPost(export)] public async TaskIActionResult Export() { // using 保证 ExcelPackage 释放否则临时文件会堆积在系统临时目录 using var package new ExcelPackage(); var sheet package.Workbook.Worksheets.Add(订单报表); // 表头 sheet.Cells[A1].Value 订单号; sheet.Cells[B1].Value 客户名称; sheet.Cells[C1].Value 金额; sheet.Cells[D1].Value 下单时间; // 模拟两行数据实际项目里这里是从数据库/内存列表取 sheet.Cells[A2].Value SO-1001; sheet.Cells[B2].Value 上海某某贸易; sheet.Cells[C2].Value 12800.50m; sheet.Cells[D2].Value DateTime.Now; var bytes await package.GetAsByteArrayAsync(); // 中文文件名要 URL 编码否则部分浏览器下载时乱码或截断 var fileName Uri.EscapeDataString($订单报表_{DateTime.Now:yyyyMMdd}.xlsx); return File(bytes, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, fileName); }两个细节。第一GetAsByteArrayAsync返回的是内存字节数组文件内容已经在内存里了using释放的是 ExcelPackage 占用的临时资源和文件句柄。第二fileName必须做Uri.EscapeDataString中文文件名 Content-Disposition 是经典乱码源不编码的话 Chrome 正常、旧版 Edge 和 IE 直接乱码。4.2 格式细节列宽、自动筛选、冻结窗格与合并单元格导出的报表如果只有数据业务方会说“能用但没法看”。加格式的代码量不大但对交付效果提升最明显// 列宽优先按内容自适应但金额列手动给固定宽度更整齐 sheet.Cells[A1:D100].AutoFitColumns(1, 80); // 最小宽度 1最大 80 sheet.Column(3).Width 18; // 金额列固定 18 // 自动筛选下拉框直接生成业务方按状态筛选零成本 sheet.Cells[A1:D1].AutoFilter true; // 冻结表头滚动时第一行始终可见长报表必备 sheet.View.FreezePanes(2, 1); // 合并单元格标题行横跨 A:D sheet.Cells[A1:D1].Merge true; sheet.Cells[A1].Value 2024 年度订单汇总; sheet.Cells[A1].Style.Font.Size 14; sheet.Cells[A1].Style.Font.Bold true;参数说明AutoFitColumns(1, 80)的第一个参数是最小字符宽度第二个是最大超长内容不会被无限制撑开FreezePanes(2, 1)表示冻结第一行和第一列第二个参数等于 1 表示从第 2 行开始可滚动合并区域赋值时要赋给左上角单元格其它单元格留空否则 Excel 打开会报格式警告。还有一个小经验表头样式底色、字体、边框建议统一抽一个私有方法因为报表多了以后样式代码是最容易重复的地方。4.3 复杂报表的常见做法加载 Excel 模板只填数据如果报表格式很复杂——比如财务结算单、对账单每一行都有固定边框、特定小数位、批注纯代码写样式会写到崩溃。我的做法是准备一个 .xlsx 模板文件里面画好所有静态格式代码里用Load加载后只填数据区域// 模板文件模板/结算单.xlsx已经画好边框、合并单元格、公式 using var template new FileStream(模板/结算单.xlsx, FileMode.Open, FileAccess.Read); using var package new ExcelPackage(template); var sheet package.Workbook.Worksheets[0]; // 模板里第 5 行开始是数据明细区域DB 列是金额列 var orders GetSettlementOrders(); // 数据库查询 int row 5; foreach (var order in orders) { 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.SettledAt; row; } // 数据下方是模板里的合计公式公式会自动扩展到新区域 var bytes await package.GetAsByteArrayAsync(); return File(bytes, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, 结算单.xlsx);模板方案的核心价值是“样式和代码解耦”。业务方要改样式直接把模板发回去改设计人员改完发回来代码不用动。要注意模板文件路径别写死用IConfiguration或IWebHostEnvironment拼绝对路径否则部署到 Linux 容器里临时目录一变就找不到文件。5. 避坑清单读 Excel 常见的四个坑与排查实录这一章是我拆项目时重点整理的血泪部分每一条都是线上或开发阶段真实遇到过的按“现象 → 原因 → 解决”写。5.1 文件流只能读一次IFormFile 与 ExcelDataReader 的配合现象Controller 里拿到IFormFile后直接OpenReadStream()传给 ExcelDataReader 读取第一次正常第二次再读同一个流抛“无法读取”或读到 0 行。原因IFormFile.OpenReadStream()返回的流是只向前、不可重寻的non-seekable。ExcelDataReader 流式读取会把流一路读到 EOF之后流的 Position 已经到末尾任何再次读取都是空。解决先用MemoryStream托底再Position 0using var ms new MemoryStream(); await file.CopyToAsync(ms); ms.Position 0; using var reader ExcelReaderFactory.CreateReader(ms); // 这时候 reader 想读几遍就读几遍因为底层是内存流随时可以 Reset注意“想读几遍”的前提是每次都ms.Position 0再重新CreateReader。血泪经验一次请求内如果既想读文件校验、又想转存一份到对象存储必须走这个副本。5.2 日期变成 OLE 自动化序列号现象Excel 里明明是“2024-01-15”读出来变成45231这种数字或者变成字符串“2024-01-15 00:00:00”。原因Excel 内部把日期存成 OLE Automation Date即从 1899-12-30 起算的天数。ExcelDataReader 对日期型单元格返回的是数值需要手动转换。解决写一个列类型转换的辅助方法识别Numeric类型且在合理日期范围内时转成DateTime// 合理的 OLE 日期范围1900-01-01 到 9999-12-31 private static DateTime? ConvertDate(double value) { if (value 1 || value 2958465.0) return null; return DateTime.FromOADate(value); }调用时判断reader.GetFieldType(i)为typeof(double)且表头是日期字段就用这个方法。另一个坑是单元格格式是“文本”的日期读出来是字符串那种情况需要DateTime.TryParse我一般在TryParse失败时记日志并保留原始值而不是直接抛异常方便业务侧回去改数据。5.3 空行与合并单元格的“幽灵数据”现象读出来一行解析下来全是 null 或空字符串但行数很多像是“扫到一堆空数据”另一种更隐蔽——合并单元格只有左上角有值其它格子读出来是 null。原因用户在 Excel 里按了回车产生空行或者业务方为了排版去合并单元格合并区域的值只存在左上角单元格对象里。解决这两类问题要分开处理。空行直接跳过// 判断一整行是否全空是则跳过减少后续 DTO 映射的开销 var rowHasValue Enumerable.Range(0, reader.FieldCount) .Any(i reader.GetValue(i) ! null !string.IsNullOrWhiteSpace(reader.GetValue(i)?.ToString())); if (!rowHasValue) { reader.NextResult(); // 或者按 DataReader 的循环移动 continue; }合并单元格的处理更麻烦EExcelDataReader 不会帮你横向补齐。我常用的方案是读每一列值时如果当前格是 null就向左找非空值补上合并行的情况再向上找。这个逻辑单独提一个GetMergedValue(sheet, row, col)方法不要散写在业务解析里。5.4 EPPlus 读公式读出来的是公式字符串现象用 EPPlus 读一个带SUM(A1:A10)公式的单元格Value拿到的是“SUM(A1:A10)”字符串不是计算结果有时候拿到的是一个看起来对、但实际是上次 Excel 打开时的缓存值。原因OpenXML 格式里公式单元格同时存了公式和“上次计算结果缓存”。EPPlus 默认不重新计算公式引擎直接返回缓存值缓存缺失时就返回公式文本。解决读取场景优先用 ExcelDataReader它按“值”返回如果已经在 EPPlus 流程里可以手动触发计算package.Workbook.Calculate(); // 全工作簿重算 var value sheet.Cells[C20].Value; // 此时拿到计算结果注意Calculate()有一定的性能开销大工作簿会明显变慢只在确有必要时调用。还有一个边界ExcelDataReader 读出来的公式计算值本质也是 Excel 最后一次保存时的缓存如果那个文件是从接口程序生成、从未用 Excel 打开过缓存可能根本不存在。所以读的时候别假设“Excel 文件里的数字一定可靠”该重算的重算。6. 进阶技巧把“读→改→写→再读”串成回归验证问题在进数据库前钉死这个习惯是我被坑过两次之后养成的一次是导入的数据在 Excel 里看着对入库后才发现日期偏移了一天一次是导出的报表在 Linux 服务器上生成后Windows 打开显示“文件损坏”。从那以后我每次改动 Excel 相关代码都强制走一遍“读 → 改 → 写 → 再读”的闭环回归不进数据库不联调前端。具体做法是准备一个小型验证用的样例文件二十行左右覆盖表头、日期、金额、合并单元格、空行这些边界条件。然后写一个验证方法// 回归验证样例.xlsx 读进来 - 导出成 新样例.xlsx - 再读一遍 - 断言关键值一致 public void RoundTripTest(string sourcePath) { // 1. 读取源文件 using var sourceStream File.OpenRead(sourcePath); var originalRows _reader.Read(sourceStream); // 2. 把读到的数据原样导出 var exportedBytes _exporter.Export(originalRows); // 3. 再把导出的文件读回来 using var exportedStream new MemoryStream(exportedBytes); var reimportedRows _reader.Read(exportedStream); // 4. 断言行数不变日期字段的值不变金额字段的值不变 Debug.Assert(originalRows.Count reimportedRows.Count); Debug.Assert(originalRows[0].OrderDate reimportedRows[0].OrderDate); Debug.Assert(originalRows[0].Amount reimportedRows[0].Amount); }这个测试的价值是它同时验证了读取、导出、类型转换三个环节。日期偏移、金额精度丢失、空行误判这些问题大多在第二步“导出后再读”就现原形根本走不到数据库那一层。方法不复杂但能省掉大量和业务方来回要样本文件的沟通成本。另外建议在真正的上传接口里给每个阶段加 Stopwatch 日志不是跟踪性能而是排错时定位问题在哪一段var sw Stopwatch.StartNew(); // reader 读取逻辑 sw.Stop(); _logger.LogInformation(读取阶段花费 {ElapsedMs} ms, sw.ElapsedMilliseconds);ExcelDataReader 解析到一半抛异常时如果日志能明确告诉你“是读取 2000 行之后挂掉的”比对着堆栈猜快得多。这个项目本身已经把读写两头都处理好了你拿到手之后先跑通这个闭环再把它接到自己的数据访问层Excel 这块就基本从踩坑清单里划掉了。希望帮到你。本文还有配套的精品资源点击获取