CsvHelper 用于 C# (.NET)：完整指南及示例

\n\n

1. 什么是 CsvHelper 以及为什么需要它

CsvHelper 库是一个强大且灵活的工具，用于在 .NET 生态系统中读取和写入 CSV 文件。它为开发者提供了高级 API，抽象了处理 CSV 格式的复杂性，使您能够专注于应用程序的业务逻辑。与 String.Split(',') 等原始方法不同，CsvHelper 能正确处理转义字符、引号、多行字段以及各种区域性设置（分隔符、日期和数字格式）。

为什么需要它？在现代开发中，CSV 仍然是数据交换最常用的格式之一：导出报告、从 Excel 导入、加载配置、与旧系统交换数据以及数据迁移。CsvHelper 将解析这一常规任务转化为简洁、声明式的代码，利用类映射（属性或 Fluent API）、自动类型转换和内置验证。这节省了数小时的开发时间，并减少了与手动解析字符串相关的错误数量。

关键功能：支持 .NET Standard 2.0+（可在任何地方运行：.NET Framework、.NET Core、.NET 5+）、流式处理（不将整个文件加载到内存中）、自定义类型转换器、分隔符检测、处理标题和索引，以及完全支持异步操作（ReadAsync/WriteAsync）。

\n\n

2. 安装

通过 NuGet 包管理器进行安装。在包管理器控制台或 .NET CLI 终端中执行以下任一命令：

dotnet add package CsvHelper

或通过包管理器控制台：

Install-Package CsvHelper

对于版本 31.0.2（撰写本文时的最新版本），需要 .NET Standard 2.0 或更高版本。安装后，在代码中添加 using 指令：

using CsvHelper;\nusing CsvHelper.Configuration;\nusing System.Globalization;

\n\n

3. 快速入门 — 最小工作示例

创建一个简单的模型并写入/读取 CSV 文件。

using System.Globalization;\nusing CsvHelper;\nusing CsvHelper.Configuration;\n\npublic class Person\n{\n    public string Name { get; set; }\n    public int Age { get; set; }\n    public string Email { get; set; }\n}\n\n// 写入\nvar people = new List<Person>\n{\n    new Person { Name = "安娜", Age = 30, Email = "anna@example.com" },\n    new Person { Name = "鲍里斯", Age = 25, Email = "boris@example.com" }\n};\n\nusing (var writer = new StreamWriter("people.csv"))\nusing (var csv = new CsvWriter(writer, CultureInfo.InvariantCulture))\n{\n    csv.WriteRecords(people);\n}\n\n// 读取\nusing (var reader = new StreamReader("people.csv"))\nusing (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))\n{\n    var records = csv.GetRecords<Person>().ToList();\n    foreach (var p in records)\n        Console.WriteLine($"{p.Name}, {p.Age}, {p.Email}");\n}

此示例演示了基本流程：创建 CsvWriter 或 CsvReader 对象，传递流和区域性，调用写入/读取方法。请注意 CultureInfo.InvariantCulture — 这确保了小数分隔符和日期以统一格式写入（数字用点，日期用 ISO 格式）。

\n\n