HTTP/3开启后不生效怎么排查

网站后台已经开启 HTTP/3，页面也能正常打开，但在浏览器中查看连接协议，显示的仍然是 h2。

出现这种情况，可能与 UDP 端口、服务器配置、CDN 设置或客户端网络有关。仅凭“开关已打开”或者“网站可以访问”，还不能确认 HTTP/3 已经生效。

本文按“查看实际协议、确认访问入口、检查端口与服务、验证连接结果”的顺序排查。

文中的 example.com 为示例域名，需要替换为自己的网站域名；服务器命令以 Linux 环境为例。

1. 先查看浏览器实际使用的协议

以桌面版 Chrome 为例：

1. 打开需要检查的网站。
2. 按 F12，或右键页面选择“检查”。
3. 进入 Network（网络） 面板。
4. 在请求列表的表头上右键，勾选 Protocol（协议）。
5. 刷新页面，查看目标请求对应的协议。

常见结果如下：

Chrome 官方文档明确说明，Protocol 列用于显示每个请求实际使用的协议。

检查时，优先找到网站主页面对应的 Document 请求，同时核对请求域名。

一个网页可能加载多个域名的图片、字体和脚本。因此，看到某个第三方资源使用 h3，并不能证明自己的网站主域名也已经使用 HTTP/3。

2. 确认浏览器连接的是源站还是 CDN

修改服务器之前，先确认网站的访问入口。

如果使用 CDN，浏览器与 CDN、CDN 与源站通常是两段独立连接，使用的 HTTP 版本可以不同。

以 Cloudflare 为例，其官方文档说明，HTTP/3 开关控制的是访客与 Cloudflare 之间的连接，目前不支持以 HTTP/3 连接源站。

因此，源站日志显示 HTTP/1.1 或 HTTP/2，并不能直接说明访客没有使用 HTTP/3。

接入 CDN 的网站，应先确认目标域名确实经过 CDN 代理，再检查该域名对应的 HTTP/3 设置。源站的 UDP 端口，则在源站本身需要对外提供 HTTP/3 时检查。

3. 检查 UDP 443 是否可用

HTTP/3 使用基于 UDP 的 QUIC。即使 TCP 443 可以正常访问，也不能据此判断 UDP 443 已经放通。UDP 连接受阻时，客户端可能改用基于 TCP 的 HTTP 版本。

本文按常见的 UDP 443 配置说明；如果实际使用其他端口，应检查对应端口。

对于直接对外提供 HTTP/3 的云服务器，需要核对：

• 云服务器安全组是否允许相应的 UDP 入站流量。
• 系统防火墙是否允许 UDP 443。
• Web 服务是否已经创建 UDP 监听。
• 前置负载均衡或端口转发是否支持并转发 UDP。

如果网站同时配置了 IPv4 和 IPv6，也要分别核对两种地址的监听与放行规则。

对于直接运行在宿主机上的服务，可以执行：

sudo ss -lunp 'sport = :443'

该命令用于查看本机 UDP 443 的监听情况及关联进程。没有对应结果时，应进一步检查服务是否启用了 QUIC 监听。

本机存在监听，只能说明服务已经绑定端口，不能证明外部网络一定可以访问。

使用 Docker 端口映射的部署，还需要结合第 5 节检查，不能只根据宿主机上的 ss 输出下结论。

如果需要独立验证配置，可以使用莱卡云 Linux 云服务器搭建测试站点。

查看官网购买链接： https://www.lcayun.com

9折优惠码：bloglcayun

4. 检查 Nginx 支持与 Alt-Svc 响应头

如果网站使用 Nginx，需要检查实际提供 HTTPS 服务的那个 Nginx 实例。

先查看版本和编译参数：

nginx -V 2>&1

重点确认是否包含：

--with-http_v3_module

Nginx 的 HTTP/3 支持依赖对应模块。只看版本号，或者配置了普通的 listen 443 ssl;，都不足以确认 QUIC 已经启用。还应检查目标站点是否配置了带 quic 参数的监听，并具备所需的 TLS 支持。

接下来查看网站响应头：

curl -sS --max-time 15 -D - -o /dev/null https://example.com/

