必须用HttpClient.SendAsync配合HttpCompletionOption.ResponseHeadersRead手动读取响应流，通过IProgress报告已读字节数，Content-Length为空时无法计算百分比，需限制上报频率防UI卡顿。
HttpClient 下载时如何实时获取进度
直接用 HttpClient.GetAsync 或 DownloadAsync 拿不到进度，因为这些是封装好的“一键下载”，底层不暴露流式读取过程。必须改用 HttpClient.SendAsync 配合 HttpCompletionOption.ResponseHeadersRead，手动读取响应流。
关键点：不能等整个响应体下载完才开始处理，否则进度条毫无意义。
- 调用
SendAsync时传入HttpCompletionOption.ResponseHeadersRead，让请求在收到响应头后就返回HttpResponseMessage - 立刻调用
response.Content.ReadAsStreamAsync()获取响应流 - 用
Stream.CopyToAsync写入本地文件流，并传入自定义的IProgress<long></long>实现来报告已读字节数
用 IProgress 报告已下载字节数
IProgress<t></t> 是 .NET 提供的线程安全进度通知机制，比手动发事件或回调更轻量、不易出错。注意它只负责“通知”，不参与数据搬运逻辑。
常见误区：把 IProgress<long></long> 当成“总大小”或“百分比”——它只传当前累计读取的字节数，总大小得从 Content-Length 响应头里单独取（可能为空，比如分块传输）。
- 构造
IProgress<long></long>时，回调函数里可更新 UI 控件（如ProgressBar.Value），但需确保在 UI 线程执行（WPF 用Dispatcher.Invoke，WinForms 用Control.Invoke） - 如果
response.Content.Headers.ContentLength为null，说明服务器没返回明确长度（常见于 chunked 编码或动态生成文件），此时只能显示“已下载 XXX 字节”，无法算百分比 - 不要在回调里做耗时操作（如日志写磁盘），否则会拖慢下载流读取速度
完整示例：带进度回调的 DownloadFileAsync
public static async Task DownloadFileAsync(string url, string filePath, IProgress<long> progress)
{
using var client = new HttpClient();
using var response = await client.GetAsync(url, HttpCompletionOption.ResponseHeadersRead);
response.EnsureSuccessStatusCode();
var totalBytes = response.Content.Headers.ContentLength ?? -1;
using var contentStream = await response.Content.ReadAsStreamAsync();
using var fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write, FileShare.None, 8192, useAsync: true);
var buffer = new byte[8192];
long totalRead = 0;
int read;
while ((read = await contentStream.ReadAsync(buffer, CancellationToken.None)) > 0)
{
await fileStream.WriteAsync(buffer, 0, read, CancellationToken.None);
totalRead += read;
progress?.Report(totalRead);
}
}
这段代码避开了 CopyToAsync 的黑盒行为，显式控制每次读取和写入，便于插入进度上报。缓冲区大小设为 8192 是平衡内存占用与吞吐的常用值；useAsync: true 确保文件写入也是异步的，避免阻塞线程。
常见失败场景与绕过方案
不是所有服务器都支持标准进度获取。遇到问题先查响应头：curl -I {url} 看有没有 Content-Length，再确认是否返回 200 OK 而非 206 Partial Content（后者意味着服务端启用了断点续传，但客户端没发 Range 头）。
- 服务器返回
Transfer-Encoding: chunked且无Content-Length→ 只能显示“下载中”，无法预估剩余时间 - 下载大文件时 UI 卡顿 → 进度回调太频繁（比如每字节都 Report），应加阈值限制（如每 16KB 报一次）
- 移动端或低权限环境写入失败 → 检查
filePath所在目录是否有写权限，或改用ApplicationData.Current.LocalFolder（UWP）或Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData)（.NET Core/.NET 5+）
真正麻烦的是那些不返回 Content-Length、又不支持 Range 请求的老旧 HTTP 服务——这时候进度条本质是个心理安慰，重点反而是做好异常重试和断点续传逻辑。
