在.NET开发中，处理Excel尤其是大文件，一直是让开发者头疼的问题。传统的NPOI、EPPlus等库往往因为将整个文件加载到内存而导致OutOfMemoryException。MiniExcel以其轻量、高效、低内存的特点，为这个问题提供了一个优雅的解决方案。
下面是一份关于MiniExcel的详细使用方案，希望能帮你快速上手。
🚀 为什么选择MiniExcel？
MiniExcel的优势非常突出，主要体现在以下几个方面：
- 极致低内存，告别OOM：这是MiniExcel最核心的优势。它采用流式处理（Stream-based）技术，数据像流水一样逐行处理，而不是一次性全部加载到内存。这使得处理上百MB甚至GB级别的大文件时，内存占用依然能保持在极低水平（有案例显示从8GB降至200MB以下，或从1.5GB降至几十MB）。
- 轻量级，无依赖：MiniExcel的NuGet包仅约150KB，且完全不依赖微软Office组件或任何其他大型运行时库，部署和使用都非常干净。
- API简洁，开箱即用：MiniExcel的设计哲学是“开箱即用”，提供了极其简洁的API。很多情况下，读取或写入Excel只需要一行核心代码就能搞定。
- LINQ完美搭档：MiniExcel的方法返回
IEnumerable，天然支持LINQ延迟查询。你可以先构建查询，再通过.ToList()或.Take()等方法按需获取数据，进一步优化性能。 - 跨平台支持：基于.NET Standard，MiniExcel能完美运行在Windows、Linux、macOS等平台上。
⚙️ 快速安装与准备
在你的.NET项目中，通过NuGet包管理器安装即可。
- 方式一：NuGet包管理器控制台
Install-PackageMiniExcel - 方式二：.NET CLI
dotnetaddpackage MiniExcel
安装完成后，在代码文件顶部引入命名空间：
usingMiniExcelLibs;📖 基础用法：从入门到实践
1. 读取Excel数据
假设我们有一个Employee类：
publicclassEmployee{publicintId{get;set;}publicstringName{get;set;}publicintAge{get;set;}publicstringDepartment{get;set;}}- 方式一：读取为强类型集合（推荐）
这是最推荐的方式，类型安全且智能。Query<T>方法会自动将Excel的第一行（表头）与Employee类的属性进行匹配（默认不区分大小写）。stringfilePath=@"C:\Reports\employees.xlsx";// 使用延迟查询，数据不会被立即全部加载到内存IEnumerable<Employee>employees=MiniExcel.Query<Employee>(filePath);// 真正需要数据时再遍历或转换为列表foreach(varempinemployees){Console.WriteLine($"{emp.Id}-{emp.Name}");}// 或者按需获取前10条varfirstTen=employees.Take(10).ToList(); - 方式二：读取为动态对象
当Excel结构不固定或没有对应实体类时，可以读取为dynamic对象。varrows=MiniExcel.Query(filePath);foreach(varrowinrows){// 通过动态属性访问列，列名即属性名Console.WriteLine($"{row.Name}-{row.Age}");}
2. 写入Excel数据
将数据集合导出为Excel文件，同样简单。
- 导出强类型集合
List<Employee>employees=GetEmployees();// 获取数据stringoutputPath=@"C:\Reports\employees_output.xlsx";// SaveAs 方法会自动根据 Employee 类的属性生成表头MiniExcel.SaveAs(outputPath,employees);
🧠 高级用法：解锁更多能力
1. 模板填充（Template）
这是MiniExcel非常强大的功能，可以让你预先设计好Excel模板，然后填充数据。
- 单条数据填充：在模板中使用
{{变量名}}占位。// 模板文件 template.xlsx 内容：姓名：{{Name}}，年龄：{{Age}}varvalue=new{Name="张三",Age=30};MiniExcel.SaveAsByTemplate("output.xlsx","template.xlsx",value); - 集合数据填充：在模板中使用
{{集合名.属性名}}进行循环渲染。// 模板文件 template.xlsx 内容：// 姓名：{{list.Name}}，年龄：{{list.Age}}vardata=new{list=new[]{new{Name="李四",Age=25},new{Name="王五",Age=28}}};MiniExcel.SaveAsByTemplate("output.xlsx","template.xlsx",data);
2. 处理动态列数据
当需要导出的数据列不固定时，可以使用Dictionary<string, object>作为数据源。
vardata=newList<Dictionary<string,object>>();// 动态添加列和数据data.Add(newDictionary<string,object>{["Name"]="赵六",["Score"]=95,["City"]="深圳"});data.Add(newDictionary<string,object>{["Name"]="孙七",["Score"]=88,["City"]="广州"});MiniExcel.SaveAs("dynamic_output.xlsx",data);3. 指定读取范围（QueryRange）
对于某些维度信息异常（如dimension属性错误）的Excel文件，直接读取可能导致卡死。此时可以使用QueryRange方法明确指定读取范围。
// 从第1行第1列开始读取，共读取10行5列的数据varrows=MiniExcel.QueryRange(filePath,startCell:"A1",rowCount:10,columnCount:5);📊 性能对比：数据说话
MiniExcel在性能上的优势是压倒性的。以下为处理约100MB文件时的对比数据：
| 库名称 | 内存消耗 | 处理时间 | 是否需要Office |
|---|---|---|---|
| MiniExcel | ~58 MB | ~12秒 | 否 |
| NPOI | ~1.2 GB | ~25秒 | 否 |
| ClosedXML | ~890 MB | ~30秒 | 否 |
| Interop.Excel | 不稳定 | ~45秒 | 是 |
选型建议：对于简单的数据导入导出，MiniExcel是首选；如果报表格式非常复杂（如图表、复杂公式），可考虑EPPlus（v5+版本需商业授权）；若需兼容老旧的
.xls格式，则NPOI仍是一个选择。
⚠️ 避坑指南：常见问题与解决方案
- 版本兼容性问题：如果你同时使用
Dapper等ORM，建议将MiniExcel升级到最新稳定版，以避免潜在的异步方法冲突。 - 列名映射失败：如果
Query<T>未能正确映射，请检查：- Excel的第一行（表头）是否与类属性名称完全一致（默认不区分大小写）。
- 表头是否包含前后空格，这会导致匹配失败。
- 数据类型转换问题：当将Excel单元格映射到
double类型时，如果单元格是文本，MiniExcel可能会赋值为double.NaN而非抛出异常，需要注意在代码中处理此情况。 - Sheet名称长度限制：Excel的Sheet名称不能超过31个字符。如果使用MiniExcel创建超出此长度的Sheet名，会导致文件打开错误。
- 模板变量大小写：在Excel模板中使用
{{variable}}语法时，变量名是区分大小写的，请确保与传入的对象属性名完全匹配。
💎 总结
MiniExcel为.NET开发者提供了一种高效、低内存、极其易用的Excel处理方案。无论是应对日常的小规模数据导出，还是挑战百万级数据的大文件处理，它都能游刃有余。其简洁的API设计，让你能从繁琐的底层细节中解放出来，专注于核心业务逻辑。
希望这份使用方案能对你有所帮助。如果在实践中遇到其他问题，也欢迎交流探讨。