这里应填写浏览器最终访问的 HTTPS 地址。

采用 Alt-Svc 公告 HTTP/3 的站点，可能返回：

Alt-Svc: h3=":443"; ma=86400

其中，h3 表示 HTTP/3，:443 表示同一主机的对应端口，ma 表示这条服务公告的缓存有效时间，单位为秒。

Alt-Svc 是服务能力公告，不是当前请求已经使用 HTTP/3 的证明。

浏览器可能先通过 HTTP/2 收到公告，再尝试建立 HTTP/3 连接。因此，第一次访问仍显示 h2，不能单独判定配置失败。

如果部署方案依赖 Alt-Svc，但实际响应中没有出现预期内容，应检查：

• 是否修改了正确域名对应的站点配置。
• 配置是否已经成功加载。
• 前面的 CDN 或代理是否修改了响应头。

修正 Nginx 配置后，先执行：

sudo nginx -t

检查通过后，再按原部署方式重载服务。

如果 Nginx 因证书与私钥不匹配而无法加载配置，可以参考本站的 SSL证书与私钥不匹配怎么办。

5. Docker 部署要检查 UDP 端口映射

使用 Docker 部署 Nginx、Caddy 等 Web 入口时，容易遗漏 UDP 映射。

例如：

ports:
  - "443:443"

这种写法默认发布 TCP 端口，不会同时发布 UDP。需要分别配置 TCP 与 UDP 映射。

如果容器内部的 HTTPS 和 HTTP/3 都使用 443，可以在现有 Web 服务的 ports 中配置：

ports:
  - "443:443/tcp"
  - "443:443/udp"

这只是端口配置片段，应放在实际提供 Web 入口的服务下，保留原来的镜像、挂载和其他设置。

修改后，在项目目录执行：

docker compose up -d web
docker compose ps

其中，web 需要替换为 Compose 中的实际服务名称；使用过自定义配置文件或项目名的，应沿用原来的启动参数。

端口映射属于容器创建配置。配置变化后，docker compose up -d 会按需重建容器，因此更新前应确认业务数据已经正确持久化。

如果修改后仍然没有生效，可以继续参考本站的 Docker修改配置不生效怎么办。

另外，发布 UDP 端口并不会自动让容器中的程序支持 HTTP/3，程序自身仍需正确启用相关功能。

6. 使用 curl 验证 HTTP/3 连接

建议在服务器之外、能够直接访问目标网站的设备上测试，以检查实际访问路径。

先执行：

curl --version

查看输出中的 Features 是否包含：

HTTP3

如果没有，说明当前 curl 构建没有提供 HTTP/3 支持，不能用它的“不支持参数”报错判断网站配置有问题。

确认工具支持后，执行：

curl --http3-only \
  --connect-timeout 10 \
  --max-time 20 \
  -sS -o /dev/null \
  -w 'HTTP version: %{http_version}\nStatus code: %{http_code}\n' \
  https://example.com/

请将网址替换为目标网站最终访问的 HTTPS 地址。

成功时，可能看到：

HTTP version: 3
Status code: 200

这里的 HTTP version: 3 表示该次请求实际使用了 HTTP/3；状态码则需要结合业务判断。例如，返回 403 仍可能已经成功建立 HTTP/3 连接，只是请求被网站拒绝。

测试时要区分两个参数：

因此，curl --http3 请求成功，并不能单独证明 HTTP/3 已经生效。

如果测试失败，应先查看具体错误，再检查 UDP 连通性、证书和服务配置。也可以换一个网络对比结果，判断问题是否集中在当前客户端的访问路径。

7. 根据现象缩小排查范围

排查过程中，每次调整后都应重新验证实际请求，避免同时修改多处配置，导致无法判断是哪一步解决了问题。

8. 结语

HTTP/3 开启后不生效，需要结合访问入口、UDP 连通性、服务配置和客户端能力逐项检查。

浏览器中目标请求显示 h3，或支持 HTTP/3 的 curl 返回实际协议版本 3，才是判断该次连接使用 HTTP/3 的直接依据。

确认协议正常后，还应结合页面加载时间、请求失败率和不同网络下的访问表现，评估网站的实际使用效果。