HttpClient 默认不支持 HTTP/3，需在 .NET 6+ 中显式启用：满足操作系统与 msquic/libmsquic 版本要求，设置 AppContext 开关、环境变量，并在请求中指定 Version 和 VersionPolicy；否则会降级或失败。

HttpClient 默认不支持 HTTP/3，必须显式启用并满足运行时条件

在 .NET 6+ 中，HttpClient 对 HTTP/3 的支持是可选且受限的：它仅在 Windows 11 / Windows Server 2022（或安装了 msquic 2.0+ 的 Windows 10 22H2+）、Linux（需 libmsquic 2.0+）上可用，且默认关闭。即使环境满足，HttpClient 仍会降级到 HTTP/2 或 HTTP/1.1，除非你主动配置。

关键操作步骤：

• 确保 DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER 环境变量未设为 false（Kestrel 不受影响，但 HttpClient 依赖此 Handler）
• 设置 AppContext.SetSwitch("System.Net.Http.EnableHttp3", true) —— 必须在应用启动早期（如 Main 方法开头）调用，晚于首次 HttpClient 实例化将无效
• 使用 HttpRequestMessage.Version 和 VersionPolicy 显式要求 HTTP/3：

  var request = new HttpRequestMessage(HttpMethod.Get, "https://example.com/");
  request.Version = HttpVersion.Version30;
  request.VersionPolicy = HttpVersionPolicy.RequestVersionExact;

• 注意：若服务端不支持 HTTP/3 或 TLS ALPN 协商失败，请求将直接失败（抛 HttpRequestException），不会自动降级 —— 这与浏览器行为不同

Kestrel 从 .NET 7 起原生支持 HTTP/3，但需手动开启监听并配置 TLS

.NET 7+ 的 Kestrel 已内置 msquic 集成，无需额外包，但默认不监听 HTTP/3 端口。启用前提是：必须使用 HTTPS（HTTP/3 不允许明文），且证书需支持 ALPN（绝大多数现代证书都满足）。

Linux Distros

Linux发行版游乐场，适用于需要临时Linux沙箱、基于浏览器的Linux虚拟机、一次性终端环境、桌面Linux会话等场景

下载

典型配置方式（Program.cs）：

• 在 WebHostBuilder 或 WebApplicationBuilder 中调用 ConfigureKestrel
• 为 HTTPS 终结点显式启用 HTTP/3：

  builder.WebHost.ConfigureKestrel(serverOptions =>
  {
      serverOptions.ListenAnyIP(5001, listenOptions =>
      {
          listenOptions.UseHttps(); // 必须
          listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
      });
  });

• 若使用自签名证书（如开发环境），需确保它包含 SAN（Subject Alternative Name），否则 msquic 会拒绝握手
• Linux 上需提前安装 libmsquic（如 Ubuntu 22.04：apt install libmsquic1），且版本 ≥ 2.0.0；否则 Kestrel 启动时会静默跳过 HTTP/3 监听

验证 HTTP/3 是否真正生效的三个关键检查点

光看配置不等于跑通。常见“看似启用实则降级”的情况比比皆是。

• 客户端侧：捕获 HttpResponseMessage.Version —— 若返回 HttpVersion.Version30 才算成功；VersionPolicy 设为 RequestVersionOrHigher 会导致你误以为启用了 HTTP/3，实际可能是 HTTP/2
• 服务端侧：启用 Kestrel 日志级别为 Debug，搜索日志中是否出现 ConnectionId:xxx started HTTP/3；没有该日志即未走 HTTP/3
• 网络层：用 Wireshark 抓包，过滤 udp.port == 443 并查看 QUIC 协议解析是否成功；若看到大量 UDP 包携带 QUIC 字样且 TLSv1.3 ALPN = h3，才是真实 HTTP/3 流量

HttpClient 与 Kestrel 的 HTTP/3 兼容性不是对称的

你能让 Kestrel 监听 HTTP/3，不代表你的 HttpClient 调用它就走 HTTP/3 —— 反之亦然。两者独立协商，受各自环境、配置、TLS 栈限制。

• Kestrel 作为服务端，只要监听配置正确 + 环境支持，就能响应 HTTP/3 请求；但客户端（比如浏览器或另一个 .NET 进程）能否发 HTTP/3，取决于它自身能力
• HttpClient 发起请求时，若目标地址 DNS 返回 A/AAAA 记录，且 TLS 握手时服务端通告 h3 ALPN，则可能升级；但若服务端 Kestrel 没开 HTTP/3 监听，或中间有不支持 QUIC 的代理（如旧版 Nginx、IIS），就会彻底失败
• 特别注意：.NET 的 HttpClient 在 Windows 上依赖系统 msquic DLL，而某些企业环境策略会禁用或锁定 DLL 加载路径，导致 DllNotFoundException: msquic.dll —— 此时即使代码全对也跑不通

HTTP/3 的启用不是开关一按就完事，每个环节（操作系统、TLS 栈、证书、网络中间件、客户端配置）都可能成为断点，其中 msquic 的加载时机和 ALPN 协商细节最容易被忽略。