.NET 8接口返回application/octet-stream报406错误求解决方案

问题背景 #

需要实现接口返回数据库中存储的文件字节流，当前代码添加[Produces("application/octet-stream")]后返回406 Not Acceptable错误；改为application/json时返回200 Ok，但字节流出现错乱。

原因分析 #

1. 406错误原因：直接返回HttpResponseMessage时，[Produces]特性会触发ASP.NET Core的内容协商机制。若客户端请求的Accept头未包含application/octet-stream，或框架内容协商逻辑与手动构建的HttpResponseMessage冲突，就会返回406错误。
2. 字节流错乱原因：当设置[Produces("application/json")]时，框架会将字节数组序列化为JSON格式（通常转为Base64字符串），导致原始二进制流被篡改，无法正确还原文件。

解决方案 #

改用ASP.NET Core推荐的IActionResult返回类型，通过File方法直接返回二进制流，避免内容协商冲突和序列化问题：

修改后的代码 #

[HttpGet("/GetTemplate")]
public IActionResult GetTemplate()
{
    try
    {
        byte[] boletoTemplate = _templateService.GetTemplate();
        // 直接返回字节流，指定Content-Type为application/octet-stream
        return File(boletoTemplate, "application/octet-stream");
    }
    catch (NotFoundException ex)
    {
        return NotFound(ex.Message);
    }
    catch (Exception ex)
    {
        return BadRequest(ex.Message);
    }
}

关键调整说明 #

• 替换返回类型：将HttpResponseMessage改为IActionResult，使用框架提供的FileContentResult（由File方法返回）处理二进制响应，这是ASP.NET Core返回文件流的标准方式。
• 移除[Produces]特性：File方法已明确指定Content-Type，无需通过特性约束，避免触发不必要的内容协商。
• 异常处理标准化：使用NotFound、BadRequest等内置结果方法，保持异常响应格式一致性，同时符合框架规范。

额外优化（可选） #

如果需要指定下载文件名，可在File方法中添加第三个参数：

return File(boletoTemplate, "application/octet-stream", "template.pdf");

这样客户端会自动触发文件下载，文件名设为template.pdf。

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