HttpClient的PostAsync默认不支持进度回调，因其一次性读取整个Stream并封装发送，未暴露字节级传输钩子；需用自定义ProgressStream+StreamContent+SendAsync手动控制流式上传并触发进度事件。
为什么 HttpClient 的 PostAsync 默认不支持进度回调
因为 PostAsync 是一次性把整个 Stream 读完再发出去，底层封装了请求体的写入过程，没暴露中间的字节发送钩子。你传一个 FileStream 或 MemoryStream，它内部就默默全塞进 HTTP body，你完全感知不到“发到哪了”。
要监控进度，必须绕过自动封装，自己控制请求体的流式写入——也就是用 HttpContent 的派生类 + 自定义 Stream。
- 核心思路：用自定义的
ProgressStream包裹原始文件流，每次Read或Write时触发回调 - 再把它塞进
StreamContent，最后用HttpClient.SendAsync（不是PostAsync）发起请求 - 注意：.NET 6+ 中
StreamContent默认会调用stream.Length，所以你的ProgressStream必须正确实现CanSeek和Length，否则会抛NotSupportedException
如何写一个带进度通知的 ProgressStream
它得继承 Stream，重写 Read（上传时常用）或 Write（更推荐，因 StreamContent 内部是往它里写），并暴露 ProgressChanged 事件。
public class ProgressStream : Stream
{
private readonly Stream _innerStream;
private readonly Action<long long> _onProgress;
<pre class="brush:php;toolbar:false;">public override bool CanRead => _innerStream.CanRead;
public override bool CanSeek => _innerStream.CanSeek;
public override bool CanWrite => _innerStream.CanWrite;
public override long Length => _innerStream.Length;
public override long Position { get => _innerStream.Position; set => _innerStream.Position = value; }
public ProgressStream(Stream innerStream, Action<long, long> onProgress)
{
_innerStream = innerStream;
_onProgress = onProgress;
}
public override int Write(byte[] buffer, int offset, int count)
{
var written = _innerStream.Write(buffer, offset, count);
_onProgress?.Invoke(_innerStream.Position, _innerStream.Length);
return written;
}
// 其他必需重写方法（Read/Seek/Flush/Close）直接转发给 _innerStream
public override void Flush() => _innerStream.Flush();
public override int Read(byte[] buffer, int offset, int count) => _innerStream.Read(buffer, offset, count);
public override long Seek(long offset, SeekOrigin origin) => _innerStream.Seek(offset, origin);
public override void SetLength(long value) => _innerStream.SetLength(value);
protected override void Dispose(bool disposing)
{
if (disposing) _innerStream.Dispose();
base.Dispose(disposing);
}}
- 关键点：
Write中调用_onProgress，参数是当前已写位置和总长度，UI 层可据此算百分比 - 务必转发所有其他方法，否则
StreamContent在初始化或发送过程中可能调用Seek或Length导致异常 - 如果源流是
FileStream，确保以FileAccess.Read打开；如果是内存流，确认GetBuffer()或ToArray()不被误用
用 HttpClient.SendAsync 发起带进度的请求
不能用 PostAsync，必须手动构造 HttpRequestMessage，把 ProgressStream 套进 StreamContent，再设好 Content-Length 和 Content-Type。
var fileStream = File.OpenRead("test.pdf");
var progressStream = new ProgressStream(fileStream, (sent, total) =>
{
double percent = (double)sent / total * 100;
Console.WriteLine($"上传中: {percent:F1}% ({sent}/{total})");
// 更新 UI 进度条，例如: progressBar.Value = (int)percent;
});
<p>var content = new StreamContent(progressStream);
content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
content.Headers.ContentLength = fileStream.Length; // 必须显式设置！</p><p>var request = new HttpRequestMessage(HttpMethod.Post, "<a href="https://www.php.cn/link/f142c6067e6345134c6728f299cf4c1e">https://www.php.cn/link/f142c6067e6345134c6728f299cf4c1e</a>")
{
Content = content
};</p><p>using var client = new HttpClient();
var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);</p>-
HttpCompletionOption.ResponseHeadersRead很重要：它让请求在收到响应头时就返回，避免等整个响应体下载完，提升上传阶段的响应速度 -
ContentLength必须手动设，否则HttpClient可能退化为 chunked 编码，后端无法预知大小，前端进度计算也会失准 - 上传大文件时，记得配置
HttpClient.Timeout，比如设为TimeSpan.FromMinutes(10)
常见失败场景和绕不过去的坑
进度条卡在 99%、上传中途报错、UI 线程阻塞——这些问题几乎都来自这几点：
- 没在 UI 线程外执行上传：用
await是必须的，但回调里的 UI 更新（如progressBar.Value = ...）必须用Dispatcher.Invoke（WPF）或Control.Invoke（WinForms），否则抛跨线程异常 - 后端没做分块接收或超时限制：即使前端发完了，如果后端 Nginx/Apache 有
client_max_body_size或timeout限制，仍会断连，此时前端可能收不到明确错误，只看到HttpRequestException带 “connection reset” -
ProgressStream没正确处理Dispose：上传取消时，HttpClient.CancelPendingRequests()会触发流释放，若ProgressStream.Dispose没转发_innerStream.Dispose()，文件句柄泄漏 - 移动端（Xamarin/.NET MAUI）要注意：某些平台对后台上传有电量/网络策略限制，单纯加进度回调不能绕过系统级中断
进度本身是客户端可控的，但“传没传成功”永远取决于服务端是否完整接收到并校验通过。别让进度条掩盖了最终响应状态的检查。
