Nginx 1.25.0+仅支持HTTP/3终结（接收QUIC并降级为HTTP/1.1或HTTP/2转发），不支持HTTP/3反向代理；需满足版本、模块、内核、UDP端口、TLS 1.3及兼容SSL库等全部前提，配置须含双listen指令与Alt-Svc头。
Nginx 从 1.25.0 版本起提供对 HTTP/3 的实验性支持，但仅限于“终结”（terminating）QUIC 连接，不支持反向代理 HTTP/3 上游。它接收客户端的 QUIC 流量，解包为 HTTP/1.1 或 HTTP/2 后再转发给后端服务。这是当前主线版本的核心能力边界，不是配置疏漏，而是架构限制。
前提条件必须全部满足
HTTP/3 不是开关式功能，缺一不可：
- Nginx 主线版本 ≥ 1.25.0，且编译时启用 --with-http_v3_module 和 --with-stream_quic_module
- 操作系统内核 ≥ 5.4（推荐 5.7+），确保 UDP socket 性能与稳定性
- 防火墙放行 UDP 443 端口（最常被忽略的生产故障点）
- SSL 库需为 BoringSSL、quictls，或 OpenSSL 3.2+（OpenSSL 3.0–3.1 功能受限）
- TLS 强制使用 TLSv1.3，禁用降级：添加 ssl_conf_command Options -no_middlebox_degradation;
- 证书路径正确，TCP 与 UDP 共享同一套证书（无需额外配置）
核心配置写法与常见误区
以下是最小可行 server 块配置，重点在监听指令组合与响应头：
- 必须同时存在两行监听：listen 443 ssl http2;（兼容旧客户端）和 listen 443 quic reuseport;（启用 QUIC）
- 不存在 http3 on; 指令——Nginx 官方配置语法中无此参数，启用靠的是 quic 关键字
- add_header Alt-Svc 'h3=":443"; ma=86400'; 是必需项，浏览器依赖该头部发现并切换协议
- 不支持 proxy_pass http3://...；后端通信始终为 HTTP/1.1 或 HTTP/2，无法透传 HTTP/3
- 避免在 location 块中使用 header_rewrite 类指令，HTTP/3 终结阶段部分 rewrite 行为不生效
验证是否真正启用 HTTP/3
别依赖默认 curl 输出，它不识别 H3：
- Chrome 访问后打开 chrome://net-internals/#quic，搜索域名，看到 Active 状态即成功
- 开发者工具 → Network → 任一请求 → Headers → 查看响应中是否存在格式正确的 Alt-Svc 头
- 终端验证需用支持 QUIC 的 curl：curl -I --http3 https://yourdomain.com（需提前编译含 quiche 的版本）
- Wireshark 抓包过滤 udp.port == 443，观察 QUIC handshake 流程（Initial、Handshake 包）
生产环境更稳妥的落地策略
坚持用 Nginx 全链路承载 HTTP/3 风险高、维护难。推荐分层架构：
- Caddy 2.7+：开箱支持 HTTP/3，自动申请/续期 Let’s Encrypt 证书，一行 reverse_proxy localhost:8080 即可将流量转给本地 Nginx
- Envoy 1.26+：通过 quic_transport_socket 启用 H3 监听，upstream cluster 指向 Nginx，可观测性与稳定性更强
- 避免使用 nginx-quic 实验分支：不兼容多数第三方模块（如 lua-nginx-module、headers-more），升级路径断裂
