简介面向.NET开发者的OpenXml读写Excel实例代码资源重点演示在完全不安装Microsoft Office的前提下利用DocumentFormat.OpenXml库操作xlsx格式文件。资源以PDF文档呈现给出完整的C#代码示例覆盖从Excel导入数据到DataTable、将DataTable导出为Excel、创建并应用单元格样式等核心环节同时包含对共享字符串、数字与布尔值等单元格数据类型的处理逻辑。压缩包仅1个文件类型为PDF整体大小约50KB内容精简便于随时查阅。该资源现有565人学习浏览特别适合需要在服务端自动化生成报表、批量处理表格数据的开发者也适合希望深入理解OpenXml底层结构的读者。通过这份实例可以快速提取可复用的读写方法减少摸索时间直接嵌入到实际项目中。1. 不装 Office 也能写 ExcelOpenXml 读写 Excel 的实战入口很多第一次接触 OpenXml 的人听到“读 Excel 还要先搞懂 zip 里的 XML”都会皱眉我直接用 Excel 自动化不就行了但实际做过服务端报表的人都知道批量生成 .xlsx 时最怕的就是环境里有 Office、COM 组件掉链子、加载项被禁用这类黑匣子问题。OpenXml 的底气在于xlsx 本质是一个 zip 压缩包里面的 sheet、样式、共享字符串都是 XMLDocumentFormat.OpenXml 这个官方 SDK 就是让 .NET 程序直接操作这些 XML不拉起 Excel 进程。你可以在 Windows、Linux 容器里跑同一个导出任务Excel 加载项被禁用、宏安全设置、Office 版本差异这些事统统与你无关。这篇笔记把 OpenXml 读写 Excel 的最小可运行代码、参数细节和五个典型翻车点一次讲透适合被 Excel 自动化折磨过的 .NET 后端开发也适合要批量生成报表的运维和数据处理同学。2. 拆开 xlsx 看结构读写在动手前必须先懂这张部件图2.1 xlsx 的真实身份一个按 OOXML 规范打包的 zip我常说做 OpenXml 读写如果不知道文件物理结构写出来的代码就是碰运气。新建一个空白的 .xlsx用任意解压工具打开你会看到[Content_Types].xml、_rels/.rels、xl/workbook.xml、xl/worksheets/sheet1.xml、xl/styles.xml、xl/sharedStrings.xml这几个文件它们各司其职部件文件在 SDK 中对应的类作用与读写注意点xl/workbook.xmlWorkbook顶层入口记录所有 Sheet 的清单、计算属性、定义名称xl/worksheets/sheetN.xmlWorksheet真正存数据的SheetData包含行、单元格、合并单元格xl/sharedStrings.xmlSharedStringTable共享字符串表重复文本只存一份单元格里写的是索引xl/styles.xmlStylesheet字体、填充、边框、数字格式、单元格格式的集合xl/rels/workbook.xml.rels关系文件Sheet 与 WorksheetPart、样式与样式部件之间的映射[Content_Types].xml内容类型声明每个部件必须有对应的 content type缺失则文件打不开理解这个结构后读写套路就清晰了读是“打开包 → 找 WorkbookPart → 通过关系拿 WorksheetPart → 解析 SheetData”写是“创建包 → 建 WorkbookPart → 挂 WorksheetPart → 往 SheetData 塞 Rows”。SDK 把 zip 和 XML 序列化都封装掉了但部件之间的关系Relationship你得亲手处理最常见的错误就是把数据写进了一个孤立部件没有挂到工作簿的关系链上结果 Excel 打开报错。一个小例子一个只含“你好”的 sheet1.xml 长这样worksheet xmlnshttp://schemas.openxmlformats.org/spreadsheetml/2006/main sheetData row r1 c rA1 tinlineStr ist你好/t/is /c /row /sheetData /worksheet注意这里tinlineStr表示字符串直接写在单元格里不走共享字符串表。很多初学 OpenXml 的同学写字符串不设DataType直接把文本塞进CellValue结果 Excel 打开时把“123ABC”当数字解析失败。类型属性DataType是 OpenXml 读写里最容易踩的坑后面会专门展开。2.2 选型对比OpenXml、COM 与 NPOI 到底该用谁常见做法是在 .NET 里做 Excel 读写通常有三条路COM 组件调用 Excel 自动化、NPOI 或 EPPlus 这类封装库、以及官方 OpenXml SDK。我自己做选型时的判断表是这样方案环境依赖服务端适用性主要风险COM / Interop必须装 Office且 Windows 环境差进程残留、权限问题、加载项被禁用时直接失败并发导出容易把 Excel 进程拖死NPOI无 Office 依赖纯托管较好老牌库API 顺手对图表、图片、复杂样式支持弱某些版本对xlsx的流式写支持有限OpenXml SDK无 Office 依赖跨平台好API 偏底层需要懂 xlsx 结构但可控性最强不会忽然弹出“文件已损坏”如果你的需求只是把DataTable导出成简单表格NPOI 确实更快但涉及公式、合并单元格、打印区域、图片锚点、自定义样式这些复杂特性或者要在 Linux 容器里跑定时任务OpenXml SDK 几乎是唯一不出幺蛾子的选择。它不碰注册表、不开 Office 进程自然也不会触发“excel 加载项被禁用”这类环境投诉。我一般还会提醒同事EPPlus 新版有商业授权限制公司项目用之前先看许可证OpenXml SDK 是官方维护没有这个顾虑。2.3 项目引用与最小上下文从 NuGet 到命名空间在 Visual Studio 或 CLI 里安装 NuGet 包DocumentFormat.OpenXml项目会自动引入两个核心命名空间DocumentFormat.OpenXml元素基类、枚举和DocumentFormat.OpenXml.Packaging包、Part 的抽象另外还有一个DocumentFormat.OpenXml.Spreadsheet它里面才是Workbook、Worksheet、Row、Cell这些业务类。很多人困惑“为什么我的Worksheet和Cell找不到”就是少了第三个 using。写代码前先把这三个 using 摆齐using DocumentFormat.OpenXml; using DocumentFormat.OpenXml.Packaging; using DocumentFormat.OpenXml.Spreadsheet;这之后你的所有 Excel 对象都会以“部件Part”的形式存在比如WorkbookPart、WorksheetPart、WorkbookStylesPart。部件可以理解为 zip 里的一个文件SDK 的职责就是把这些文件变成强类型对象让你像操作 DOM 一样操作 Excel。但记住SDK 不是 Excel它不做自动重算、不做排版优化只忠实地按规范读写 XML——不理解这一点后面遇到“公式打开不计算”“样式丢了”时就会一头雾水。3. 用 OpenXml 写 Excel从空文件到带样式公式的报表3.1 最小写实例从 WorkbookPart 到 Cell 的完整链路先跑通一个最小写例子再谈别的。下面这段代码生成一个demo.xlsx只有一个工作表里面写了两行数据using var doc SpreadsheetDocument.Create(demo.xlsx, SpreadsheetDocumentType.Workbook); var workbookPart doc.AddWorkbookPart(); workbookPart.Workbook new Workbook(); var sheets workbookPart.Workbook.AppendChild(new Sheets()); var sheetPart workbookPart.AddNewPartWorksheetPart(); sheetPart.Worksheet new Worksheet(new SheetData()); var sheetData sheetPart.Worksheet.GetFirstChildSheetData(); sheetData.AppendChild(new Row( new Cell { DataType CellValues.InlineString, CellValue new CellValue(姓名) }, new Cell { DataType CellValues.InlineString, CellValue new CellValue(部门) } )); sheetData.AppendChild(new Row( new Cell { CellValue new CellValue(1001) }, new Cell { DataType CellValues.InlineString, CellValue new CellValue(研发部) } )); var sheet new Sheet { Id workbookPart.GetIdOfPart(sheetPart), SheetId 1, Name 人员清单 }; sheets.AppendChild(sheet); doc.Save();逻辑说明SpreadsheetDocument.Create负责创建 zip 包的骨架并生成[Content_Types].xmlAddWorkbookPart创建workbook.xml随后AddNewPartWorksheetPart()创建sheet1.xml并自动建立关系workbookPart.GetIdOfPart(sheetPart)拿到的是关系文件里的 Id这个 Id 必须写进Sheet元素Excel 才能找到对应工作表。最后doc.Save()不写会丢数据。参数说明CellValues.InlineString是直接把字符串写进单元格的最稳妥方式适合数据量小、不追求压缩的场景数值单元格不需要设DataType默认按数字处理1001会写成c rB2v1001/v/c。注意Row构造器里Cell的顺序就是列顺序SDK 不会帮你排序B列写前A列写后会导致 schema 校验失败Excel 打开会提示“文件错误”。3.2 样式与格式默认样式缺失是最常见的“文件已损坏”元凶很多人写完最小实例后开始加字体、背景色、边框然后发现 Excel 打开报“文件已损坏是否要修复”。原因通常是样式表里没有满足 OOXML 规范的最小元素集。一个合法的Stylesheet至少要有一个空Font、两个Fill第二个必须是Gray125、一个空Border、一个默认CellFormat。代码是这样var stylesPart workbookPart.AddNewPartWorkbookStylesPart(); var fonts new Fonts(); fonts.AppendChild(new Font()); // 默认字体 var fills new Fills(); fills.AppendChild(new Fill()); // 默认填充 fills.AppendChild(new Fill(new PatternFill { PatternType PatternValues.Gray125 })); // 灰色125规范要求 var borders new Borders(); borders.AppendChild(new Border()); // 默认无边框 var cellFormats new CellFormats(); cellFormats.AppendChild(new CellFormat()); // 默认格式索引为 0 stylesPart.Stylesheet new Stylesheet(fonts, fills, borders, cellFormats); stylesPart.Stylesheet.Save();逻辑说明所有自定义样式都往这个Stylesheet里追加。比如想要一个“黑体 11 号、黄色填充、细边框”的单元格格式就先AppendChild新的 Font、Fill、Border再追加一个CellFormat它的FontId、FillId、BorderId指向前面追加元素的索引然后把得到的CellFormat索引赋给Cell.StyleIndex。这里索引从 0 开始顺序错一个就全花。参数说明Cell.StyleIndex是UInt32Value直接在代码里写uint会被隐式转换。真正调样式时我习惯先把想要的样式注册进Stylesheet返回索引存到一个字典里后面写单元格时从字典取StyleIndex避免每个单元格都注册一次样式——那会让 styles.xml 膨胀到几十 MB。另外数字格式比如保留两位小数要加NumberingFormats和带NumberFormatId的CellFormat这属于进阶参数等报表要出精度时再回来调。3.3 公式、合并单元格与打印设置一次写全开会话报表常见的三个需求合计行公式、标题跨列合并、打印区域控制。三者代码可以一次写进同一个Worksheet// 假设 B2:B11 是数值B12 写合计 var sumCell new Cell { CellFormula new CellFormula(SUM(B2:B11)), CellValue new CellValue(0) }; // 合并单元格第一行前两列合并做标题 var mergeCells new MergeCells { Count 1 }; mergeCells.AppendChild(new MergeCell { Reference A1:B1 }); sheetPart.Worksheet.Append(mergeCells); // 打印设置横向、一页宽、页边距 var pageSetup new PageSetup { Orientation OrientationValues.Landscape, FitToWidth 1, FitToHeight 1 }; sheetPart.Worksheet.Append(pageSetup);逻辑说明MergeCells必须追加在SheetData之后这是 OOXML 的元素顺序要求顺序反了会让文件校验失败。PageSetup同理XML schema 对worksheet内部元素的出现顺序有严格规定SheetData、MergeCells、PageSetup依次排列。用 SDK 时我用Append总是先查一下元素顺序最稳妥的做法是打开任意一个真实 Excel 文件看它的 XML 标签顺序。参数说明公式串里可以写SUMIFS、COUNTIF这些多条件函数OpenXml 对公式文本不做解释原样写入最终计算由 Excel/WPS 打开时执行。FitToWidth 1跟打印时“将所有列调整到一页宽”对应热词里常见的“excel 打印”问题很大程度是靠这个参数解决的。注意公式单元格里我顺手写了CellValue(0)作为缓存值否则有些版本的 Excel 在未加载计算链时会显示空白这里也算一个预防性写法。3.4 日期、文本类型与字符编码希腊字母、UUID 都能直写写入字符串最稳妥的方式是InlineString但它有一个代价每个单元格都带完整 XML 文本重复内容多时文件偏大。对大量重复文本应该用共享字符串表var sharedStringTable workbookPart.AddNewPartSharedStringTablePart(); var sharedItems new Liststring { 研发部, 市场部, 运维部 }; sharedStringTable.SharedStringTable new SharedStringTable(); foreach (var item in sharedItems) { sharedStringTable.SharedStringTable.AppendChild(new SharedStringItem(new Text(item))); } // 单元格写法DataType CellValues.SharedStringCellValue 写索引 new Cell { DataType CellValues.SharedString, CellValue new CellValue(0) }逻辑说明共享字符串表里存一份文本单元格存索引文件体积可以显著下降。但要注意索引必须和表内顺序一致否则读出来串行。参数说明日期是另一个高频坑。OpenXml 没有专门的日期类型规范要求把日期转成 OADate1899-12-30 为基准的序列数写入数字单元格然后通过样式里的NumberFormatId让它显示成日期。常见做法是DateTime.ToOADate()后用代码生成一个带数字格式的样式这也解释了为什么“写日期”在 OpenXml 里比想象中麻烦。文本编码方面希腊字母、中文、UUID 这类内容都是普通 UTF-8 字符串CellValue直接写就行不需要特殊转义SDK 做序列化时会处理 XML 转义真正要留意的是不要自己手拼 XML手拼时、、容易漏转导致文件损坏。UUID 写入时我一般先ToString()再写不用Guid直接传给CellValue保持类型清晰。4. 用 OpenXml 读 Excel逐行读与五个现场排查4.1 小文件 DOM 读法先拿 SharedStringTable 再取单元格读取小文件几千行以内用 DOM 最直观。核心是先拿到共享字符串表再遍历每行每格按DataType决定怎么取值using var doc SpreadsheetDocument.Open(demo.xlsx, false); var workbookPart doc.WorkbookPart; if (workbookPart null) return; var sharedStringTable workbookPart.SharedStringTablePart?.SharedStringTable; var sheet workbookPart.Workbook.DescendantsSheet().First(); var worksheetPart workbookPart.GetPartById(sheet.Id!) as WorksheetPart; if (worksheetPart null) return; foreach (var row in worksheetPart.Worksheet.DescendantsRow()) { foreach (var cell in row.ElementsCell()) { var value GetCellValue(cell, sharedStringTable); Console.WriteLine(${cell.CellReference} {value}); } } static string? GetCellValue(Cell cell, SharedStringTable? sharedStrings) { if (cell.CellValue null) return null; if (cell.DataType ! null cell.DataType.Value CellValues.SharedString) { var index int.Parse(cell.CellValue.Text); return sharedStrings?.ElementAt(index).InnerText; } return cell.CellValue.Text; }逻辑说明SharedStringTablePart可能为空你在前面写过 3.1 的InlineString文件就没有这个部件所以不能假设它一定存在。GetPartById(sheet.Id)根据工作簿里的关系 Id 拿到具体工作表部件这个 Id 在写入时是GetIdOfPart生成的读取时按同样的关系链反查。参数说明SpreadsheetDocument.Open第二个参数false表示只读打开不要为读操作开启可写模式否则文件会被独占锁住服务端并发场景直接报“文件正由另一进程使用”。读InlineString单元格时DataType不是SharedString代码走最后的CellValue.Text分支即可。另外空白单元格在 XML 里可能是一个没有v标签的cCellValue为 null取值时需要判空不要直接.Text。4.2 大数据量读法用 OpenXmlReader 避免内存爆炸读 10 万行 Excel 如果仍然用DescendantsRow()整个 XML DOM 会一次性进内存观察任务管理器会发现内存冲到 1GB 以上。SDK 提供了另一个 APIOpenXmlReader它的特点是只读取节点标签需要某一行时才真正反序列化那一行using var doc SpreadsheetDocument.Open(big.xlsx, false); var worksheetPart doc.WorkbookPart!.WorksheetParts.First(); var buffer new ListRow(); using (var reader OpenXmlReader.Create(worksheetPart.Worksheet)) { while (reader.Read()) { if (reader.ElementType typeof(Row)) { var row (Row)reader.LoadCurrentElement(); buffer.Add(row); if (buffer.Count 5000) { ProcessRows(buffer); // 批量处理然后释放 buffer.Clear(); } } } } if (buffer.Count 0) ProcessRows(buffer);逻辑说明OpenXmlReader.Create接收的是Worksheet对象但只创建读取器不加载全部内容LoadCurrentElement()只把当前这个Row反序列化成对象处理完就可以丢弃。这就是它与 DOM 读法的本质区别内存占用从 O(总行数) 降为 O(批大小)。参数说明5000 这个批大小不是固定值取决于每行单元格数和后续业务处理耗时。批太小则频繁ProcessRows批太大会让buffer占内存我一般以 200~500 MB 内存为界来调。更极端的大文件可以放弃 SDK 的Row对象直接用XmlReader解析Worksheet的流但那样要自己处理命名空间和类型转换得不偿失我一般先试OpenXmlReader。4.3 排查写入后 Excel 提示“文件已损坏”现象自己用 OpenXml 生成的 xlsx双击打开时弹出黄色警告“文件已损坏是否要修复”点修复后又正常显示。原因绝大多数是三种情况之一Stylesheet缺少默认 Font/Fill/Border见 3.2MergeCells或PageSetup元素顺序放错或者Sheet的关系 Id 与实际的 Part 关系不匹配。解决先写个单元测试用OpenXmlValidator做 schema 校验落盘前就把问题暴露出来而不是等用户打开时才发现var validator new OpenXmlValidator(); var errors validator.Validate(workbookPart).ToList(); foreach (var error in errors) { Console.WriteLine(${error.Path?.XPath} : {error.Description}); }这个验证器会逐条对照 OOXML schema 报告“元素 X 出现在错误位置”“属性 Y 值不合法”这类信息是生产前必跑的一步。我自己现在所有写 Excel 的工具方法都会在单测里把生成的文件用验证器过一遍再调用 Excel 打开一次做冒烟测试。4.4 排查公式下拉不生效、打开显示 0现象程序生成的 Excel 里有SUM公式用 Excel 打开后单元格显示 0 或空白要手动双击公式单元格才重新计算热词里常说的“excel 公式下拉失效”很多时候也是这个原因。原因OpenXml 写入的公式默认没有计算结果缓存也没有设置强制全量重算标志。Excel 出于性能考虑会直接读取缓存值缓存是空就显示空。解决往工作簿的计算属性里开“打开时全量重算”var calcProps workbookPart.Workbook.CalculationProperties; calcProps.FullCalcOnLoad true; // 部分新版本 SDK 属性名为 ForceFullCalculation逻辑说明CalculationProperties对应workbook.xml里的calcPr元素FullCalcOnLoad / ForceFullCalculation告诉 Excel 打开文件时忽略缓存、重算所有公式。这个开关写一次就作用于整个工作簿建议在创建工作簿时立刻设上免得后期排查半天。4.5 排查大文件导出内存暴涨复制粘贴还卡死现象导出 5 万行 Excel 时程序内存一路涨到 1GB 以上偶尔进程被杀用户拿到文件后在 Excel 里做“全选复制”也卡死。原因写入端用了sheetData.AppendChild(row)循环所有Row对象全被挂在SheetData的 DOM 树上SDK 在Save时才序列化峰值内存自然高。用户端卡顿则是因为某些单元格内容过大、又没设合理列宽Excel 在渲染复制范围时对所有单元格做格式计算。解决写入端改用OpenXmlWriter流式写见第 5 章单元格内容上一个CellValue不要塞几 MB 文本能用共享字符串就用共享字符串。对用户端来说导出时把不必要的样式去掉、不要给整行设置边框能显著改善复制粘贴体验。我们项目里出过一版报表给每行都设了ApplyBorderExcel 里 CtrlC 直接无响应去掉边框后秒复制。4.6 排查读出来字符串串行、希腊字母乱码现象读取一个别人给的 xlsx发现某些字符串单元格返回的数字或乱码和 Excel 界面显示的不一致含希腊字母的文件读出变成?。原因第一种是单元格实际是共享字符串索引但代码没用SharedStringTable转换直接把索引当文本返回第二种是 GRE 字母本身是 UTF-8 编码读取时如果手动用Encoding.Default解码 XML 流就变成了?。解决所有取值统一走 4.1 的GetCellValue不要自己判断读取时若手动解析 XML必须明确使用 UTF-8using var stream worksheetPart.Worksheet.WriteToStream() ...实际开发里用 SDK 不需要手动解码SDK 内部就是 UTF-8如果你是自己写的读取器StreamReader构造时务必传Encoding.UTF8。UUID、希腊字母这类文本没有专门的类型在 OpenXml 眼里都是普通字符串只要编码不出错就不会有问题。4.7 排查插入图片或定义打印区域后文件丢失块现象往工作表里加了DrawingPart图片或者设置了打印区域再次读取时图片不显示、打印区域失效Java 那边用 EasyPOI 导模板时“图片无效”的投诉OpenXml 侧也有对应版本。原因OOXML 对部件之间有严格的关系和顺序要求。图片需要WorksheetPart添加DrawingPart还要在worksheet.xml里插入drawing标签并通过关系 Id 关联打印区域则是workbook.xml里的DefinedNames名称必须以_xlnm.Print_Area命名且局部作用域要指定LocalSheetId。解决图片不要手工拼 XML用worksheetPart.AddNewPartDrawingPart()再追加ImagePart打印区域用代码构建DefinedNamevar definedName new DefinedName(_xlnm.Print_Area) { Text Sheet1!$A$1:$D$30, LocalSheetId 0 }; workbookPart.Workbook.AppendChild(new DefinedNames(definedName));逻辑说明LocalSheetId对应工作簿里 Sheet 的索引从 0 开始写错就不知道打印区域作用到哪个表了。做完之后建议用OpenXmlValidator再校验一次比肉眼找关系稳妥得多。5. 流式写出与正确性验证上生产前的最后一公里5.1 用 OpenXmlWriter 写十万行内存占用降一个数量级前面 4.5 提到写入端的高内存问题正解是用OpenXmlWriter直接向WorksheetPart的流里写元素整个SheetData树都不进内存using var doc SpreadsheetDocument.Create(stream.xlsx, SpreadsheetDocumentType.Workbook); var workbookPart doc.AddWorkbookPart(); workbookPart.Workbook new Workbook(new Sheets()); var sheetPart workbookPart.AddNewPartWorksheetPart(); using (var writer OpenXmlWriter.Create(sheetPart)) { writer.WriteStartElement(new Worksheet()); writer.WriteStartElement(new SheetData()); for (int i 0; i 100000; i) { var row new Row( new Cell { CellValue new CellValue(i.ToString()) }, new Cell { DataType CellValues.InlineString, CellValue new CellValue($第{i}行) } ); writer.WriteElement(row); } writer.WriteEndElement(); writer.WriteEndElement(); }writer 模式下同一个Row实例只能WriteElement一次写出去后这个对象就有父级了复用会报异常所以循环内每次new Row。这种写法的内存占用只跟writer内部缓冲有关和总行数无关十万行导出内存稳定在几十 MB 级别是生产环境的推荐姿势。缺点是这个写法没法顺手做复杂的样式后处理所以我的规则是纯数据导出用 Writer数据量小但样式复杂用 DOM。5.2 验证与辅助工具快速定位单元格的列索引换算OpenXml 里最常用的辅助函数就是列名和索引互转因为CellReference是A1这种形式而循环计数是整数。热词里“excel 快速定位”的需求在代码侧就是这段函数static string ColumnLetter(int index) // 1 - A, 27 - AA { var s ; while (index 0) { var rem (index - 1) % 26; s (char)(A rem) s; index (index - 1) / 26; } return s; } static int ColumnIndex(string letter) // A - 1, AA - 27 { var result 0; foreach (var c in letter.ToUpper()) result result * 26 (c - A 1); return result; }这个工具函数几乎每个读写 Excel 项目都有一份写大数据量时用它把rowIndex、colIndex拼成CellReference读数据时把它解析回行列索引比正则解析[A-Z][0-9]可靠得多。验证方法上除了 4.3 的OpenXmlValidator我还会做三件事用 WPS 打开一遍WPS 对 schema 顺序更敏感、用 Excel 打开一遍、再读回前 100 行和最后 100 行做对比。导出前我会故意写一个坏文件跑单测确认验证器能抓到顺序错乱、图片关系缺失这类问题确保它真的在干活。最近这两个月我已经把这个流程固化成习惯任何改到写入逻辑的提交都必须附一份生成文件的验证器输出不然不放行。这个习惯帮我挡掉了至少三次上线后报表打不开的翻车也希望帮到你。本文还有配套的精品资源点击获取