nginx 1.25.0+ 支持 http/3 终结但不支持反向代理 http/3 上游，需编译启用 --with-http_v3_module 和 --with-stream_quic_module，内核 ≥5.4、放行 udp 443、强制 tlsv1.3，并配置 listen 443 quic reuseport 与 add_header alt-svc。
Nginx 1.25.0+ 可以原生终结 QUIC 连接并提供 HTTP/3，但不能反向代理 HTTP/3 上游；它解包后仍用 HTTP/1.1 或 HTTP/2 转发给后端。别指望“全链路 HTTP/3”，重点是让客户端更快、更稳地连上来。
确认 Nginx 版本与编译模块是否就绪
很多问题卡在第一步：你以为装了支持 HTTP/3 的 Nginx，其实没有。官方 mainline 包（如 Ubuntu 官方仓库的 nginx）从 1.25.0 起默认不启用 --with-http_v3_module 和 --with-stream_quic_module，必须手动验证：
- 运行
nginx -V 2>&1 | grep -E 'http_v3_module|stream_quic_module'，两行都得有输出才算完整支持 - 若无输出，说明你用的是预编译二进制包（比如 apt 安装的），需自行编译；
apt install nginx不等于支持 HTTP/3 - Ubuntu 用户可改用 Nginx 官方 mainline 仓库安装，但注意：即使用了官方 repo，也要检查
nginx -V输出——部分发行版打包时仍会禁用 QUIC 模块
listen 指令写法和 Alt-Svc 响应头必须配对
Nginx 不认 http3 on; 这种写法，这是常见误配点。HTTP/3 启用靠的是 quic 关键字，不是开关指令：
- 必须同时存在两行监听：
listen 443 ssl http2;（TCP 兼容旧客户端）和listen 443 quic reuseport;（UDP 启用 QUIC） -
reuseport很关键：它允许多个 worker 进程共享 UDP 端口，避免丢包；缺它会导致 QUIC 连接不稳定甚至失败 -
add_header Alt-Svc 'h3=":443"; ma=86400';必须加，且路径要匹配：如果监听的是:443，Alt-Svc 就不能写成h3=":8443"，否则浏览器直接忽略 - Alt-Svc 不是“可选优化项”，而是浏览器发现 HTTP/3 的唯一机制；没它，Chrome 就不会尝试 QUIC
系统层和 TLS 层的硬性约束常被跳过
QUIC 不是配置完 Nginx 就能跑的协议，OS 和 TLS 层缺一不可：
- 内核版本 ≥ 5.4（推荐 5.7+），低版本 UDP 性能差，
reuseport行为异常；用uname -r确认 - 防火墙必须放行
UDP 443——这是最常被忽略的一步；iptables -L -n | grep :443或ufw status查看，缺规则就加：ufw allow 443/udp - TLS 必须强制
ssl_protocols TLSv1.3;；QUIC 不支持 TLS 1.2 或降级协商，开了也无效 - OpenSSL 3.2+ 可用，但功能受限；BoringSSL 或 quictls 更稳妥；用
nginx -V查看链接的 SSL 库路径，再确认其是否含 QUIC 支持
验证是否真走 HTTP/3 而非“看起来像”
别信 curl -I https://example.com 的输出，它默认不支持 HTTP/3；真正验证得靠三处：
- Chrome 访问后打开
chrome://net-internals/#quic，搜索域名，看到 “Active” 状态才表示 QUIC 已建立 - 开发者工具 → Network → 任一请求 → Headers → 查看响应头是否有
alt-svc，且值格式正确（如h3=":443"; ma=86400） - 终端验证必须用支持 QUIC 的 curl：
curl -I --http3 https://example.com；这个 curl 需自行编译（含quiche或nghttp3），系统自带的几乎都不行
生产环境建议把 HTTP/3 终结交给 Caddy 或 Envoy，Nginx 回归它最稳的角色：处理静态资源、负载均衡、TLS 卸载。强行在 Nginx 上堆 QUIC，容易因模块兼容性或升级断层引入隐性故障。
