ASP.Net Core中PDF文件下载失败的问题排查与正确实现方法

原代码的问题点 #

• 直接操作Response不符合ASP.NET Core的MVC设计规范，框架提供了更安全标准的IActionResult返回方式
• Content-Disposition的filename参数用了完整文件路径，浏览器会把路径当作文件名，导致文件名异常甚至下载失败
• Response.WriteAsync(outputFilePath)写入的是文件路径字符串，而非PDF文件的实际内容，这是核心错误
• 未处理文件不存在的异常，若文件缺失会直接抛出未捕获错误

正确的PDF下载实现方式 #

方式1：直接返回文件路径（推荐，框架自动处理头信息） #

利用ASP.NET Core内置的File方法，框架会自动处理Content-Disposition和Content-Length等头信息：

public IActionResult DownloadFile()
{
    string webRootPath = _webHostEnvironment.WebRootPath;
    string outputFilePath = Path.Combine(webRootPath, "pdf", "sample.pdf");
    
    // 检查文件是否存在
    if (!System.IO.File.Exists(outputFilePath))
    {
        return NotFound("文件不存在");
    }
    
    // 提取纯文件名，避免路径干扰
    string fileName = Path.GetFileName(outputFilePath);
    
    // 返回文件，指定ContentType为PDF类型，设置为附件下载
    return File(outputFilePath, "application/pdf", fileName);
}

方式2：读取文件流返回 #

如果需要对文件流做额外处理（比如加密、修改内容），可以先读取流再返回：

public IActionResult DownloadFile()
{
    string webRootPath = _webHostEnvironment.WebRootPath;
    string outputFilePath = Path.Combine(webRootPath, "pdf", "sample.pdf");
    
    if (!System.IO.File.Exists(outputFilePath))
    {
        return NotFound("文件不存在");
    }
    
    string fileName = Path.GetFileName(outputFilePath);
    var fileStream = new FileStream(outputFilePath, FileMode.Open, FileAccess.Read);
    
    return File(fileStream, "application/pdf", fileName);
}

方式3：返回字节数组 #

如果已将文件内容读取为字节数组，可使用这种方式：

public IActionResult DownloadFile()
{
    string webRootPath = _webHostEnvironment.WebRootPath;
    string outputFilePath = Path.Combine(webRootPath, "pdf", "sample.pdf");
    
    if (!System.IO.File.Exists(outputFilePath))
    {
        return NotFound("文件不存在");
    }
    
    string fileName = Path.GetFileName(outputFilePath);
    byte[] fileBytes = System.IO.File.ReadAllBytes(outputFilePath);
    
    return File(fileBytes, "application/pdf", fileName);
}

关键注意事项 #

• 必须检查文件是否存在，避免抛出未处理异常
• filename参数只传纯文件名，不要带路径，防止浏览器解析错误
• 优先使用框架提供的File方法，而非直接操作Response，这是ASP.NET Core的标准实践，能规避很多头信息处理错误

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