如何排查基于Node.js QUIC的HTTP/3测试环境连接故障

1. 先定位连通性故障的网段范围 #

因为已经验证过客户端本身可以正常通过HTTP/3访问公网服务，所以不需要再校验客户端的基础功能，直接定位链路和服务配置问题。
HTTP/3 完全基于 UDP 传输，和此前正常运行的 HTTP/2 服务走 TCP 的链路完全独立，TCP 1234 端口连通性正常不代表 UDP 端口通路正常。

• 第一步先在 WSL 内部执行本地测试：curl --http3 -v https://localhost:1234/
  • 若WSL本地测试都超时：问题出在Node服务的配置层面，直接往下走后续步骤排查
  • 若WSL本地测试可以正常访问，但Windows侧的Firefox、curl访问超时：核心问题出在WSL2的NAT网络适配层
    • WSL2默认采用独立虚拟NAT网段，默认仅自动映射TCP端口到Windows主机，UDP端口不会自动做地址映射
    • 排查操作：在WSL内执行ip addr show eth0拿到WSL实例的内网IP（通常为172.x.x.x网段），在Windows管理员权限的PowerShell中配置UDP端口转发规则，把Windows主机的1234 UDP流量转发到WSL实例的对应端口
    • 同步检查两道防火墙规则：Windows Defender 防火墙是否放行了入方向UDP 1234流量，WSL内部的ufw是否放行了UDP 1234入站流量

2. 校验ALPN协议的两端匹配性 #

Node服务端配置的ALPN值为h3-25，该值必须和客户端发起请求时携带的ALPN值完全一致，否则QUIC的TLS握手会直接失败，无任何后续通信数据。

• 查看客户端实际携带的ALPN值：用curl测试时加-v参数，从verbose输出中找到客户端发送的ALPN扩展值，常见的取值包括h3、h3-29、h3-27等
• 若客户端ALPN值和服务端配置的h3-25不匹配，要么调整Node服务的alpn配置为客户端支持的匹配值，要么重新编译对应版本的Node、curl，让两端的HTTP/3 draft版本完全对齐

3. 检查Node QUIC服务的监听绑定范围 #

当前脚本中的createQuicSocket({ endpoint: { port: 1234 } })配置如果没有显式指定绑定地址，需要确认服务的实际监听范围：

• 服务启动后，在WSL内执行ss -ulnp | grep 1234，查看UDP 1234端口的实际监听地址
• 如果监听地址是127.0.0.1或::1，说明服务仅绑定了本地回环地址，外部网络完全无法访问，需要在endpoint配置中加上address: '0.0.0.0'，强制绑定所有可用网络接口

4. 排除QUIC层的证书兼容问题 #

虽然同证书的HTTP/2服务可以正常访问，但QUIC对TLS证书存在额外的校验规则：

• 确认证书的SAN列表完全覆盖访问用的域名my.dev.domain.name，避免QUIC握手阶段的域名校验失败
• 确认Node编译时依赖的OpenSSL版本支持证书使用的加密算法，不会因算法不兼容中断握手流程

内容的提问来源于stack exchange，提问作者rekire