ASP.NET Core 3.1 MVC返回PDF报无法下载 响应头正常无报错怎么解决

常见触发场景与对应修复（均为服务器日志无报错的场景） #

• 网关/反向代理层的响应截断
  当请求链路中存在Nginx、IIS反向代理、云WAF等中间层时，即便ASP.NET Core本身返回的响应完整，中间层的默认响应大小限制、缓冲策略也会直接截断长响应流。这类截断动作发生在网关层，不会在应用服务器的日志中留下任何错误记录，浏览器接收到不完整的响应体就会直接抛出网络错误。
  调整方向：
  • 对下载路由单独关闭网关层的响应缓冲，调高单请求最大响应体大小限制，匹配实际PDF文件的体积
  • 排查中间层是否有拦截application/pdf类型响应的安全规则
• Content-Disposition头的文件名不符合浏览器安全规范
  当下载文件名包含中文、全角符号、特殊转义字符时，即便应用端输出的响应头参数看起来符合要求，新版Chrome、Edge浏览器的安全策略也会直接拦截不满足RFC编码规范的文件名，整个下载请求不会完成完整的响应传输，自然不会在应用日志留下错误。
  调整方向：
  • 对下载文件名做UTF-8 URL编码，不要直接把原始文件名拼入响应头
  • 编码后的正确返回写法：

    var encodedFileName = System.Net.WebUtility.UrlEncode(mergedFileName, System.Text.Encoding.UTF8);
    return new FileStreamResult(ms, new MediaTypeHeaderValue("application/pdf"))
    {
        FileDownloadName = encodedFileName
    };
    

• 不必要的内存流转产生的生命周期问题
  当前代码已经拿到了完整的PDF字节数组，完全不需要手动new MemoryStream做中转写入。这类中转操作不仅会浪费内存，还容易在流的释放、位置指针调整上出现隐蔽问题——一旦字节数组为空、长度校验缺失，就会出现传输中途流被提前释放的情况，这类异常经常会被全局异常中间件静默吞掉，不会输出到日志。
  调整方向：
  • 拿到字节数组后直接用内置的File(bytes, contentType, fileName)方法返回，省掉手动创建内存流的步骤
  • 增加空值/长度校验：

    if (rawPdf == null || rawPdf.Length == 0)
    {
        return BadRequest("生成的PDF内容为空");
    }
    return File(rawPdf, "application/pdf", mergedFileName);
    

• 前端请求的响应类型不匹配
  如果前端是通过fetch、axios等AJAX方式发起的POST下载请求，没有显式将请求的响应类型设置为blob，浏览器就会按默认的JSON/文本格式解析响应流，碰到不匹配的二进制流时就会直接报网络错误，不会触发原生的下载弹窗。
  调整方向：
  • 前端请求中显式配置responseType: 'blob'，拿到完整二进制流后再手动触发浏览器下载
  • 也可以将下载接口改为GET请求，用隐藏a标签的原生跳转触发浏览器下载，绕开AJAX的响应解析逻辑

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