做后端开发的人应该都接过这种需求系统里有一份JSON格式的数据可能是接口返回的也可能存在数据库某个字段里业务方说要导成Excel方便他们筛筛选选、发给别人看。我第一次接到这个需求的时候心想不就是把JSON转成表格嘛写个循环往单元格里塞值就行了。结果真正做完才发现方案选错后面全是坑——数据不多的时候看起来没事数据一上万、字段结构一复杂要么导出文件打开就报错要么内存先被吃光。这篇文章把我实践后的完整方案和踩过的坑整理出来给准备做“JSON转Excel导出”功能的朋友一个参考。无论你是在做内部管理系统、接口对接工具还是给业务部门做数据分析前的数据抽取思路基本通用代码也基本可以直接抄。1. 先把方案选清楚直接写Excel还是走旁门左道1.1 常见的“伪Excel”方案为什么不推荐我第一次做这个功能时图省事直接把JSON拼成CSV字符串存成.csv文件。CSV确实是纯文本表格格式Excel也能直接打开但很快就会发现三个致命问题中文文件名在Excel里打开没问题可一旦内容里有中文保存编码不对就是一片乱码身份证号、订单号这种长数字会被Excel自动转成科学计数法精度丢了你都不知道还有CSV不支持多Sheet也不支持单元格样式、公式、数据验证这些真正的Excel特性。改扩展名这种事我也试过把一段HTML或者纯文本改成.xls后缀确实能被Excel打开但每次都会弹“文件格式与扩展名不一致”的警告稍微复杂点的表格结构直接就显示乱了。这就是为什么我后来坚持一个原则要导出真正的Excel文件就用真正生成xlsx的方案。xlsx本质上是一个zip压缩包里面是一堆XML文件靠手写XML当然也能生成但这活儿交给成熟的组件做更靠谱。1.2 主流的C# Excel组件怎么选在C#生态里处理Excel的组件不少我按使用场景列了个表方便你对照选型方案授权方式适用场景需要注意的地方EPPlus从5.0开始商业使用需要License功能全面、样式丰富对xlsx支持极好如果公司商用记得评估License费用ClosedXML开源免费MIT轻量级导出导入API简洁大文件性能一般NPOI开源免费Apache老项目需要兼容.xls格式写xlsx的API稍微底层文档偏旧OpenXML SDK开源免费MIT追求极致的性能和可控性代码量大样式处理要自己写商业组件各类报表套件商业付费不想折腾、预算充足文件体积大License不便宜我的建议很直接新项目、普通数据量选ClosedXML或者EPPlus老系统还在用.xls选NPOI如果是要导出几十万行甚至上百万行的超大报表别急着上EPPlus后面我会讲OpenXML或者直接走流式方案的思路。选型这事没有绝对正确关键是想清楚你的数据量、部署环境和是否商用。组件选好之后真正的重头戏在于JSON数据怎么喂给Excel。2. 数据准备JSON解析的两个分支JSON落到C#里最常见的两种形态一种是已经有强类型模型比如从接口反序列化成了ListOrder另一种是拿到手就是JArray、JObject这种动态结构字段随时可能加。这两种情况的处理思路完全不同我分开说。2.1 强类型模型最省事的路径如果你的JSON结构稳定最省事的方式是先定义好对应的C#类再反序列化成对象集合。拿订单数据举例public class Order { public string OrderId { get; set; } public string CustomerName { get; set; } public decimal TotalAmount { get; set; } public DateTime CreatedTime { get; set; } } // Newtonsoft.Json var orders JsonConvert.DeserializeObjectListOrder(jsonString); // System.Text.Json.NET Core 3.0 // var orders JsonSerializer.DeserializeListOrder(jsonString);用强类型的最大好处是后续写Excel时表头和数据可以按属性名直接取编译器能帮你检查错误不用操心JSON里字段名的大小写。但这里有个很容易踩的坑Newtonsoft.Json反序列化时默认不区分大小写而System.Text.Json在默认配置下是区分大小写的。如果你的JSON字段叫orderIdC#属性叫OrderId用System.Text.Json直接反序列化得到的全是默认值。解法有三种把属性改成和JSON字段一致用[JsonPropertyName(orderId)]特性标注或者配置JsonSerializerOptions里的PropertyNameCaseInsensitive true。我个人习惯是加上特性因为字段命名规范和C#的PascalCase风格冲突时特性能把两个世界打通。2.2 动态结构字段不固定时怎么处理但现实工作是残酷的很多场景下JSON结构根本不固定。比如对接第三方接口今天返回三个字段明天加了两个你不可能每次都改实体类重新发布。这时候最实用的做法是用JArray动态解析字段名从数据里自动提取。核心思路分三步用JArray.Parse把JSON字符串变成数组。遍历所有记录把出现的字段名收集到一个有序集合里这个集合就是Excel的列头。再遍历一次按列名取每个字段的值填入单元格。字段名收集时有个细节不要直接拿HashSetstring去重因为HashSet不保证顺序可能你JSON里第一个字段是id出来之后变成第三列。正确做法是用Liststring配合HashSetstring双结构既保证不重复又保证先来后到的顺序。var jArray JArray.Parse(jsonString); var columns new Liststring(); var columnSet new HashSetstring(); foreach (var item in jArray.OfTypeJObject()) { foreach (var prop in item.Properties()) { if (columnSet.Add(prop.Name)) { columns.Add(prop.Name); } } }这个动态方案有个天然优势以后数据源加字段你的导出代码一行都不用改Excel列会自动多出来。做接口对接类的工具时这个方案能省掉大量维护成本。2.3 嵌套对象和数组怎么摊平JSON里最让人头疼的就是嵌套。比如一个订单里嵌着收货地址对象地址下面又有省份城市。如果你直接把整个子对象ToString塞进单元格会出现一行{Province:广东,City:深圳}虽然没报错但业务方肯定不满意因为他们没法筛选用。嵌套对象处理我一般给两种策略让业务方选扁平化把子对象的字段拍平列名变成Address.Province、Address.City。这样每个字段独立成列方便筛选和透视。序列化成JSON字符串保留原始结构适合那种“只是备份一下完整数据不打算逐个字段分析”的场景。嵌套数组更麻烦因为一条主记录对应多条子记录。如果你把数组里的值都拼成一个长字符串用分号或竖线分隔那还能接受如果你想让每个子项各占一行那就等于做笛卡尔积拆行逻辑复杂度直接上一个台阶。我的建议是除非业务上明确要求“一单多行”否则嵌套数组优先用分隔符合并大体上够用而且实现成本低很多。扁平化的递归逻辑并不复杂就是遍历JToken的每个子级碰上JObject继续往下走碰上JValue就返回叶节点。写一个FlattenJson辅助方法以后所有嵌套JSON都能复用。3. 导出核心实现从JSON到Excel方案选定、JSON解析也确定了接下来就是真正的核心代码。我用EPPlus来演示因为它的API直观样式也丰富。先说明一下EPPlus从5.0开始非商业用途需要设置ExcelPackage.LicenseContext LicenseContext.NonCommercial;否则会抛LicenseException。3.1 表头怎么生成才好看表头是用户对表格的第一印象我通常不直接用JSON字段名而是维护一个字段映射字典把英文key对应成中文表头。比如var columnMapping new Dictionarystring, string { [orderId] 订单号, [customerName] 客户名称, [totalAmount] 订单金额, [createdTime] 创建时间 };这样做的原因很简单直接拿orderId当表头业务方大概率看不懂回头还得提需求让你改。用一个映射字典你随时能调整列名而不用改JSON解析逻辑。写表头时我建议把第一行整体设置成加粗、背景色、居中对齐再顺手冻结首行。就三行代码的事但用户体验差别很大。3.2 数据行的写入细节类型和格式数据写入时最容易被忽略的就是类型。常见的问题有两个第一长数字变科学计数法。订单号、身份证号这类超过15位的数字Excel会默认按数值处理显示成8.84195033128003E17精度直接丢失。解决办法是先把这类列设置为文本格式再写入字符串。第二日期显示成####。日期列的列宽不够时Excel不会自动换行只会显示一串井号。别慌把列宽调大或者用AutoFitColumns就能解决。我实际写入单元格时会判断一下JToken的类型再做相应处理for (int r 0; r rows.Count; r) { var rowObj rows[r]; for (int c 0; c columnList.Count; c) { var token rowObj[columnList[c]]; object value null; switch (token?.Type) { case JTokenType.Integer: value token.Valuelong(); break; case JTokenType.Float: value token.Valuedecimal(); break; case JTokenType.Boolean: value token.Valuebool(); break; case JTokenType.Date: value token.ValueDateTime(); break; default: value token?.ToString(); break; } ws.Cells[r 2, c 1].Value value; } }这个判断看着啰嗦其实能避免一个隐蔽问题如果你把所有值都ToString那金额字段就变成文本了业务方在Excel里没法SUM求和到时候你又被拉去改需求。类型该保留就要保留别怕麻烦。3.3 一套可以复用的导出方法把上面的逻辑拼起来就是一个通用的动态导出方法。我这边直接给一份基于EPPlus的完整参考实现public static byte[] ExportJArrayToExcelBytes( string json, Dictionarystring, string columnMapping) { ExcelPackage.LicenseContext LicenseContext.NonCommercial; var jArray JArray.Parse(json); var allColumns columnMapping.Keys.ToList(); using var package new ExcelPackage(); var ws package.Workbook.Worksheets.Add(导出数据); // 写表头 for (int i 0; i allColumns.Count; i) { var cell ws.Cells[1, i 1]; cell.Value columnMapping[allColumns[i]]; cell.Style.Font.Bold true; cell.Style.Fill.PatternType ExcelFillStyle.Solid; cell.Style.Fill.BackgroundColor.SetColor(Color.FromArgb(220, 220, 220)); cell.Style.HorizontalAlignment ExcelHorizontalAlignment.Center; } // 写数据 int rowIndex 2; foreach (var item in jArray.OfTypeJObject()) { for (int c 0; c allColumns.Count; c) { var token item[allColumns[c]]; object value null; switch (token?.Type) { case JTokenType.Integer: value token.Valuelong(); break; case JTokenType.Float: value token.Valuedecimal(); break; case JTokenType.Boolean: value token.Valuebool(); break; default: value token?.ToString(); break; } ws.Cells[rowIndex, c 1].Value value; } rowIndex; } // 调优展示效果 ws.Cells.AutoFitColumns(); ws.Cells[1, 1, rowIndex - 1, allColumns.Count].AutoFilter true; ws.View.FreezePanes(2, 1); using var ms new MemoryStream(); package.SaveAs(ms); return ms.ToArray(); }这个方法入参只要JSON字符串和一个字段映射字典返回字节数组。Web接口可以直接把这个byte[]丢给前端下载控制台程序也能直接写文件复用性很高。但注意这个版本适合几万行内的数据数据量再大就要看下一节的优化方案。4. 大数据量导出的性能实战很多人在留言里问我为什么导出1万行数据页面转半天导出10万行内存直接爆。这里面的坑不只是Excel组件的问题更常见的是写出代码的方式太差。4.1 不要再用循环逐格写数据了在循环里一个个赋值单元格比如ws.Cells[i, j].Value xxx;这种行为在EPPlus的实现里每写一个单元格都要处理坐标定位、样式继承、类型转换1万行乘20列就是20万次调用每个调用还有内部逻辑开销慢是必然的。更高效的方式是批量加载。如果你的数据源是强类型集合EPPlus提供了LoadFromCollectionws.Cells[A2].LoadFromCollection(orders, true);如果是DataTable用LoadFromDataTablews.Cells[A2].LoadFromDataTable(dataTable, true);这两个方法本质上是把整块数据一次性映射进Excel的单元格区域效率比逐格赋值提升几个数量级。我实测过同样1万行数据逐格写大概5到10秒用LoadFromCollection基本毫秒级就完成数据填充剩下的时间几乎全在生成文件上。4.2 内存暴涨的元凶整个Excel包堆在内存里用EPPlus最舒服的用法是using var package new ExcelPackage();所有内容都写进内存最后SaveAs到MemoryStream。数据少时完全没问题但到了几十万行ExcelPackage内部需要构建完整的工作簿模型再加上最终要生成的xlsx又是一个zip包内存占用可能是源数据的好几倍。解决思路有两个方向。方向一是减少常驻内存数据。JSON解析完之后不要一次性保存成ListJObject而是边遍历边写入Excel遍历完一份就释放一份。配合分批读取外部数据源比如数据库游标式的分页读取能显著降低内存峰值。方向二是换方案直接用OpenXML SDK的流式写入。xlsx内部是一个XML文件OpenXML SDK允许你以Stream的方式逐行追加数据不用把整个工作簿模型加载到内存。代价是自己要处理大量底层细节比如共享字符串、样式表。说实话不是每个人都愿意写这么多代码所以我的建议是如果经常要导出超大文件该用OpenXML就上一次封装好后面就是收益。4.3 Web下载时的文件流细节很多人忽略一个细节接口返回Excel时把ExcelPackage直接SaveAs到MemoryStream然后再把stream里的字节复制到响应流整个过程会同时存在两到三份完整文件的数据。如果是几百KB的小文件无所谓但几十MB的文件这么搞内存直接翻倍。我习惯的做法是大文件先写到服务器临时文件路径比如Path.GetTempFileName()然后通过FileStream读取返回给前端返回完再删除临时文件。这样内存里始终只有一份流在传输不会同时持有多个副本。在ASP.NET Core里返回文件的写法也要注意文件名编码[HttpGet(export)] public IActionResult Export() { var bytes ExportJArrayToExcelBytes(json, mapping); var fileName WebUtility.UrlEncode($订单报表_{DateTime.Now:yyyyMMdd}.xlsx); return File(bytes, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, fileName); }中文文件名不处理的话某些浏览器下载下来是乱码。用UrlEncode处理一下绝大多数现代浏览器都能正确识别。5. 常见问题与排查技巧实录JSON导出Excel这个功能代码看起来简单但实际问题五花八门。我把这些年遇到的高频问题整理成一张速查表你遇到类似情况可以直接对照。5.1 高频问题速查表现象可能原因处理方式打开Excel提示“文件格式或扩展名无效”生成的不是真xlsx是HTML或文本改了扩展名检查输出文件确认是组件生成的xlsx导出文件打不开提示XML错误写入过程中对流的位置处理错误文件截断SaveAs之前确保流可写不要重复保存同一个流中文乱码使用了CSV或文本方案编码不对改用组件生成xlsxCSV场景用带BOM的UTF-8长数字变成科学技术法Excel自动识别为数值该列单元格数字格式设为文本日期单元格显示####列宽不够调大列宽或AutoFitJSON字段名和表头对不上大小写不一致或属性映射缺失统一走映射字典或JsonProperty特性数据量大时OOM整个工作簿都驻留内存分批写入、考虑OpenXML流式下载文件名乱码Content-Disposition编码问题对文件名做UrlEncode处理5.2 最容易误判的“JSON格式不对”问题有个坑我印象特别深。接口返回的JSON根本不是一个数组而是包了一层对象比如{code:0,data:[...]}。直接JArray.Parse(jsonString)会抛异常说不能从JsonReader读取。很多人第一反应是JSON坏了其实只是入口选错了。正确做法是先解析成JObject再取data字段作为数组var jsonObj JObject.Parse(jsonString); var jArray (JArray)jsonObj[data];这背后其实是个习惯问题对接接口前先花一分钟看一下整个JSON的结构再决定从哪一层开始解析。我之前图省事直接解析结果线上导出功能突然报错排查半天才发现是接口方在返回外层加了状态码字段。5.3 导出文件损坏的排查思路用户反馈“Excel打开就提示文件已损坏”的时候我有一套固定的排查顺序第一步确认后端返回的文件是不是用组件生成的还是用文本拼的。第二步检查响应流有没有先Seek(0, SeekOrigin.Begin)再输出。第三步确认有没有在同一个函数里重复SaveAs到同一个流。第四步看是不是多线程同时写同一个文件导致文件被截断。这四个步骤解决了我遇到过的九成“文件损坏”问题。尤其是第四步在导出量大的系统里多个用户同时点击导出如果代码里用了全局唯一的临时文件名很容易互相覆盖。5.4 不要忽略空数组和空值当JSON数组为空时动态列生成的代码可能压根进不了循环导致Excel文件里没有表头只有一片空白。我一般在解析完成后判断一下columns.Count 0直接提示“没有可导出的数据”避免生成一个空文件让用户困惑。另外JSON里的null值ToString会变成字符串null看起来特别蠢。正确的处理方式是判断JTokenType.Null后赋值为null或空字符串我倾向前者因为空单元格比显示null更符合业务习惯。6. 从“能导出”到“很好用”的扩展思路基本的动态导出跑通之后你会发现需求永远不止于此。这里分享几个我后来陆续加上的扩展能力正好也是从“能用”到“好用”的关键。6.1 模板导出提前定好样式很多企业需要固定的导出格式比如表头Logo、特定配色、固定列宽。如果每次都在代码里写样式维护成本很高。更好的方式是准备一个Excel模板文件里面把样式、列宽、表头都画好导出时用EPPlus加载模板using var templateStream File.OpenRead(export_template.xlsx); using var package new ExcelPackage(templateStream); var ws package.Workbook.Worksheets[0]; // 直接从指定行开始填充数据这样做的好处是样式调整可以由业务人员直接改模板不用动代码。要注意的是模板里的合并单元格、公式等特殊结构填充数据时要额外小心别把公式区域覆盖了。6.2 多Sheet导出按数据源分页分类当数据本身有分类维度比如按部门导员工表、按月份导订单表一个Sheet全塞进去用户找不到重点也容易让Excel卡顿。按分组循环创建多个Worksheet就很好用foreach (var group in groups) { var ws package.Workbook.Worksheets.Add(group.Name); FillSheet(ws, group.Data); }每页Sheet数据量控制在合理范围比如5万行以内用户打开的时候也不会等太久。6.3 配置化列映射动态表头的好搭档如果你做的系统里多个导出页面都用同一个通用组件列映射字典建议从配置文件或数据库读取而不是硬编码在代码里。这样业务方自己也能力调整导出列不用每次让你发版。配置化之后动态解析、模板导出、多Sheet、配置映射四个能力组合起来基本就是一个通用的Excel导出中间件了。后面再碰到“这个JSON导Excel”的需求我基本就是把jArray扔给这个组件三行代码解决问题。这种收益前面铺垫越早做完后面项目越省心。最后再分享一点个人体会。做导出功能不要一上来就写代码先把数据形态看清楚JSON是数组还是对象字段会不会变嵌套深不深数据量大致多少这一分钟的判断决定了你选哪套方案也会直接影响后面会不会返工。我自己就是在这些看似“简单”的功能上反复踩坑才慢慢把这些经验沉淀下来的。希望这套思路也能帮你少走几段弯路。