用 HttpClient 下载单张图片最稳，因其支持取消、超时控制和流式读取；WebClient 已过时，易因无缓冲导致内存暴涨或重定向失败。
用 HttpClient 下载单张图片最稳，别碰 WebClient
默认情况下，WebClient 已被标记为过时（.NET 6+），且不支持取消、超时精细控制和异步流式读取。实际项目中下载图片出错——比如 403、重定向失败、大图内存暴涨——八成是因为它内部没做响应流缓冲，直接把整个图片 load 进内存。
正确做法是用 HttpClient 配合 Stream.CopyToAsync，边读边写磁盘：
using var client = new HttpClient();
using var response = await client.GetAsync("https://example.com/photo.jpg");
response.EnsureSuccessStatusCode(); // 抛出 4xx/5xx
<p>using var stream = await response.Content.ReadAsStreamAsync();
using var fileStream = File.Create("photo.jpg");
await stream.CopyToAsync(fileStream);
</p>
- 务必调用
EnsureSuccessStatusCode()，否则 404 也会静默返回空流 -
ReadAsStreamAsync()是关键：它不缓存整个响应体，适合大图 - 不要用
response.Content.ReadAsStringAsync()或.ReadAsByteArrayAsync()下载图片，会 OOM -
HttpClient实例应复用（全局静态或 DI 注入），别每次 new
多线程下载器用 Parallel.ForEachAsync 而不是 Task.Run 套循环
手动开一堆 Task.Run + DownloadFileAsync 看似简单，但极易失控：没有并发数限制、异常传播混乱、无法统一取消。.NET 6+ 的 Parallel.ForEachAsync 是专为此类 I/O 密集型批量任务设计的。
示例：同时下载 10 张图，最多并发 4 个请求：
var urls = new[] { "url1.jpg", "url2.jpg", /* ... */ };
var options = new ParallelOptions { MaxDegreeOfParallelism = 4 };
<p>await Parallel.ForEachAsync(urls, options, async (url, ct) =>
{
var fileName = Path.GetFileName(new Uri(url).LocalPath);
using var client = new HttpClient();
using var response = await client.GetAsync(url, ct);
response.EnsureSuccessStatusCode();</p><pre class="brush:php;toolbar:false;">await using var stream = await response.Content.ReadAsStreamAsync();
await using var fileStream = File.Create(fileName);
await stream.CopyToAsync(fileStream, ct);});
-
MaxDegreeOfParallelism必须设，否则可能瞬间发起几十个 TCP 连接，被目标站限流或封 IP - 每个迭代内创建独立
HttpClient实例是安全的（短生命周期），但若需加认证头或自定义 DNS，建议外部传入共享实例 -
ct（CancellationToken）会自动传递给所有异步操作，支持整体取消 - 异常会聚合在
AggregateException中抛出，需catch后遍历.InnerExceptions处理单个失败
下载路径、文件名、重定向要自己校验，HTTP 不保证你拿到的是 JPG
你以为 URL 以 .jpg 结尾就一定是图片？现实是：CDN 回源跳转后返回 HTML 登录页、防盗链触发 302 到错误页、API 返回 JSON 错误体——这些都可能悄无声息地写进你的 photo.jpg 文件里。
- 检查
response.Headers.ContentType，至少包含image/（如image/jpeg） - 用
response.RequestMessage.RequestUri对比原始 URL，确认没被重定向到非图片地址 - 文件名别全信 URL：用
Path.GetExtension()提取真实后缀，或根据ContentType补全（如image/png→.png） - 对关键业务，可加轻量校验：读取前 4 字节，比对 JPEG（
FF D8 FF）、PNG（89 50 4E 47）魔数
源码里最容易漏掉的三件事：超时、User-Agent、目录不存在时的 Directory.CreateDirectory
本地跑通不代表线上可用。生产环境常见失败点根本不在下载逻辑本身：
-
HttpClient默认无超时（底层TimeSpan.FromSeconds(100)是误导），必须显式设置：new HttpClient(new SocketsHttpHandler { PooledConnectionLifetime = TimeSpan.FromMinutes(5) })并配合cancellationTokenSource.CancelAfter(TimeSpan.FromSeconds(30)) - 很多图床校验
User-Agent，空值或默认值（dotnet/8.0）会被直接 403；加一句client.DefaultRequestHeaders.UserAgent.ParseAdd("Mozilla/5.0") - 目标路径如
./downloads/2024/06/不存在？File.Create会直接抛DirectoryNotFoundException；得在写入前Directory.CreateDirectory(Path.GetDirectoryName(filePath))
这些不是“锦上添花”，而是让下载器从玩具变成能塞进 CI 流水线、跑一整晚不崩的工具的关键细节。
