Nginx 启用 HTTP/3 配置教程（含排障）

一、环境准备
Nginx 版本要求
必须使用 Nginx 1.25.0 或更高版本（官方实验性支持 HTTP/3）。

nginx -v  # 验证版本

开放 80/443 端口
云服务器需要确保安全组和服务器内部防火墙均放行如下端口：

HTTP/1 基于 TCP 协议，需确保防火墙放行 TCP/80 流量。
HTTP/2 基于 TCP 协议，需确保防火墙放行 TCP/443 流量。
HTTP/3 基于 QUIC（Over UDP）协议，需确保防火墙放行 UDP/443 流量。

二、核心配置
在 Nginx 配置文件（如 /etc/nginx/nginx.conf 或站点配置文件）中修改 server 块：

server {
    listen 80;
    listen 443 ssl;
    listen 443 quic reuseport;  # 启用 QUIC 并优化 UDP 性能

    # IPv6 监听
    listen [::]:80;
    listen [::]:443 ssl;
    listen [::]:443 quic reuseport;

    # 强制启用 HTTP/2（兼容旧客户端）
    http2 on;

    # SSL 证书配置（必须使用 TLS 1.3）
    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_protocols       TLSv1.3;  # HTTP/3 强制要求

    # 协议协商响应头（核心）
    add_header Alt-Svc 'h3=":443"; ma=2592000, h3-29=":443"; ma=2592000';

    # 其它配置块...
}

关键说明

reuseport 只需在一个 server 块中启用，避免多个 worker 竞争端口。

Alt-Svc 头用于告知客户端支持 HTTP/3，ma=2592000 表示缓存有效期（30 天）。

需同时监听 TCP（HTTP/2）和 UDP（QUIC）端口以实现协议兼容。

参考文档 https://nginx.org/en/docs/http/ngx_http_v3_module.html

三、验证 HTTP/3 是否生效
浏览器验证
打开 Chrome/Firefox 开发者工具 → Network 面板 → 查看请求的 Protocol 列：

成功启用时显示 h3（HTTP/3）。

若显示 h2，需检查 Alt-Svc 头或清除浏览器缓存。

命令行测试
使用支持 HTTP/3 的 curl 版本验证：

curl -I --http3 https://your-domain.com  # 响应头应包含 Alt-Svc

在线检测工具
访问 https://http3check.net 输入域名检测协议状态。
四、性能优化建议
在 server 块中添加如下配置，参阅 https://nginx.org/en/docs/http/ngx_http_v3_module.html

quic_retry on;               # 启用 QUIC 重传
quic_gso on;                 # UDP 分段卸载（Linux 内核 ≥5.19）
quic_stream_buffer_size 64k; # 流缓冲区大小

五、常见问题排查

问题现象
解决方案

浏览器未切换至 HTTP/3
检查 Alt-Svc 头是否生效

UDP 端口被防火墙阻断
使用 tcpdump 抓包验证

Nginx 启动报错
检查 listen quic 语法

TLS 版本不兼容
确认 ssl_protocols 为 TLSv1.3