nginx 从 1.25.0 版本起支持 http/3 终结，需编译启用 --with-http_v3_module 和 --with-stream_quic_module，依赖 boringssl 或 quiche 等 quic 兼容 tls 库，内核 ≥5.4、放行 udp 443、强制 tlsv1.3，并配置 listen 443 quic reuseport 与 add_header alt-svc。
标准 Nginx 源码本身不内置 HTTP/3 支持，必须通过引入外部 QUIC 实现（如 quiche 或 BoringSSL）并打补丁或指定第三方 SSL 库路径来启用。这不是简单加个模块开关的事，而是依赖底层 TLS 栈对 QUIC 的支持。
HTTP/3 依赖的核心是 QUIC 协议栈
Nginx 的 --with-http_v3_module 只是协议层“胶水”，真正处理加密、帧解析、连接管理的是底层 SSL 库。官方 OpenSSL 不支持 QUIC，所以必须替换为：
-
quiche（Cloudflare 开发）：需 git clone + 编译，Nginx 配置中用
--with-openssl=../quiche/deps/boringssl --with-quiche=../quiche -
BoringSSL（Google）：更轻量，常用于 Docker 构建，配置时指定
--with-openssl=/path/to/boringssl
二者都需提前编译好，且版本需与 Nginx 兼容（例如 Nginx 1.25+ 推荐搭配 quiche v0.20+ 或 BoringSSL commit hash 稳定版）。
源码编译时的关键配置参数
进入解压后的 Nginx 源码目录后，运行 ./configure 必须包含以下几项：
-
--with-http_ssl_module：HTTPS 基础，不可省略 -
--with-http_v3_module：启用 HTTP/3 协议解析 -
--with-stream_quic_module：让 stream 模块支持 QUIC 流量（反向代理 UDP 流量必需） -
--with-openssl=路径：指向已编译好的 BoringSSL 或 quiche 内置的 BoringSSL -
--with-quiche=路径（仅 quiche 场景）：显式声明 QUIC 实现位置
注意：--with-http_v2_module 建议同时开启，便于客户端降级兼容；ssl_protocols 必须包含 TLSv1.3，因为 HTTP/3 强制要求 TLS 1.3。
补丁不是主流方式，替代方案更可靠
过去部分旧版 Nginx（如 1.16–1.21）需手动打 quiche 补丁（如 patch -p1 ），但自 Nginx 1.23 起已将 HTTP/3 支持合并进主线，<strong>不再需要额外补丁</strong>。当前稳定推荐做法是：
- 选用 Nginx ≥ 1.25（官方原生支持 HTTP/3）
- 跳过补丁步骤，直接通过
--with-http_v3_module+ 第三方 SSL 库启用 - 若坚持用老版本（如 1.21），需严格匹配 quiche 分支（如 v0.15.x），否则 configure 会失败
验证是否成功启用
编译安装后，检查输出：
-
nginx -V 2>&1 | grep -i v3应显示--with-http_v3_module - 配置中监听
listen 443 udp quic;并配好证书后，启动无报错 - 用
curl -I --http3 https://your-domain.com或 Chrome DevTools 的 Network → Protocol 列查看是否显示h3
若出现 quic: connection refused 或 no application protocol，大概率是 TLS 版本不对、Alt-Svc 头缺失，或防火墙未放行 UDP 443 端口。
