nginx 1.25.0+ 支持 http/3 终结但不支持反向代理 http/3 上游，必须同时满足编译含 --with-http_v3_module 和 --with-stream_quic_module、内核 ≥5.4、openssl ≥3.0（推荐 boringssl/quictls）、listen 443 quic reuseport 与 listen 443 ssl 共存、强制 tlsv1.3、手动 add_header alt-svc，缺一不可。
直接说结论：Nginx 1.25.0+ 必须同时满足「编译含 --with-http_v3_module 和 --with-stream_quic_module」、「内核 ≥ 5.4」、「OpenSSL ≥ 3.0（推荐 BoringSSL/QuicTLS）」、「listen 443 quic reuseport + listen 443 ssl 共存」、「强制 ssl_protocols TLSv1.3」、「手动加 add_header Alt-Svc」，缺一不可；apt 安装的默认包几乎全不满足，别试了。
怎么确认 Nginx 真支持 HTTP/3 而不是“看起来支持”
很多人配完重启就以为成了，其实 nginx -V 输出里没这两行，等于白搭：
-
--with-http_v3_module（HTTP/3 终结能力） -
--with-stream_quic_module（QUIC 流转发能力，反向代理虽不走 HTTP/3，但健康检查等依赖它）
运行：nginx -V 2>&1 | grep -E 'http_v3_module|stream_quic_module'，两行都得有输出。Docker 用户别只看镜像标签——docker exec -it nginx nginx -V 才算数。Ubuntu 官方源的 nginx 包（哪怕版本号是 1.25.x）通常禁用了这两个模块，必须换用 nginx.org 的 mainline deb 或自行编译。
listen 443 quic reuseport 不是可选项，是硬性要求
Nginx 不认 http3 on 这种写法，那是过时文档或错误配置。HTTP/3 启用靠的是 quic 关键字本身，且必须和 TCP 监听共存于同一 server 块：
- 必须同时写：
listen 443 ssl（TCP，兼容旧客户端）和listen 443 quic reuseport（UDP，HTTP/3 入口） -
reuseport强烈建议带上：它让多个 worker 共享 UDP 端口，避免单 worker 接收瓶颈；内核 - 不能写成
listen 443 ssl http2 quic：HTTP/2 是 TCP 协议，QUIC 是 UDP，语法上不兼容，Nginx 会报错 - 端口可以改（比如测试用
listen 8443 quic reuseport），但防火墙必须放行对应 UDP 端口：ufw allow 443/udp，只开 TCP 443 没用
Alt-Svc 头漏了，浏览器根本不会切 HTTP/3
Alt-Svc 不是“锦上添花”，是浏览器发现 HTTP/3 的唯一机制。没它，Chrome 就当没这回事：
- 必须加：
add_header Alt-Svc 'h3=":443"; ma=86400'; - 路径要严格匹配：如果
listen是:443，就不能写成h3=":8443"，否则被忽略 -
ma=86400是秒级有效期，设太短（如 60）会导致频繁协商，太长（如 31536000）不利于快速回退 - 这个头必须加在 server 块里，location 块里加无效；如果用了 proxy_pass，确保 upstream 不覆盖它
系统层和 TLS 层的坑比 Nginx 配置还致命
即使 Nginx 配对了，OS 和 TLS 不达标照样启动失败或连接超时：
- 内核版本必须 ≥ 5.4（推荐 5.7+）：
uname -r查，低版本 reuseport 行为异常，UDP 丢包率高 - OpenSSL 版本 ≥ 3.0，但功能受限；BoringSSL 或 QuicTLS 更稳妥——
nginx -V看--with-openssl=路径，再进该目录查openssl version -
ssl_protocols TLSv1.3;必须显式写死，QUIC 不支持 TLS 1.2 或降级协商，开了也无效 - 证书必须有效且域名匹配；Let’s Encrypt 的泛域名证书没问题，但自签名证书需客户端手动信任，Chrome 默认拒接
验证是否真走 HTTP/3：Chrome 开发者工具 → Network → 刷新页面 → 看 Response Headers 里有没有 alt-svc，Protocol 列显示 h3，Connection 列显示 quic —— 三者缺一不可。UDP 端口不通、Alt-Svc 写错、内核太老，都会导致只显示 h2 或 http/1.1。
