Debian / Ubuntu 下使用 HTTP/3 协议的 Nginx QUIC

以下操作需要 root 权限，本文命令均已带上 sudo 前缀，请确保当前用户拥有 sudo 权限；或者直接使用 root 用户操作并省略命令中的 sudo。其中 docker 命令未加 sudo：建议把当前用户加入 docker 用户组（sudo usermod -aG docker $USER，重新登录生效），或自行为 docker 命令加上 sudo。

#1、什么是 HTTP/3 和 QUIC？

HTTP/3 是一种基于 QUIC (Quick UDP Internet Connections) 协议的 HTTP 协议版本，它是 HTTP/2 的后继者，旨在改进 Web 性能和安全性。

HTTP/3 与之前的 HTTP 协议有很大的不同，最明显的区别是它使用 QUIC 协议而不是 TCP 协议来传输数据。

QUIC 是一种由 Google 开发的协议，基于 UDP，它在保持安全性的同时提供更快的连接和更少的延迟。与 TCP 不同，QUIC 允许多个请求同时在同一连接上进行，从而减少了网络拥塞和握手延迟的影响。

总的来说，HTTP/3 的设计目标是通过减少延迟和提高性能，为 Web 应用程序提供更快、更安全和更高效的用户体验。

#2、安装 Nginx Quic

这里我们推荐烧饼博客团队打包的 Nginx Quic 版本，它是基于最新的官方 1.25.0 源码打包的，支持 HTTP/3 和 QUIC 协议。

##2.1 更新系统并安装部分必要软件

bash

sudo apt update
sudo apt upgrade -y
sudo apt dist-upgrade -y
sudo apt install curl vim wget gnupg dpkg apt-transport-https lsb-release ca-certificates

##2.2 增加 GPG Key

bash

curl -sSL https://n.wtf/public.key | sudo gpg --dearmor -o /usr/share/keyrings/n.wtf.gpg

##2.3 添加 Nginx QUIC 源

bash

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/n.wtf.gpg] https://mirror-cdn.xtom.com/sb/nginx/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/n.wtf.list

如果你的服务器在国内，可以使用下面的源：

bash

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/n.wtf.gpg] https://mirror.iscas.ac.cn/sb/nginx/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/n.wtf.list

或

bash

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/n.wtf.gpg] https://mirror.nju.edu.cn/sb/nginx/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/n.wtf.list

##2.4 更新并安装 Nginx

bash

sudo apt update
sudo apt install nginx-extras -y

安装完毕后，我们可以使用 nginx -V 命令看到 Nginx 已经是最新的 1.31.2 主线版 + QUIC 了：

bash

root@debian ~ # nginx -V
nginx version: nginx-n.wtf/1.31.2
built by gcc 14.2.0 (Debian 14.2.0-19) 
built with OpenSSL 4.0.1 9 Jun 2026
TLS SNI support enabled

##2.5 使用 Docker 安装

你也可以使用 Docker 进行体验：

bash

docker run --name nginx --net host --restart always -v $HOME/nginx-config:/usr/src/docker-nginx/conf:ro -d ghcr.io/u-sb/nginx

此时配置文件的目录在当前目录的 nginx-config 文件夹下。

#3、配置 Nginx

首先，HTTP/3 仅支持 HTTPS 协议，因此我们需要准备好 SSL 证书，可以参考《Nginx 配置 SSL 证书》获取 SSL 证书。

其次，需要开启 TLS 1.3 支持，因为 HTTP/3 是基于 TLS 1.3 的，如果没有开启 TLS 1.3，那么 HTTP/3 将无法正常工作。

最后，需要添加 listen 443 http3 监听端口并开启 HTTP/3 支持，以及需要添加一个 Alt-Svc 的头部信息 add_header Alt-Svc 'h3=":443"; ma=86400';，用于告诉浏览器使用 HTTP/3 协议访问网站。

最后，需要添加 listen 443 quic 监听端口并开启 HTTP/3 支持，以及需要添加一个 Alt-Svc 的头部信息 add_header Alt-Svc 'h3=":$server_port"; ma=86400';，用于告诉浏览器使用 HTTP/3 协议访问网站。

因为这个修改，从 Nginx 1.25.0 开始，已经不支持 http3 的 listen 段，需要改为 quic。

另外，从 Nginx 1.25.1 开始，listen ... http2 已废弃，需要改为 http2 on，否则会报警告 nginx: [warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead：

我们附上一个基本的配置示例：

nginx

server {
	listen 443 ssl default_server;
	listen [::]:443 ssl default_server;
    # 开启 HTTP/3
	listen 443 quic reuseport;
	listen [::]:443 quic reuseport;
    # 开启 HTTP/2
    http2 on;

	server_name example.com;

	root /var/www/example.com;
	index index.html;

	ssl_certificate /etc/nginx/ssl/example.com.crt;
	ssl_certificate_key /etc/nginx/ssl/example.com.key;

    ssl_protocols TLSv1.3;
    ssl_ecdh_curve X25519MLKEM768:X25519:prime256v1:secp384r1;
    ssl_prefer_server_ciphers off;

	add_header Alt-Svc 'h3=":$server_port"; ma=86400' always;
    add_header X-protocol $server_protocol always;
}

请注意 listen 443 quic reuseport 里的 reuseport 参数，以及 listen 443 ssl default_server 里的 default_server 参数，所有 server 段里，只允许一个段出现 reuseport 和 default_server 参数，否则会报错。

另外 listen 段里的 ssl 无法和 quic 放一起，必须分开写两段。

#4、测试 HTTP/3

我们使用 Firefox 浏览器，因为目前 DNS SVCB/HTTPS 记录尚未普及，所以第一次访问的时候，浏览器还是走 TCP 协议使用 HTTP/2 或者 HTTP/1.1 请求你的网站，获取 Alt-Svc 的头部信息后，才会走 HTTP/3 协议，所以第一次访问以后，可以关掉浏览器重新打开再测试。

我们可以打开 F12 开发者工具，查看 Network 选项卡，可以看到 HTTP/3 协议的请求：

Firefox HTTP/3