ASP.NET Core 2使用PhysicalFileResult下载含Emoji文件名文件乱码问题

这个问题我之前帮朋友排查过，其实不是PhysicalFileResult本身的问题，核心在于HTTP响应头里的Content-Disposition字段对非ASCII字符（尤其是Emoji这类Unicode补充平面字符）的编码规范兼容性。ASP.NET Core 2的默认处理逻辑没覆盖好这类场景，导致文件名乱码。

问题根源 #

早期HTTP标准只支持ASCII字符，后来虽然通过RFC 5987和RFC 6266扩展了Unicode支持，但不同浏览器对编码格式的要求有差异。ASP.NET Core 2默认生成Content-Disposition时，会用旧的编码方式（比如ISO-8859-1）处理非ASCII字符，而Emoji属于UTF-8多字节字符，直接转码就会变成��这类乱码。

具体解决方法 #

方法一：手动构造Content-Disposition头

跳过PhysicalFile方法的第三个文件名参数，自己手动生成符合标准的响应头，确保用UTF-8编码Emoji：

public async Task<IActionResult> GetByIdAsync([FromRoute] long id)
{
    var filePath = "c:\\file.png";
    var targetFileName = "😀.png";
    
    // 用Uri.EscapeDataString正确编码UTF-8字符（包括Emoji）
    var encodedFileName = Uri.EscapeDataString(targetFileName);
    // 同时兼容新旧浏览器的写法：filename*是RFC标准格式，filename是兼容旧浏览器的降级写法
    Response.Headers.Add("Content-Disposition", $"attachment; filename=\"{encodedFileName}\"; filename*=UTF-8''{encodedFileName}");
    
    return PhysicalFile(filePath, "image/png");
}

方法二：封装扩展方法复用逻辑

如果多个接口都需要处理这类文件名，可以写一个扩展方法封装编码逻辑，避免重复代码：

public static class FileResultExtensions
{
    public static PhysicalFileResult WithUnicodeFileName(this PhysicalFileResult result, string fileName)
    {
        var encodedFileName = Uri.EscapeDataString(fileName);
        // 清空默认的FileDownloadName，避免框架自动生成错误的头
        result.FileDownloadName = null;
        result.ResponseHeaders.Add("Content-Disposition", $"attachment; filename=\"{encodedFileName}\"; filename*=UTF-8''{encodedFileName}");
        return result;
    }
}

使用时就很简洁：

public async Task<IActionResult> GetByIdAsync([FromRoute] long id)
{
    return PhysicalFile("c:\\file.png", "image/png")
           .WithUnicodeFileName("😀.png");
}

补充说明 #

ASP.NET Core 3.0及以上版本已经修复了这个问题，框架会自动处理包括Emoji在内的Unicode文件名，不需要手动编码。但如果你还在维护2.x版本的项目，上面的方法就能完美解决乱码问题。

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