先安装dotnet add package Magicodes.IE.IO最简单的模型不需要额外配置public sealed class Foo{public string Name { get; set; } “”;public decimal Value { get; set; }public DateTime CreatedAt { get; set; }}var foos new[]{new Foo { Name “foo-1”, Value 1.25m, CreatedAt new DateTime(2026, 1, 1) },};先写一个文件数据已经在内存中目标又是本地文件时直接传路径即可Xlsx.Write(“foo.xlsx”, foos);路径重载会创建并释放内部 FileStream。如果输出目标由调用方管理例如文件流或 HTTP 响应流就使用 Stream 重载using var stream File.Create(“foo.xlsx”);Xlsx.Write(stream, foos);Stream 重载不负责释放传入的流。HTTP 响应写出一部分 XLSX 后后续发生异常也无法把已发送的字节收回不要再往同一个响应写 JSON 错误信息。如果需要“成功后才覆盖旧文件”在外层先写临时文件成功后再替换目标文件。返回 byte[]适合小结果不适合大文件如果 API 必须返回字节数组可以使用byte[] bytes Xlsx.ToBytes(foos);这个入口会物化整个工作簿和最终的 byte[]。小文件、测试或确实需要字节数组的 API 可以使用它下载接口和大数据导出通常应直接写入输出流。可以这样理解场景 建议 API小文件、单元测试、需要 byte[] Xlsx.ToBytes写本地文件 Xlsx.Write(path, data)已有文件流或 HTTP 响应流 Xlsx.Write(stream, data)调用方已有缓冲区 Xlsx.Write(IBufferWriter, data)数据源本身异步、不能全量物化 Xlsx.WriteAsync(stream, IAsyncEnumerable)导入并同步遍历 Xlsx.Read(stream)导入并异步遍历 Xlsx.ReadAsync(stream)再看一个最小导入读取 API 返回惰性枚举数据会在遍历时映射为行模型using var stream File.OpenRead(“foo.xlsx”);var rows Xlsx.Read(stream).ToList();读取完成时Reader 默认会关闭输入流。如果同一个流后面还要继续使用传入 leaveOpen: true。这和导出 Stream 重载的所有权规则正好相反。配置列名、格式和过滤默认情况下列名和顺序由模型属性推断。需要改列名、格式或过滤行时再配置 ExportProfileXlsx.Write(“foo.xlsx”, foos, p {p.Column(x x.Name, c c.WithName(“Name”));p.Column(x x.Value, c c.WithFormat(“0.00”));p.Where(x x.Value 0);});ExportProfile 还负责列顺序、隐藏列、样式、冻结表头、合并单元格和超链接。配置会在写入前冻结后续每一行复用同一份列计划。异步数据源数据库查询已经返回 IAsyncEnumerable 时可以直接交给异步写入await Xlsx.WriteAsync(response.Body,GetFoosAsync(cancellationToken),cancellationToken: cancellationToken);这条路径不要求先把全部记录放进 List。不过输出缓冲、压缩状态、SST 和数据源自己的预取仍会占用内存“流式”只表示不必由调用方一次性物化全部行。什么时候打开 AutoSst字符串重复率高时可以尝试启用 Shared String TableSSTXlsx.Write(“foo.xlsx”, foos, p p.WithAutoSst(true));实现会抽样判断是否启用 SST。它能减少重复文本但也要维护全量唯一字符串表。状态、地区、产品名这类重复短文本可以尝试订单号、时间戳和随机 ID 这类高基数字段默认保持 Inline String 往往更稳。具体规则见第 05 篇。从旧导出入口迁移如果项目之前使用 Magicodes.IE 的旧导出抽象可以先从这些常见入口迁移旧思路 Magicodes.IE.IO导出到路径 Xlsx.Write(path, data)导出到 byte[] Xlsx.ToBytes(data)导出到响应流 Xlsx.Write(stream, data)异步数据源 Xlsx.WriteAsync(stream, asyncData)列和格式配置 ExportProfile迁移前需要重新确认原来的调用方是否依赖完整工作簿一次性驻留内存输出流的所有权由谁负责释放原来使用的高级 Excel 特性是否在当前 IO 路径中有对应实现。大文件优先考虑 Stream 或 IAsyncEnumerable不要把所有导出都改成 ToBytes。