Nginx 1.25.0+ 离线支持 HTTP/3 必须同时满足：编译启用 --with-http_v3_module、OpenSSL ≥3.0.12（需 enable-quic）、内核 ≥5.10、listen 443 quic reuseport 与 ssl 共存、强制 TLSv1.3、手动配置 add_header Alt-Svc，缺一不可。
HTTP/3 在离线内网环境中完成协议模块加载，核心不是“联网下载”，而是提前编译支持 QUIC 的 Nginx 可执行文件，并确保运行时依赖全部本地闭环。它不依赖在线包管理或动态加载远程模块，但对编译环境、OpenSSL 版本、系统内核及配置方式有明确要求。
必须满足的底层前提
OpenSSL ≥ 3.0.0（强烈建议 3.0.12+）
HTTP/3 依赖 TLS 1.3 的 ALPN 扩展与 QUIC 加密栈，旧版 OpenSSL（如 1.1.1w）虽可编译通过，但无法真正启用 HTTP/3，运行时会静默降级为 HTTP/2。离线环境下必须预装匹配的 OpenSSL 源码并静态链接或精确指定动态库路径。Linux 内核 ≥ 5.10（推荐 5.15+）
QUIC 协议栈需内核支持AF_XDP和SOCK_DGRAM的 UDP 高性能收发能力。低于此版本可能编译成功，但 listen 443 quic 会报错invalid argument或服务无法启动。-
Nginx 源码需启用
--with-http_v3_module
该模块自 Nginx 1.25.0 起正式进入主线，1.24.x 及更早版本不支持。离线编译时必须确认源码版本，并在./configure中显式开启：./configure \ --with-http_v3_module \ --with-http_ssl_module \ --with-http_v2_module \ --with-openssl=../openssl-3.0.12 \ --with-cc-opt="-I../openssl-3.0.12/include" \ --with-ld-opt="-L../openssl-3.0.12/lib -Wl,-rpath,../openssl-3.0.12/lib"
离线编译与部署关键操作
所有依赖必须同机编译，避免跨版本 ABI 不兼容
PCRE、zlib 可复用系统自带（若版本足够），但 OpenSSL 和 Nginx 必须在同一台离线构建机上完成编译——尤其是 OpenSSL 需./config enable-quic启用 QUIC 支持（部分发行版默认关闭），否则 Nginx 编译时检测不到 QUIC 接口，http3 on将无效。-
验证模块是否真实加载
启动后执行：nginx -V 2>&1 | grep -o "v3\|quic"
若输出含
v3，说明模块已编译进二进制；再检查配置语法：nginx -t
若提示
unknown directive "http3"，说明 configure 阶段未识别到 QUIC 支持，大概率是 OpenSSL 编译未启用 QUIC 或路径指定错误。 -
配置中禁用任何外部依赖项
离线环境严禁使用resolver、proxy_pass https://、grpc_pass等需 DNS 解析或 TLS 上游的功能。QUIC 监听仅用于终端直连，例如：server { listen 443 quic reuseport; listen 443 ssl; ssl_certificate /etc/nginx/ssl/internal.crt; ssl_certificate_key /etc/nginx/ssl/internal.key; http3 on; add_header Alt-Svc 'h3=":443"; ma=86400'; location / { root /usr/share/nginx/html; } }注意：
Alt-Svc头用于客户端协商，不依赖外网；证书可用自签名，无需 CA 信任链。
内网客户端如何验证 HTTP/3 生效
- 使用支持 HTTP/3 的浏览器（Chrome 110+、Edge 110+），访问
https://内网IP，打开开发者工具 → Network → 刷新页面 → 查看协议列是否显示h3； - 或用命令行工具（需提前离线部署）：
# curl 编译时需启用 nghttp3 + quiche 支持，较重，非必需 # 更轻量方式：用 openssl s_client 测试 ALPN 协商 openssl s_client -alpn h3 -connect 192.168.10.100:443 -servername example.local
若返回中含
ALPN protocol: h3，即表示服务端已正确通告 HTTP/3 能力。
不复杂但容易忽略
