nginx 1.25.0+仅支持http/3终结，不支持反向代理；需满足版本≥1.25.0、启用--with-http_v3_module和--with-stream_quic_module、内核≥5.4、放行udp 443、强制tlsv1.3、使用boringssl/quictls等全部条件，并配置双监听与alt-svc头。

Nginx 从 1.25.0 版本起原生支持 HTTP/3 终结（terminating），关键不是加个模块就完事，而是整套环境协同生效。QUIC 基于 UDP，必须绕开 TCP 的限制，所以部署本质是“让客户端用 UDP 快速连上并解密”，而非追求全链路 HTTP/3。

Nginx Config Linter

对 Nginx 配置文件进行语法检查、验证和安全、性能审计。

下载

确认 Nginx 编译时已启用必要模块
官方 http_v3_module 仅在源码编译阶段启用才有效，预编译包（如 apt/yum 官方源）默认不含 QUIC 支持：

• 必须配置 --with-http_v3_module（HTTP/3 解析）
• 必须配置 --with-stream_quic_module（UDP 层 QUIC 支持）
• 同时保留 --with-http_ssl_module（TLSv1.3 强依赖）
  运行 nginx -V 2>&1 | grep -E "(v3|quic|ssl)" 可验证是否启用。若无输出，需重新编译。

系统与网络层不可跳过的硬性条件
QUIC 不是纯软件配置，OS 和网络策略缺一不可：

• 内核 ≥ 5.4（推荐 5.7+），低版本 reuseport 行为异常，UDP 丢包率高
• 防火墙必须显式放行 UDP 443：ufw allow 443/udp 或 iptables -I INPUT -p udp --dport 443 -j ACCEPT
• TLS 必须强制为 TLSv1.3：ssl_protocols TLSv1.3;，禁用降级（QUIC 不兼容 TLS 1.2）
• SSL 库建议用 BoringSSL 或 quictls；OpenSSL 3.2+ 虽可工作，但部分 QUIC 功能受限

Nginx server 块的核心配置写法
以下是最小可行配置，注意细节决定成败：

• TCP 和 UDP 监听必须共存：
  listen 443 ssl http2;（兼容旧客户端）
  listen 443 quic reuseport;（启用 QUIC，reuseport 是稳定性关键）
• Alt-Svc 响应头必须存在且路径匹配：
  add_header Alt-Svc 'h3=":443"; ma=86400';（不能写成 :8443 或省略引号）
• 证书路径对 TCP 和 UDP 共用，无需额外配置
• 不要写 http3 on; —— Nginx 官方配置中无此指令，启用靠的是 quic 关键字

验证是否真正走 HTTP/3 而非“看起来像”
curl 默认不支持 HTTP/3，别信 -I 输出：

• Chrome 访问后打开 chrome://net-internals/#quic，搜索域名，状态为 “Active” 才算成功
• 开发者工具 → Network → 点击任意请求 → Headers → 查看 Alt-Svc 是否存在、格式是否正确
• 终端用支持 QUIC 的 curl：curl -I --http3 https://yourdomain.com（需自行编译含 quiche 的版本）
• 浏览器 Network 标签页 Protocol 列显示 h3 即表示当前请求走 HTTP/3

不复杂但容易忽略