.NET 6 Web API下载CSV文件后德语字符显示异常问题

问题场景 #

API端点返回包含德语特殊字符（如ö、ß、ü）的CSV模板时，出现以下现象：

• 直接通过浏览器访问端点，CSV内容显示正常
• 通过Swagger调用下载文件、前端UI集成下载时，德语字符全部乱码

提供的简化实现代码：

[HttpGet]
[ProducesResponseType(typeof(Stream), StatusCodes.Status200OK)]
[Route("template")]
public async Task GetTemplate()
{
    Response.StatusCode = StatusCodes.Status200OK;
    Response.ContentType = "text/csv";
    Response.Headers.AddContentDispositionAttachment("Template.csv");

    CsvConfiguration csvConfiguration = new (new CultureInfo("de-de"))
    {
        Delimiter = ";",
        HasHeaderRecord = false
    };

    string header = $"Url;Beschreibung;Code;ID;Löschen;Straße;Pünklitch";

    using var streamWriter = new StreamWriter(Response.Body, Encoding.UTF8, 65536);
    await using var csvWriter = new CsvWriter(streamWriter, csvConfiguration);
    await streamWriter.WriteAsync(header);
}

核心原因 #

直接浏览器访问正常是因为现代浏览器对无BOM（字节顺序标记）的UTF-8兼容性较好，但Swagger的下载逻辑、部分前端Blob处理逻辑会默认将无BOM的UTF-8文件识别为系统默认编码（如Windows-1252），导致特殊字符解析乱码。

解决方案 #

1. 使用带BOM的UTF-8编码 #

将Encoding.UTF8替换为new UTF8Encoding(true)，后者会生成UTF-8 BOM，明确告知客户端文件编码格式。

2. 明确ContentType的编码信息 #

在ContentType中补充charset=utf-8，避免客户端猜测编码。

3. 规范使用CsvWriter写入内容（可选） #

避免手动拼接分隔符，直接使用CsvWriter的API写入字段，保证编码一致性的同时减少错误。

修改后的完整代码 #

[HttpGet]
[ProducesResponseType(typeof(Stream), StatusCodes.Status200OK)]
[Route("template")]
public async Task GetTemplate()
{
    Response.StatusCode = StatusCodes.Status200OK;
    // 明确指定ContentType带UTF-8编码
    Response.ContentType = "text/csv; charset=utf-8";
    Response.Headers.AddContentDispositionAttachment("Template.csv");

    CsvConfiguration csvConfiguration = new(new CultureInfo("de-de"))
    {
        Delimiter = ";",
        HasHeaderRecord = false
    };

    // 使用带BOM的UTF-8编码
    using var streamWriter = new StreamWriter(Response.Body, new UTF8Encoding(true), 65536);
    await using var csvWriter = new CsvWriter(streamWriter, csvConfiguration);
    
    // 通过CsvWriter写入字段，替代手动拼接
    await csvWriter.WriteFieldAsync("Url");
    await csvWriter.WriteFieldAsync("Beschreibung");
    await csvWriter.WriteFieldAsync("Code");
    await csvWriter.WriteFieldAsync("ID");
    await csvWriter.WriteFieldAsync("Löschen");
    await csvWriter.WriteFieldAsync("Straße");
    await csvWriter.WriteFieldAsync("Pünktlich"); // 修正原代码拼写错误，若为业务特殊命名可忽略
    await csvWriter.NextRecordAsync();
}

补充说明 #

• 带BOM的UTF-8是解决Swagger和前端下载乱码的关键，它能让客户端明确识别文件编码为UTF-8
• 若前端仍存在乱码，需检查前端Blob处理逻辑是否指定了UTF-8编码读取文件

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