HTTP/3 并不是 HTTP/2 的简单升级，它把传输层从 TCP 换成了基于 UDP 的 QUIC 协议。这样一来，连接建立可以少一次 RTT，而且单个数据流的丢包不会阻塞其他流。对于需要大量并行请求的游戏资源下载场景，这个特性非常关键。Apache 作为常见的反向代理服务器，从较新版本开始通过 mod_http3 模块支持 HTTP/3，再配合 mod_proxy 和 mod_cache，就能在边缘节点同时完成协议卸载和内容缓存。Cocos 引擎开发的游戏往往需要从 CDN 或资源服务器拉取图片、音频、图集等小文件，如果底层网络栈支持 QUIC，弱网下的体验会有明显提升。下面先理清 Apache 启用 HTTP/3 的完整流程，再讨论缓存配置和 Cocos 端的接入方式。
Apache 启用 HTTP/3 需要哪些模块和配置
要让 Apache 监听 HTTP/3，首先需要确认编译时是否包含了 mod_http3。该模块依赖 quiche 或 nghttp3 库，不同发行版的预编译包可能未默认开启。你可以通过 apachectl -M | grep http3 检查模块是否加载，如果没有则需要自行编译或安装带 HTTP/3 支持的版本。编译时至少需要启用 --enable-http3 和 --with-quiche 等参数，具体根据源码版本的 configure 选项调整。安装完成后，在配置文件中加载以下模块：mod_http3、mod_proxy、mod_proxy_http、mod_cache、mod_cache_disk。
监听端口方面，HTTP/3 使用 UDP 443，而 HTTP/2 和 HTTP/1.1 仍然使用 TCP 443。Apache 的 Listen 指令需要同时声明两种协议，例如 Listen 443 http3 用于 UDP，Listen 443 用于 TCP。虚拟主机配置中必须通过 Protocols 指令列出支持的应用层协议，并开启 TLS，因为 HTTP/3 强制要求 TLS 1.3。下面是一个最小化的虚拟主机配置示例：
# 加载模块
LoadModule http3_module modules/mod_http3.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule cache_module modules/mod_cache.so
LoadModule cache_disk_module modules/mod_cache_disk.so
# 监听 HTTP/3 的 UDP 端口
Listen 443 http3
Listen 443
# 虚拟主机配置
<VirtualHost *:443>
ServerName game.ippipp.com
Protocols h2 h3 http/1.1
SSLEngine on
SSLCertificateFile /etc/ssl/certs/server.crt
SSLCertificateKeyFile /etc/ssl/private/server.key
# 启用 HTTP/3
H3Protocol on
H3MaxStreams 100
</VirtualHost>
证书配置与 HTTP/2 没有区别，但客户端会使用 TLS 1.3 的 ALPN 协商来确认是否走 HTTP/3。如果证书链不完整或者中间证书缺失，QUIC 握手会失败。另一个容易忽略的点是防火墙和负载均衡器必须放行 UDP 443 端口，只开放 TCP 443 会导致客户端无法尝试 QUIC，只能回退到 HTTP/2。对于生产环境，建议在 Apache 前面加一层支持 UDP 转发的 L4 负载均衡，例如使用 proxy_protocol 保留源 IP。
配置 Apache 反向代理与磁盘缓存策略
反向代理的核心是 mod_proxy，它把客户端请求转发给后端源站，再把响应返回给客户端。当后端是游戏资源服务器时，很多静态文件并不会频繁变化，适合在代理层做缓存。Apache 的 mod_cache 和 mod_cache_disk 提供了基于磁盘的缓存能力，配合 ProxyPass 指令即可实现边缘缓存。配置时需要注意，缓存只对可缓存的请求生效，默认情况下带 Authorization 头或 Set-Cookie 的响应不会被缓存，如果需要强制缓存可以通过 CacheIgnoreHeaders 调整。
下面这段配置把 /assets/ 路径的请求代理到后端 192.168.0.1:8080，并启用磁盘缓存：
ProxyRequests Off ProxyPreserveHost On # 代理静态资源路径 ProxyPass /assets/ http://192.168.0.1:8080/assets/ ProxyPassReverse /assets/ http://192.168.0.1:8080/assets/ # 磁盘缓存配置 CacheEnable disk /assets/ CacheRoot /var/cache/apache2/mod_cache_disk CacheDefaultExpire 3600 CacheMaxExpire 86400 CacheHeader on CacheDetailHeader on CacheIgnoreNoLastMod On CacheIgnoreHeaders Set-Cookie CacheLock on CacheLockMaxAge 5
CacheEnable disk /assets/ 表示对以 /assets/ 开头的 URL 启用磁盘缓存。缓存根目录 CacheRoot 必须存在且 Apache 进程有读写权限，否则缓存会静默失败。 CacheDefaultExpire 指定当源站没有提供 Expires 或 Cache-Control 时的默认过期时间，单位是秒。 CacheLock 用于避免缓存击穿，当多个请求同时请求同一个未缓存的资源时，只有一个请求会转发到后端，其余等待锁释放。
在实际测试中，你会发现即使 Apache 配置了 HTTP/3，缓存命中率依然可能不高。原因是游戏资源 URL 经常带版本号参数，例如 /assets/sprite.png?v=20240901，而 Apache 默认缓存键包含完整查询字符串。如果版本号频繁变化，缓存将失效。解决方法是使用 CacheKeyBaseURL 或重写规则去掉版本参数，或者让后端在响应中显式设置 Cache-Control: public, max-age=86400。另一个细节是 mod_cache 默认只缓存状态码为 200 的响应，304 响应不会进入缓存，这一点在配合 Last-Modified 条件请求时需要留意。
Cocos 游戏引擎如何接入 QUIC 通信
Cocos 引擎的网络请求通常封装在 XMLHttpRequest 或 WebSocket 中。在原生平台上，这些接口的底层实现依赖 libcurl 或平台自带的网络库。要让 Cocos 游戏实际使用 HTTP/3，必须确保底层 HTTP 客户端支持 QUIC。目前 libcurl 从 7.73 版本开始支持 HTTP/3，但需要编译时显式启用 quiche 或 nghttp3 后端。如果是 Web 平台，浏览器会自动处理 HTTP/3，无需额外配置；如果是 Android 或 iOS 原生包，则需要替换或重新编译网络库。
在实际开发中，Cocos 的 network::HttpRequest 允许设置请求 URL 和超时时间，但不会直接暴露传输层协议选择。如果 libcurl 编译时支持 HTTP/3，它会在 HTTPS 请求中自动尝试 QUIC，失败后回退到 TCP。因此，Cocos 端不需要修改业务代码，只要保证构建时链接的 libcurl 版本正确即可。下面是一段简单的 Cocos C++ 代码，演示如何用 HttpRequest 请求一个由 Apache 代理缓存的资源：
#include "network/HttpClient.h"
using namespace cocos2d::network;
void downloadGameAsset(const std::string& url)
{
HttpRequest* request = new HttpRequest();
request->setUrl(url.c_str());
request->setRequestType(HttpRequest::Type::GET);
request->setResponseCallback([](HttpClient* client, HttpResponse* response)
{
if (response && response->isSucceed())
{
std::vector<char>* buffer = response->getResponseData();
// 处理资源数据
CCLOG("Asset downloaded, size: %zu", buffer->size());
}
else
{
CCLOG("Request failed");
}
});
HttpClient::getInstance()->send(request);
request->release();
}
上面的代码没有显式指定 HTTP/3，但如果链接的 libcurl 支持 QUIC，访问 https://game.ippipp.com/assets/sprite.png 时会优先建立 QUIC 连接。为了验证是否真的走了 HTTP/3，可以在 Apache 端通过日志记录协议版本，或者在客户端抓包查看 UDP 443 的流量。对于 Cocos Web 版本，JavaScript 里的 fetch 或 XMLHttpRequest 由浏览器处理，只要浏览器支持 HTTP/3，就可以直接享受 QUIC 的优势。
有一种常见的误区是认为在 Cocos 中实现 QUIC 必须自己写 socket 代码。实际上，HTTP/3 隐藏在 HTTPS 协议栈之下，业务层无需感知。只有当你需要自定义传输协议、绕过 HTTP 层直接使用 QUIC 流时，才需要引入专门的 QUIC 库，例如 quiche 或 msquic。对于大多数游戏资源下载场景，依赖 libcurl 的 HTTP/3 能力已经足够。不过，如果 Cocos 引擎使用原生 WebSocket 进行实时通信，QUIC 并不适用，因为 WebSocket 基于 TCP，除非改用 WebTransport 协议，后者才是基于 QUIC 的双向流解决方案。
性能优化与常见问题排查
启用 HTTP/3 后，最大的性能收益来自连接建立时间的缩短。TLS 1.3 配合 QUIC 的 0-RTT 功能，如果客户端之前已经与服务器建立过会话，后续连接可以直接发送应用数据，无需等待握手完成。Apache 通过 SSLSessionTickets 和 SSLSessionCache 支持会话恢复，但 0-RTT 需要在 QUIC 层面额外配置，且存在重放攻击风险。对于游戏资源分发，如果资源请求可以幂等，开启 0-RTT 能显著降低弱网下的加载延迟。
缓存方面，mod_cache_disk 的磁盘 I/O 可能成为瓶颈。如果缓存目录在机械硬盘上，高并发时不如使用 mod_cache_socache 配合共享内存或 tmpfs 来得快。但 socache 缓存容量有限，适合热资源，对于大规模资源库还是需要磁盘缓存。建议把 CacheRoot 放在 SSD 上，并定期清理过期的缓存文件。另外，HTTP/3 的多路复用允许在一条 QUIC 连接上并发传输大量流，但如果 Apache 端每个流都触发磁盘读取，会导致随机 I/O 激增，可以通过调整 H3MaxStreams 和系统文件描述符上限来缓解。
排查 HTTP/3 问题时，首先要确认客户端和服务器之间的 UDP 443 是否可达。可以使用 curl --http3 命令测试，如果 curl 没有编译 HTTP/3 支持，可以用 quiche-client 或浏览器开发者工具查看协议。其次检查 Apache 错误日志中是否有 mod_http3 的报错，例如证书不支持、ALPN 协商失败等。最后，如果发现客户端总是回退到 HTTP/2，很可能是中间设备丢弃了 UDP 包，或者 Apache 只监听了 TCP 443。生产环境必须保证防火墙、安全组、负载均衡器的 UDP 转发链路完整。
还有一个容易忽视的问题是缓存与 HTTP/3 的交互。由于 QUIC 连接可能由不同线程处理，mod_cache 的缓存写入需要线程安全，Apache 已经做了内部锁，但如果多个子进程同时写同一个缓存条目，可能会产生临时文件或竞争。通常 CacheLock 可以解决这个问题，但会增加少量延迟。结合 Cocos 的请求特点，建议对体积较大且不常变的资源设置较长的 max-age，对频繁更新的配置文件关闭缓存或使用短过期时间，这样既能减少源站压力，又能避免缓存不一致。
Apache代理缓存HTTP/3QUIC协议修改时间：2026-08-19 23:51:25