简介：本资源是一套基于C#与EPPlus库的Excel（.xlsx）文件操作封装方案，面向.NET开发者及数据处理相关技术人员，解决高频Excel读写、图表自动化生成等实际开发痛点，尤其适用于报表系统、数据分析工具及后台导出模块开发。压缩包共315个文件，含75个DLL（核心依赖与封装类库）、8个C#源码文件（含读取、写入及折线图/曲线图生成逻辑）、48个隐藏配置文件（_开头，支撑环境适配）、25个TXT说明文档（含API用法与调用示例），整体35.67MB，结构完整、即拿即用。已有132人学习下载，资源中封装方法接口清晰、异常处理完备，并已预置2个示例.xlsx文件用于效果验证，配套CSProj与SLN工程可直接编译运行，大幅降低EPPlus入门门槛与二次开发成本。
1. C#用EPPlus操作XLSX：不是调个NuGet包就完事，读写+图表生成全链路踩坑实录
你是不是也试过：NuGet装上EPPlus，照着官网示例读个Excel，数据能出来；但一加图表——Chart对象创建成功，保存后打开Excel却提示“文件已损坏”？或者写入10万行数据时内存飙到2GB，GC卡顿到UI假死？又或者导出的折线图在WPS里显示正常，但在某版本Office里图例消失、坐标轴错位？这不是玄学，是EPPlus在XLSX底层结构、Open XML规范兼容性、以及C#对象生命周期管理上的真实水位线。本文不讲“EPPlus是什么”，只聚焦一个硬需求：在生产环境稳定完成XLSX的读取、写入、动态生成折线图/曲线图三件套。适合正在做报表导出、数据看板、自动化报告生成的.NET开发者——尤其当你被测试提了“导出的Excel在客户电脑打不开”这类工单时，这篇就是你的后悔药。所有代码基于EPPlus 6.2.10（当前稳定主力版），适配.NET 6/7/8，不依赖Office进程，纯内存操作。
2. 从零搭起EPPlus XLSX操作骨架：初始化、读取、写入三步闭环
EPPlus不是Excel的封装，而是Open XML SDK的高层抽象。它绕过了COM互操作的性能黑洞和部署噩梦，但代价是必须理解.xlsx本质：一个ZIP包，里面包含xl/worksheets/sheet1.xml（单元格数据）、xl/charts/chart1.xml（图表定义）、xl/styles.xml（样式）等部件。EPPlus帮你自动组装这些XML，但一旦你跳过它的约定，就会掉进黑匣子。
2.1 初始化与安全配置：别让LicenseError毁掉第一次运行
EPPlus 5.x起引入商业许可，但开源版（EPPlus.Core已停更）已被EPPlus 5+免费版替代，只需一行代码激活：
// 必须在应用启动时（如Program.cs或Global.asax）执行一次 ExcelPackage.LicenseContext = LicenseContext.NonCommercial; // 开发/学习用 // 或 LicenseContext.Commercial; // 生产商用需购买许可证提示：
NonCommercial仅限个人学习、内部非分发系统。若项目打包给客户或SaaS部署，必须购商业授权，否则运行时抛EPPlusException且无明确提示——这是血泪经验：某次UAT环境突然报错，查了3小时才发现测试服务器没设LicenseContext。
2.2 安全读取XLSX：避开空行、合并单元格、日期格式三大陷阱
读取不是worksheet.Cells["A1"].Value这么简单。真实业务表常含标题行、空行、跨列合并单元格，直接遍历会漏数据或崩溃：
using (var package = new ExcelPackage(new FileInfo("input.xlsx"))) { var worksheet = package.Workbook.Worksheets[0]; // ✅ 正确做法：用Dimensions获取实际数据范围（排除空行空列） if (worksheet.Dimension == null) throw new InvalidOperationException("工作表为空"); int rowCount = worksheet.Dimension.Rows; int colCount = worksheet.Dimension.Columns; // ✅ 处理合并单元格：读取时自动取左上角值，但需手动补全逻辑 var data = new List<List<object>>(); for (int row = 1; row <= rowCount; row++) { var rowData = new List<object>(); for (int col = 1; col <= colCount; col++) { var cell = worksheet.Cells[row, col]; // ⚠️ 关键：合并单元格中非主单元格返回null，需向上/向左找值 object value = cell.Value; if (value == null && cell.Merged) { // 找合并区域左上角单元格 var mergedRange = worksheet.MergedCells.FirstOrDefault(m => m.Start.Row <= row && m.End.Row >= row && m.Start.Column <= col && m.End.Column >= col); if (mergedRange != null) value = worksheet.Cells[mergedRange.Start.Row, mergedRange.Start.Column].Value; } rowData.Add(value); } data.Add(rowData); } }参数说明：
worksheet.Dimension是EPPlus解析出的实际有值区域边界，比UsedRange更可靠（后者可能包含格式化但无值的单元格）。cell.Merged仅表示该单元格属于合并区域，不保证它是主单元格；必须用MergedCells集合反查归属。- 日期读取默认为
DateTime，但若源Excel存为文本型日期（如"2023-01-01"），cell.Value返回string，需自行DateTime.TryParse——这是90%日期解析失败的根源。
2.3 高效写入XLSX：百万行不卡顿的核心是禁用自动计算与样式缓存
写入性能瓶颈常在worksheet.Cells[row, col].Value = xxx的逐单元格赋值。EPPlus提供批量写入接口，但需配合关键配置：
using (var package = new ExcelPackage()) { var worksheet = package.Workbook.Worksheets.Add("Data"); // ✅ 关键性能开关：关闭自动公式计算（写入时不触发重算） worksheet.CalculateMode = CalculateMode.Manual; // ✅ 关键性能开关：禁用样式自动缓存（避免重复样式对象爆炸） worksheet.StyleID = -1; // 强制使用默认样式 // ✅ 批量写入：用二维数组代替循环赋值（快5倍以上） var data = new object[100000, 5]; // 10万行×5列 for (int i = 0; i < 100000; i++) { data[i, 0] = $"ID-{i}"; data[i, 1] = DateTime.Now.AddDays(i % 30); data[i, 2] = i * 1.5; data[i, 3] = $"Category-{i % 10}"; data[i, 4] = i % 2 == 0 ? "Active" : "Inactive"; } worksheet.Cells["A1"].LoadFromArrays(new[] { data }); // 一次性载入 // ✅ 写入后手动触发计算（如需结果） // worksheet.Calculate(); package.SaveAs(new FileInfo("output.xlsx")); }为什么这样写：
CalculateMode.Manual防止每写入一个含公式的单元格就重算全表，对大数据量是刚需。StyleID = -1避免EPPlus为每个单元格创建独立ExcelStyle对象，内存占用直降70%。LoadFromArrays底层调用Open XML的SheetData批量写入，比Cells[row,col].Value减少90%的XML节点操作。
3. EPPlus生成折线图与曲线图：从XML结构到坐标轴精调的完整路径
EPPlus的图表API是其最易翻车的模块——表面看worksheet.Drawings.AddChart很友好，但背后是Open XML中<c:chart>、<c:plotArea>、<c:lineChart>等嵌套XML的硬编码。稍有不慎，Excel就报“无法读取此文件”。
3.1 创建基础折线图：数据绑定与系列命名的强制约定
EPPlus要求图表数据必须来自工作表中的连续区域（不能是离散单元格），且首行必须为系列名称（Legend），首列为X轴标签（Categories）：
// 假设数据已写入A1:E1001（A列为时间，B-E列为4个指标） var chart = worksheet.Drawings.AddChart("LineChart", eChartType.Line); chart.SetPosition(5, 0, 10, 0); // 行偏移5，列偏移0；宽10列，高0行（自适应） chart.SetSize(600, 400); // ✅ 数据绑定：必须指定Series区域（B1:E1001），且B1:E1为系列名，A2:A1001为X轴 var series1 = chart.Series.Add(worksheet.Cells["B2:B1001"], worksheet.Cells["A2:A1001"]); series1.HeaderAddress = worksheet.Cells["B1"]; // 指定系列名单元格 var series2 = chart.Series.Add(worksheet.Cells["C2:C1001"], worksheet.Cells["A2:A1001"]); series2.HeaderAddress = worksheet.Cells["C1"]; // ✅ 关键：必须设置X轴类型为文本（Text），否则时间序列会变成数字轴 chart.XAxis.Type = eAxisType.Text; chart.XAxis.MajorTickMark = eTickMark.None; // 隐藏X轴刻度线，避免拥挤为什么X轴必须设为Text：
若A列是DateTime，EPPlus默认将X轴设为Date类型，但Excel渲染时会强制按日粒度分组，导致2023-01-01、2023-01-02间出现空白。设为Text后，X轴按A列原始字符串值显示，完美保留时间精度。
3.2 曲线图（平滑折线）实现：修改底层XML的唯一可靠方式
EPPlus API不暴露smooth属性（即曲线是否平滑），官方文档也未说明。但Open XML标准中，<c:lineChart>下<c:smooth val="1"/>即可开启平滑。必须通过XmlWriter注入：
// 在AddChart后，获取图表XML并注入smooth节点 var chartXml = chart.ChartXml; var ns = chartXml.NamespaceNamespaces; var smoothNode = chartXml.CreateElement("c", "smooth", ns["c"]); smoothNode.SetAttribute("val", "1"); // 找到<c:lineChart>节点并插入smooth var lineChartNode = chartXml.SelectSingleNode("//c:lineChart", chartXml.CreateNavigator().NameTable); if (lineChartNode != null) { lineChartNode.AppendChild(smoothNode); }验证方法：保存文件后，改后缀为.zip，解压进入xl/charts/chart1.xml，搜索<c:smooth确认存在且val="1"。
3.3 图表样式精调：坐标轴、图例、网格线的不可见陷阱
EPPlus的chart.YAxis、chart.Legend等对象看似可配置，但部分属性（如Y轴最小值）需满足Open XML约束，否则静默失效：
// ✅ Y轴最小值设置（必须同时设最大值，否则无效） chart.YAxis.MinValue = 0; chart.YAxis.MaxValue = 100; // ✅ 图例位置：eLegendPosition.Bottom是唯一稳定选项 chart.Legend.Position = eLegendPosition.Bottom; // ✅ 网格线：必须先启用主网格线，再设样式 chart.YAxis.MajorGridLines.Enabled = true; chart.YAxis.MajorGridLines.Color = Color.FromArgb(220, 220, 220); // 浅灰 chart.YAxis.MajorGridLines.Width = 1; // ⚠️ 警告：chart.XAxis.MajorGridLines.Enabled = true 会导致Excel报错！ // 原因：X轴为Text类型时，Open XML不支持网格线，必须禁用 chart.XAxis.MajorGridLines.Enabled = false;避坑原理：Open XML规范中，<c:catAx>（分类轴，即X轴）的<c:majorGridlines>是可选元素，但Excel实现强制校验其存在性。当X轴为Text类型时，Excel解析器遇到<c:majorGridlines>直接拒绝加载图表。而<c:valAx>（数值轴，Y轴）则完全支持。
4. EPPlus图表生成的5个致命避坑指南：现象、原因、解决全还原
EPPlus图表模块的坑，90%源于Open XML规范与Excel客户端渲染引擎的差异。以下是我在线上系统踩过的真坑，按发生频率排序：
4.1 现象：图表保存后Excel提示“发现错误，是否恢复？”→点击恢复后图表消失
原因：图表数据区域引用了不存在的单元格（如B2:B1001但实际只有100行），或X轴区域与系列区域行数不匹配（如X轴A2:A100共99行，系列B2:B101共100行）。
解决：严格校验worksheet.Cells[range].Value是否为null，用worksheet.Dimension动态计算实际行数，而非硬编码。添加断言：
Debug.Assert(xAxisRange.Rows == seriesRange.Rows, $"X轴行数({xAxisRange.Rows})与系列行数({seriesRange.Rows})不匹配");4.2 现象：图表在Windows版Excel显示正常，Mac版Excel图例文字错位、坐标轴标签截断
原因：Mac版Excel对<c:txPr>（文本属性）的vert（垂直对齐）和anchor（锚点）解析更严格，EPPlus默认值eTextAnchoringType.Top在Mac下失效。
解决：强制设置图例文本锚点为eTextAnchoringType.Center：
chart.Legend.TextAnchoring = eTextAnchoringType.Center;4.3 现象：生成的曲线图（smooth=1）在WPS中显示为直线
原因：WPS 2019及更早版本不支持Open XML的<c:smooth>标签，将其忽略后回退为折线。
解决：检测客户端环境（通过HTTP User-Agent或前端JS），对WPS用户降级为普通折线图，并在图表标题注明“WPS兼容模式”。
4.4 现象：图表导出后，Y轴数值显示为科学计数法（如1E+06），而非1,000,000
原因：EPPlus未自动应用数字格式，Y轴默认使用Excel内置格式ID 0（常规），对大数自动转科学计数。
解决：手动设置Y轴数字格式：
chart.YAxis.NumberFormat.Format = "#,##0"; // 千分位 // 或 chart.YAxis.NumberFormat.Format = "0.00%"; // 百分比4.5 现象：多图表工作表保存后，第二个图表坐标轴刻度线消失
原因：EPPlus复用<c:axId>（坐标轴ID）时冲突，导致第二个图表的<c:valAx>被第一个覆盖。
解决：为每个图表显式设置唯一ID（需反射调用内部方法）：
// 通过反射设置Chart对象的m_chartId字段（EPPlus 6.2.10） var chartField = chart.GetType().GetField("m_chartId", BindingFlags.NonPublic | BindingFlags.Instance); chartField?.SetValue(chart, Guid.NewGuid().GetHashCode());注意：此方案依赖EPPlus内部实现，升级版本前务必回归测试。更稳妥的做法是每个图表单独存为不同工作表。
5. 生产级验证与调试技巧：用Open XML SDK反向校验EPPlus输出
当EPPlus生成的XLSX在客户环境异常，不要猜——用Open XML SDK直接读取生成文件的XML，定位问题根源。这是我在某金融报表系统上线前的标准动作。
5.1 快速提取图表XML：定位渲染失败的精确节点
// 用Open XML SDK打开EPPlus生成的文件，提取chart1.xml using (var doc = SpreadsheetDocument.Open("output.xlsx", false)) { var chartPart = doc.WorkbookPart.GetPartsOfType<ChartPart>() .FirstOrDefault(p => p.Uri.ToString().Contains("chart1")); if (chartPart != null) { var xml = chartPart.ChartSpace.OuterXml; // 搜索关键节点：<c:lineChart>, <c:smooth>, <c:catAx> Console.WriteLine($"Smooth exists: {xml.Contains("<c:smooth")}"); Console.WriteLine($"XAxis type: {Regex.Match(xml, @"<c:catAx>.*?<c:axId val=""(\d+)"">").Groups[1].Value}"); } }调试价值：
- 若
<c:smooth>不存在，证明EPPlus的XML注入失败（检查chart.ChartXml是否被其他操作覆盖）。 - 若
<c:catAx>的axId与<c:valAx>相同，说明坐标轴ID冲突（对应避坑4.5）。
5.2 自动化图表健康检查：封装成CI流水线环节
将上述XML校验封装为.NET Core命令行工具，在Jenkins/GitLab CI中作为导出功能的准入检查：
// ChartValidator.cs public static bool ValidateChart(string xlsxPath, string expectedChartType = "line") { using var doc = SpreadsheetDocument.Open(xlsxPath, false); var chartPart = doc.WorkbookPart.GetPartsOfType<ChartPart>().FirstOrDefault(); if (chartPart == null) return false; var xml = chartPart.ChartSpace.OuterXml; return xml.Contains($"<c:{expectedChartType}Chart>") && xml.Contains("<c:smooth val=\"1\"") == (expectedChartType == "line" && IsSmoothRequired()); }落地效果：某次EPPlus升级到6.2.10后，CI检测到<c:smooth>节点丢失，立即回滚，避免故障上线。
5.3 终极技巧：用Excel Formula Auditing反向追踪数据源
当客户说“图表数据不对”，但EPPlus代码逻辑清晰——此时问题常在数据源本身。用Excel的“公式审核”功能：
- 打开生成的XLSX → 选中图表 → “图表设计”选项卡 → “选择数据”
- 查看“图例项（系列）”和“水平（分类）轴标签”引用的单元格地址
- 按
Ctrl+[跳转到对应单元格，检查是否被其他公式覆盖或格式错误
我的习惯：在EPPlus写入数据后，主动在工作表末尾添加诊断信息：
worksheet.Cells["Z1"].Value = "DEBUG: Chart Data Range = B2:B" + (rowCount + 1); worksheet.Cells["Z2"].Value = "X-Axis Range = A2:A" + (rowCount + 1);这样客户反馈问题时，我能秒级定位数据范围是否正确。
希望帮到你。
本文还有配套的精品资源，点击获取
