流式传输文件时抛出Headers are read-only异常求助

异常原因 #

你遇到的System.InvalidOperationException: Headers are read-only, response has already started异常，根源在于方法末尾的return Ok();。当你通过Response.Body.WriteAsync向响应流写入数据后，HTTP响应已经启动，此时ASP.NET Core框架无法再修改响应头或发送新的响应状态（Ok()会尝试设置200状态码并完成响应），从而触发该异常。

修复方案 #

方案1：修正原代码，替换返回值 #

将末尾的return Ok();替换为return new EmptyResult();，告知框架响应已手动完成，无需再处理：

[HttpGet("stream/{id}")] 
public async Task<IActionResult> StreamFile(int id) 
{
    var upload = await _mediator.Send(new GetFileUploadByIdQuery { Id = id });
    if (upload.Data == null)
    {
        return NotFound();
    }

    var contentDisposition = new ContentDispositionHeaderValue("inline")
    {
        FileName = upload.Data.FileName
    };

    Response.Headers.Add("Content-Disposition", contentDisposition.ToString());
    Response.ContentType = upload.Data.ContentType;

    // Stream the file in chunks
    int chunkSize = 1024 * 1024 * 4;
    int bytesRead;
    using var stream = new MemoryStream(upload.Data.Content);
    byte[] buffer = new byte[chunkSize]; 
    while ((bytesRead = await stream.ReadAsync(buffer, 0, buffer.Length)) > 0)
    {
        await Response.Body.WriteAsync(buffer, 0, bytesRead);
        await Response.Body.FlushAsync();
    }

    return new EmptyResult(); // 替换Ok()，避免框架重复处理响应
}

方案2：使用ASP.NET Core内置的File方法（推荐） #

ASP.NET Core提供了专门的File方法处理文件流式传输，框架会自动管理响应头、流的释放和分块逻辑，无需手动操作Response.Body，更简洁可靠：

[HttpGet("stream/{id}")] 
public async Task<IActionResult> StreamFile(int id) 
{
    var upload = await _mediator.Send(new GetFileUploadByIdQuery { Id = id });
    if (upload.Data == null)
    {
        return NotFound();
    }

    var stream = new MemoryStream(upload.Data.Content);
    var contentDisposition = new ContentDispositionHeaderValue("inline")
    {
        FileName = upload.Data.FileName
    };
    Response.Headers.Add("Content-Disposition", contentDisposition.ToString());

    return File(stream, upload.Data.ContentType);
}

补充说明 #

• 使用File方法时，框架会自动处理Content-Length头（如果流支持获取长度），并支持断点续传等HTTP特性，比手动写流更健壮。
• 若需要设置Content-Disposition为附件（下载文件），只需将"inline"改为"attachment"即可。

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