CsvHelper读写CSV触发HeaderValidationException异常的排查与解决

这是操作配置问题，并非CsvHelper组件bug。核心原因是读写CSV时的表头匹配规则不统一，导致读取时组件按小写表头查找，与文件中实际的首字母大写表头不匹配。

核心原因 #

CsvHelper默认的表头匹配逻辑对大小写敏感，若读取配置中设置了HeaderNamingPolicy为LowerCaseNamingPolicy.Instance，或未明确配置忽略大小写，组件会尝试查找与属性名小写形式一致的表头（即body、category），但文件中实际表头为Body、Category，因此触发HeaderValidationException。

修正方案 #

1. 统一读写的命名策略 #

确保写入和读取时使用相同的表头命名规则，避免大小写差异：

• 写入示例（保持属性原大小写）：

using var writer = new CsvWriter(new StreamWriter("filters.csv"), new CsvConfiguration(CultureInfo.InvariantCulture)
{
    HeaderNamingPolicy = null // 直接使用属性名的原大小写
});
writer.WriteRecords(filterList);

• 读取示例（与写入策略一致）：

using var reader = new CsvReader(new StreamReader("filters.csv"), new CsvConfiguration(CultureInfo.InvariantCulture)
{
    HeaderNamingPolicy = null // 和写入时的配置完全匹配
});
var filters = reader.GetRecords<Filter>().ToList();

2. 配置读取时忽略表头大小写 #

若无需严格匹配大小写，可直接开启忽略大小写的配置：

var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
    IgnoreHeaderCase = true, // 忽略表头与属性名的大小写差异
    // 可选：若需保留表头验证但忽略大小写不匹配，可自定义验证逻辑
    // HeaderValidated = (context) =>
    // {
    //     if (context.HeaderNames.Contains(context.PropertyName, StringComparer.OrdinalIgnoreCase))
    //     {
    //         return;
    //     }
    //     throw context.Exception;
    // }
};
using var reader = new CsvReader(new StreamReader("filters.csv"), config);
var filters = reader.GetRecords<Filter>().ToList();

3. 正确使用[Name]特性 #

若之前使用[Name]特性无效，需确保特性值与CSV表头完全一致（包括大小写），且读取时未设置会覆盖特性的命名策略：

public sealed record Filter
{
    [Name("Body")]
    public string Body { get; init; }

    [Name("Category")]
    public string Category { get; init; }
}

读取时需关闭会修改名称的命名策略（即HeaderNamingPolicy = null），避免特性被覆盖。

关于[Index]特性的说明 #

[Index]是按列索引匹配数据，无需依赖表头，但默认开启的表头验证仍会检查表头与属性名的匹配关系。若使用[Index]，需同时关闭表头验证或开启IgnoreHeaderCase，否则仍会触发异常：

var config = new CsvConfiguration(CultureInfo.InvariantCulture)
{
    HeaderValidated = null // 关闭表头验证
};

内容的提问来源于stack exchange，提问作者Mohammed Mahmoud