nginx 实现 http/3 维护页的关键是统一协议处理与静态页正确传输：需编译支持 quic 的 nginx，配置 listen 443 quic reuseport，用顶层 if 判断 maintenance.flag 并 return 503，配合 error_page 指向 internal 的 /maintenance.html，显式设置 content-type。
Nginx 原生不支持 HTTP/3，需搭配 OpenSSL 3.0+、nghttp3 和 ngtcp2 编译，并启用 listen 443 quic reuseport; 才能开启 QUIC 协议。但 HTTP/3 是传输层协议升级，不影响维护页的呈现逻辑——维护公告页面的展示仍由 HTTP 状态码（如 503）或重定向（如 302）控制，与底层是 HTTP/1.1、HTTP/2 还是 HTTP/3 无关。
所以系统升级时显示统一维护页，关键不是“适配 HTTP/3”，而是确保：
✅ 所有协议版本（HTTP/1.1、HTTP/2、HTTP/3）请求都命中同一套维护规则
✅ 维护页本身可被 HTTP/3 正常传输（即静态文件服务正常、MIME 正确、无 TLS 握手兼容问题）
以下是实际可行的配置要点：
用 return 503 + error_page 实现协议无关的维护页
这是最推荐的方式，简洁、可靠、全协议生效：
server {
listen 80;
listen 443 ssl http2;
listen 443 quic reuseport; # 启用 HTTP/3
server_name example.com;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
# HTTP/3 必需：TLS 1.3 + QUIC 兼容设置（如 ssl_early_data on;）
# 主动触发维护模式（例如检测到 maintenance.flag 文件存在）
if (-f /etc/nginx/maintenance.flag) {
return 503;
}
error_page 503 /maintenance.html;
location = /maintenance.html {
root /usr/share/nginx/html;
internal;
add_header Content-Type text/html; # 显式声明，避免 HTTP/3 下 MIME 推断异常
}
# 正常业务配置（location / {...}）放在此处下方
}
注意事项：
-
/maintenance.html必须真实存在，权限为644，属主为nginx或www-data -
internal;防止用户绕过维护逻辑直接访问该 URL -
add_header Content-Type可避免某些 HTTP/3 实现因缺少 MIME 类型而拒绝渲染 -
if (-f ...)判断放在 server 块顶层即可，对所有协议入口生效；Nginx 不允许在location内对return 503做条件判断时嵌套if，所以用这种顶层if是安全且标准的做法
验证是否对 HTTP/3 生效：
用支持 HTTP/3 的客户端（如 curl 8.0+）测试：
curl -I --http3 https://example.com/ # 应返回 503，且响应头含 content-type: text/html，body 为你写的 maintenance.html
不复杂但容易忽略的是：HTTP/3 的维护页和 HTTP/1.1 完全共用同一套 Nginx 配置逻辑，无需额外分支或协议判断。
