PostAsync 会将整个文件加载到内存导致 OOM、无法监控进度或断点续传；需用 MultipartFormDataContent 包裹带 leaveOpen=true 的 StreamContent，并配置 FileStream 的 FileAccess、FileShare 和 FileOptions；分块上传应采用自定义协议，按块发送原始二进制流并用 Header 标识序号与偏移。
HttpClient 上传大文件时为什么不能直接用 PostAsync？
因为默认的 PostAsync 会把整个文件读进内存再发出去，1GB 文件就占 1GB 内存，还容易触发 OutOfMemoryException，而且无法监听进度、无法断点续传、无法取消上传。真正的分块上传必须绕过 HttpContent 的自动缓冲机制，手动构造流式请求体。
关键点：用 MultipartFormDataContent 包裹 StreamContent，但要确保底层 FileStream 是以 FileAccess.Read + FileShare.Read 打开，并设置 leaveOpen = true，否则上传中途流被关闭会导致 400 或连接重置。
-
FileStream必须用FileOptions.Asynchronous | FileOptions.SequentialScan，提升大文件读取效率 - 不要用
new StringContent(...)拼接表单字段，改用multipartFormDataContent.Add(new StringContent(...), "key") - 服务端必须支持
multipart/form-data解析，且对单个 part 的大小限制（如 Nginx 的client_max_body_size）要调高
如何实现可暂停/续传的分块上传（非标准 multipart）？
网盘类场景常用的是「自定义分块协议」：先调接口获取上传 ID，再按固定块大小（如 4MB）逐个 POST 块，最后合并。这时不用 MultipartFormDataContent，而是直接发原始二进制流，靠 HTTP Header 标识块序号和偏移。
示例关键逻辑：
var blockBytes = new byte[blockSize];
using var fs = new FileStream(filePath, FileMode.Open, FileAccess.Read, FileShare.Read, 4096, FileOptions.Asynchronous | FileOptions.SequentialScan);
for (int i = 0; i < blockCount; i++)
{
int read = await fs.ReadAsync(blockBytes, 0, blockSize, cancellationToken);
if (read == 0) break;
<pre class='brush:php;toolbar:false;'>var content = new ByteArrayContent(blockBytes, 0, read);
content.Headers.ContentRange = new ContentRangeHeaderValue(i * blockSize, i * blockSize + read - 1, fileSize);
content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
var response = await client.PostAsync($"/upload/{uploadId}/chunk?index={i}", content, cancellationToken);
// 检查 200 或 206，记录已上传块索引}
-
ContentRangeHeaderValue是核心，服务端靠它定位写入位置；客户端必须自己维护index和已传字节偏移 - 每次请求前检查
cancellationToken.IsCancellationRequested，并在 catch 中保存当前块索引到本地文件 - 避免用
HttpClient默认实例——它复用连接但不保证长连接稳定，建议为上传任务新建带超时的HttpClient实例
进度条卡顿或不准的常见原因
不是 UI 线程没更新，而是你监听的“进度”单位错了。比如用 Stream.ReadAsync 的返回字节数累加，但没考虑网络缓冲区、TLS 加密开销、服务端响应延迟，导致前端显示“95% 卡住 30 秒”。真实进度应基于已确认写入服务端的字节数（即每个块 POST 成功后才累加）。
- 别在
ReadAsync后立即更新进度——那是读到内存的量，不是发出去的量 - 用
IProgress<long>回调，参数是「已成功提交的总字节数」，不是「已读取字节数」 - 如果服务端支持
206 Partial Content，可在上传前发 HEAD 请求校验已传块，避免重复上传 - WPF/WinForms 中更新 UI 一定要用
Dispatcher.Invoke或Control.Invoke，别在 Task.Run 里直接改控件属性
为什么上传 2GB 文件时偶尔报 HttpRequestException: Error while copying content to a stream？
这是 .NET HttpClient 底层在写入 socket 时被中断的泛化错误，90% 以上由以下三个原因导致：
- 服务端主动断连（Nginx 默认
keepalive_timeout 75s，大文件上传超时）→ 改成keepalive_timeout 3600并加proxy_read_timeout 3600 -
HttpClient实例被多处复用，某次请求设置了短超时（如Timeout = TimeSpan.FromSeconds(10)），影响后续上传 → 上传专用HttpClient必须设Timeout = Timeout.InfiniteTimeSpan - Windows 系统默认 TCP KeepAlive 时间太长（2 小时），中间网络设备（如企业防火墙）静默断开连接 → 在
HttpClientHandler中启用并缩短 keep-alive：handler.MaxConnectionsPerServer = 10; handler.SslOptions = new SslClientAuthenticationOptions { ApplicationProtocols = ... };（.NET 5+ 可设KeepAlivePingDelay）
真正稳的大文件上传，从来不是堆参数，而是拆解成「可验证、可回滚、可降级」的原子操作——块校验用 SHA256，失败时退到小块重试，连续 3 次失败就切回传统 multipart 兜底。
