CsvHelper读取中文CSV乱码或报错主因是编码不匹配：Windows记事本保存的UTF-8 with BOM文件需用Encoding.UTF8显式指定；GBK/GB2312文件则用Encoding.GetEncoding("GB2312")；务必避免Encoding.Default。
为什么 CsvHelper 读取中文字段会乱码或报错
CsvHelper 默认用 UTF8Encoding（无 BOM）解析文件，但 Windows 记事本保存的 CSV 常带 UTF-8 with BOM，导致首列字段名识别失败，抛出 System.ArgumentException: No properties are mapped 或字段值为空。更隐蔽的是 GB2312/GBK 编码的旧系统导出 CSV，直接读会全盘乱码。
解决方式不是“换编码”，而是显式指定 StreamReader 的编码，并确保和文件实际编码一致：
using (var reader = new StreamReader("data.csv", Encoding.UTF8)) // 或 Encoding.GetEncoding("GB2312")
using (var csv = new CsvReader(reader, CultureInfo.InvariantCulture))
{
var records = csv.GetRecords<MyModel>().ToList();
}- 优先用
Encoding.UTF8，但若第一行字段名显示为"\uFEFF姓名,年龄"，说明有 BOM，UTF8可自动处理，无需额外 strip - 确认编码最稳的方式：用 VS Code 打开 CSV，右下角看当前编码；或用
file -i data.csv（Linux/macOS） - 避免用
Encoding.Default，它在不同系统上可能返回 GBK 或 Shift-JIS，不可移植
CsvHelper 映射类字段时忽略大小写或自定义列名
CSV 列名常为 user_name、UserName、用户姓名，而 C# 类属性是 UserName。CsvHelper 默认严格匹配名称（区分大小写 + 下划线），不匹配就跳过该字段，不会报错，但数据丢失不易察觉。
启用灵活映射的关键是配置 CsvConfiguration 和 ClassMap：
var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
PrepareHeaderForMatch = args => args.Header.Trim().ToLower().Replace("_", ""),
};-
PrepareHeaderForMatch是核心钩子，对 CSV 表头做标准化（去空格、转小写、删下划线），再与属性名比对 - 若需支持中文表头（如
"用户名"→UserName），必须用ClassMap显式绑定：Map(m => m.UserName).Name("用户名"); - 不要依赖
IgnoreCase = true（已废弃），它只影响属性名比较，不处理表头预处理
写入 CSV 时控制日期格式、空值输出和性能瓶颈
默认写入 DateTime 是完整 ISO 格式（如 2024-05-20 14:22:33.123），多数报表只要 yyyy-MM-dd；空值默认写成空白字段，但有些系统要求写 NULL 或 <null></null>；批量写入万级记录时，逐条 WriteRecord 比 WriteRecords 慢 3–5 倍。
- 统一日期格式：在
ClassMap中用ConvertUsing：Map(m => m.BirthDate).ConvertUsing(x => x?.ToString("yyyy-MM-dd")); - 空值控制：全局设
ShouldQuote = args => args.Field == null || args.Field.ToString().Contains(",")，但空字符串是否引号取决于业务，别一刀切 - 写入性能：用
csv.WriteRecords(list)代替循环csv.WriteRecord(item)，前者内部做了缓冲优化；若 list 超 10 万，考虑分批 +csv.NextRecord()避免内存峰值
如何安全处理含逗号、换行符、引号的 CSV 字段
CsvHelper 默认能处理这些，但前提是字段被双引号包裹，且引号本身被转义（如 "a""b"）。问题多出在原始数据没按 RFC 4180 规范生成，比如前端 JS 导出 CSV 时未 escape，导致解析错行或字段偏移。
- 读取时确保
Configuration.Delimiter = ","（别改）、Configuration.Quote = '"'（别用单引号）、Configuration.AllowComments = false（注释会干扰） - 写入前验证字段内容：含
\n、\r、,、"的字段，CsvHelper 会自动加引号并转义双引号 —— 但前提是没手动调用WriteField绕过封装 - 最易踩的坑：
csv.WriteField("abc\"def")不会自动转义，必须写成csv.WriteField("abc\"\"def")；应始终走WriteRecords或模型映射，别裸写字段
真正麻烦的不是 CsvHelper 本身，而是上游数据来源不规范。上线前务必用真实脏数据（含 emoji、混合换行、超长字段）跑一遍端到端流程，光测 clean case 没用。
