Debian 13 的 Nginx 启用 HTTP/3：确认模块、加四行配置、验证与回滚

Debian 13 自带的 Nginx 是 1.26.3，编译参数里已经包含 --with-http_v3_module（本文写作时在本机 nginx -V 实测确认过）。也就是说不需要重装、不需要重新编译，加上 QUIC 监听和协议通告就能启用 HTTP/3。

HTTP/3 跑在 UDP 的 QUIC 上，相比 HTTP/2 少了 TCP 层的队头阻塞，弱网和跨境链路的收益最明显；代价是配置里要多开一个 UDP 443，并确认防火墙放行。

1、先确认 Nginx 支不支持

1.1 查编译参数

nginx -V 2>&1 | tr ' ' 'n' | grep http_v3

输出里有 --with-http_v3_module 才继续；没有的话得换发行版自带的包，或者自己编译。

1.2 版本要求

nginx -v

要 ≥ 1.25.1：新版写法用 http2 on; 指令，老版本是把它写在 listen ... http2 末尾，两者不通用。Debian 13 的 1.26.3 没问题。

2、单站点：加四行配置

2.1 找到 vhost 文件

# Debian 官方 nginx 包
nano /etc/nginx/sites-available/wordpress

# 宝塔面板
nano /www/server/panel/vhost/nginx/你的域名.conf

宝塔用户也可以直接在面板的「网站 → 设置 → 配置文件」里改，改完手动重载。

2.2 在 HTTPS 的 server 块里加

# 原有 HTTPS：TCP 443，保持不动
listen 443 ssl;
listen [::]:443 ssl ipv6only=on;
http2 on;

# 新增 HTTP/3：UDP 443
listen 443 quic reuseport;
listen [::]:443 quic reuseport;
http3 on;

# 告诉浏览器本站支持 HTTP/3
add_header Alt-Svc 'h3=":443"; ma=86400' always;

2.3 这几行分别在做什么

• listen 443 quic：监听 UDP 443，QUIC 跑在 UDP 上；
• http3 on：在这个 server 块启用 HTTP/3；
• Alt-Svc：给浏览器的通告，让它下次访问优先尝试 h3；ma=86400 是缓存 24 小时；
• reuseport：同一地址端口复用监听，多 worker 才能分摊；同一地址+端口只能指定一次，见下一节。

3、多站点：reuseport 只能写一次

这是最容易踩的坑。同一地址、同一端口的 socket 参数只能指定一次，所以第一个站点写了 reuseport，后面的站点不能再写，否则 reload 会报地址占用。

第二个站点的写法：

listen 443 quic;
listen [::]:443 quic;
http3 on;

add_header Alt-Svc 'h3=":443"; ma=86400' always;

顺序无所谓，只要整个配置里只有一处带 reuseport。

4、TLS 1.3 是硬要求

HTTP/3 只跑在 TLS 1.3 上，没开 TLS 1.3 的话前面的配置等于白写：

ssl_protocols TLSv1.2 TLSv1.3;

用 Certbot 管理证书的站点一般不用管：/etc/letsencrypt/options-ssl-nginx.conf 默认就启用了 TLS 1.3。

5、检查与平滑重载

nginx -t
systemctl reload nginx

nginx -t 必须先通过，通过后再 reload；reload 是平滑加载，不断开已有连接。

6、验证是否生效

6.1 在线检查

打开 http3check.net，输入域名，会直接给出是否支持 HTTP/3 以及协商信息。

6.2 命令行

curl --http3 -I https://你的域名

前提是 curl 本身编译了 HTTP/3 支持；发行版自带的 curl 往往没有，看到「unknown option」不是配置的问题。

6.3 浏览器

DevTools → Network → 看 Protocol 列是否显示 h3。注意第一次访问仍是 HTTP/2：浏览器读到 Alt-Svc 并缓存后，第二次访问才会尝试 h3，测试时刷新或重开标签页。

7、常见问题与回滚

• 配置全对但不生效：先确认防火墙放行了 UDP 443，多数机器只开了 TCP 443；
• 套了 CDN：Cloudflare 这类要在面板单独开 HTTP/3，否则源站开了、用户侧看到的仍是 h2；
• 宝塔/面板用户：面板里保存配置后不一定自动 reload，记得手动执行；
• 不要在 UDP 的 listen 上加 ssl：listen 443 quic ssl 会报错，QUIC 的加密由 TLS 1.3 在协议内完成；
• 回滚：删掉 listen ... quic、http3 on、Alt-Svc 三处，nginx -t 后 reload，TCP 侧完全不受影响。

要不要开取决于用户网络：移动网络、跨境链路的收益明显；纯国内稳定链路收益有限，但成本就是这几行配置，试一下不吃亏。

参考：lala.im《Debian 13 配置 Nginx 启用 HTTP/3》 · nginx 官方 http_v3 模块文档