nginx http2 配置全流程:版本差异、server 块示例、报错排查与生效验证
nginx http2 配置的核心是:Nginx 1.25.1 及以上在 server 块写 `listen 443 ssl;` 加 `http2 on;`,1.25.0 及以下写 `listen 443 ssl http2;`,改完执行 `nginx -t && systemctl reload nginx`。 HTTP/2 在浏览器中要求 TLS + ALPN,`openssl s_client -alpn h2` 应返回 `ALPN protocol: h2`;否则检查 `ssl_protocols` 是否包含 TLSv1.2/TLSv1.3。 `http2_max_concurrent_streams` 默认 128,`http2_idle_timeout` 默认 3m,静态站点通常保持默认;高并发 API 可先观察再调到 256。 常见报错 `unknown directive "http2"` 多因版本低于 1.25.1 却写了 `http2 on;`;`the "listen ... http2" directive is deprecated` 则相反。 验证命令:`curl -I --http2 https://example.com` 返回 `HTTP/2 200`,`nginx -T | grep http2` 确认配置已加载。
为什么 nginx http2 配置写了却不生效?先看协议栈与版本前提
很多人把 listen 443 ssl http2; 加进去、nginx -s reload 也返回 0,浏览器 DevTools 里却仍是 h1.1。原因是 nginx http2 配置要真正生效,必须同时穿过三道关卡:二进制里编译了模块 → 传输层 ALPN 协商成功 → 配置语法与当前版本匹配。任何一道不满足,nginx 都不会报错,而是静默回落到 HTTP/1.1。
第一关:模块是否编进当前二进制。据 nginx 官方文档,HTTP/2 由 ngx_http_v2_module 提供,从 1.9.5 起可用,编译参数为 --with-http_v2_module,且该模块不随默认 ./configure 编译。用下面这条命令确认(nginx -V 输出到 stderr,必须重定向):
# 输出版本号、编译参数,只挑出与 HTTP/2 相关的部分
nginx -V 2>&1 | tr ' ' 'n' | grep -E 'nginx/|with-http_v2_module'
# 期望看到类似:
# nginx/1.24.0
# --with-http_v2_module
# 若无 with-http_v2_module 输出,说明该二进制不支持 h2,配置写了也是空转
第二关:ALPN。Chrome、Firefox、Safari 只在 TLS 上启用 h2,访问 http:// 一律走 HTTP/1.1;h2 的协商靠 TLS 扩展 ALPN(RFC 7301)。ALPN 需要 OpenSSL 1.0.2+,TLS 1.3 需要 OpenSSL 1.1.1+。先查本机:
openssl version
# OpenSSL 1.0.2k 以下:nginx http2 配置必然不生效,需升级系统 OpenSSL 后重编译 nginx
# 验证服务端是否真的谈成 h2(-alpn h2 是关键,缺省不会发 ALPN)
openssl s_client -connect example.com:443 -servername example.com -alpn h2 </dev/null 2>/dev/null | grep -E 'ALPN|Protocol'
# 成功:ALPN protocol: h2 失败:No ALPN negotiated 或 ALPN protocol: http/1.1
curl -sI --http2 https://example.com | head -1 # 成功返回 HTTP/2 200
证书链不完整同样会让部分客户端在握手阶段放弃 h2 并回落 h1——用 openssl s_client -connect example.com:443 -showcerts 确认是否返回了中间证书。
第三关:版本写法。1.25.1 起 listen ... http2 被弃用,改为在 server 块写 http2 on;;1.25.0 及更早只能写 listen 443 ssl http2;。写错的两个典型报错:
# 1.25.0 及更早版本里写 http2 on;
nginx: [emerg] unknown directive "http2" in /etc/nginx/conf.d/site.conf:5
# 1.25.1 及更新版本里仍写 listen 443 ssl http2;
nginx: [warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead in /etc/nginx/conf.d/site.conf:3
| Nginx 版本 | 正确写法 | 结果 |
|---|---|---|
| < 1.9.5 | 无 ngx_http_v2_module |
只能升级,h2 无法启用 |
| 1.9.5 – 1.25.0 | listen 443 ssl http2; |
生效;写 http2 on; 报 unknown directive |
| ≥ 1.25.1 | listen 443 ssl; + http2 on; |
生效;旧写法仅告警,后续版本将移除 |
默认值不是“无限并发”。据 nginx 文档:http2_max_concurrent_streams 默认 128,http2_idle_timeout 默认 3m,http2_chunk_size 默认 8k,http2_recv_buffer_size 默认 256k。多路复用减少的是 TCP 连接数,单连接内的并发流仍受 128 限制;前端资源极多的站点若看到 net::ERR_HTTP2_SERVER_REFUSED_STREAM,先查这一项而不是带宽。另外 http2_push 自 1.25.1 起已标记为 obsolete,Chrome 106 起也移除了 Server Push 支持,不要再投入配置成本。
反向代理的一个常见误解:客户端到 nginx 可以走 h2,nginx 到上游默认仍是 HTTP/1.0。想让上游 keepalive 生效需在 location 中写 proxy_http_version 1.1; 并显式 proxy_set_header Connection "";——但这两行不是 h2 的必要条件,别把它们当成 h2 不生效的原因去排查。
nginx http2 配置分步实操:6 步完成版本判断、改配置与 reload
做 nginx http2 配置,真正卡人的往往不是语法,而是版本:同一行 listen 在 1.24 和 1.25.1 上的合法写法不同。下面 6 步按顺序走,每一步都留了回退点。
第 1 步:先判断版本,再决定写哪种语法。
# 一次拿到 Nginx 版本、是否编译 http_v2 模块、链接的 OpenSSL 版本
nginx -V 2>&1 | tr ' ' 'n' | grep -Ei 'nginx/|with-http_v2_module|openssl'
# 典型输出:
# nginx/1.24.0
# --with-http_v2_module
# built with OpenSSL 3.0.13 30 Jan 2024
要点:OpenSSL 版本那一行以大写开头,用 grep -E 会漏掉,建议加 -i。低于 1.9.5 的 Nginx 没有 HTTP/2 支持(RFC 7540 于 2015 年发布,Nginx 在 1.9.5 跟进),只能升级;低于 1.25.1 时不要写 http2 on;,那是 1.25.1 才引入的独立指令。
| Nginx 版本 | 正确写法 | 写错的后果 |
|---|---|---|
| < 1.9.5 | 不支持,需升级 | 无 h2 可协商 |
| 1.9.5 – 1.25.0 | listen 443 ssl http2; |
写 http2 on; 报 [emerg] unknown directive "http2" |
| ≥ 1.25.1 | listen 443 ssl; + http2 on; |
旧写法只告警不中断:[warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead |
第 2 步:备份并留全量配置。nginx -T 会把所有 include 展开后输出,回滚时可直接比对。
cp /etc/nginx/conf.d/example.conf /etc/nginx/conf.d/example.conf.bak.$(date +%F)
nginx -T > /tmp/nginx-$(date +%F).conf # 展开全部 include,作为基线
第 3 步:确认证书路径。Let’s Encrypt 文档明确要求使用 fullchain.pem(叶证书 + 中间证书),只配 cert.pem 会让老 Android、Java 客户端在 ALPN 协商后握手失败。
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # 必须 fullchain
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
第 4 步:按版本写 listen。不要在 80 端口加 http2,浏览器不会在明文连接上走 h2,h2c 只对支持 Upgrade 的客户端有效,主流浏览器不支持。
server {
listen 443 ssl; # ≥1.25.1 写法;1.25.0 及以下改为 listen 443 ssl http2;
http2 on; # 仅 1.25.1+ 存在,低版本删除此行
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 1.23.4 起默认值即此,更早版本默认含 TLSv1/TLSv1.1
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384; # Mozilla intermediate 列表
ssl_prefer_server_ciphers off; # Mozilla 生成器对 TLS1.2 的建议值
}
第 5 步:测试并热加载。用 reload 而非 restart,worker 平滑替换、旧连接不断。
nginx -t && systemctl show -p MainPID --value nginx # 记下 master PID
systemctl reload nginx
systemctl show -p MainPID --value nginx # PID 不变才说明是 reload
第 6 步:立即验证协商结果。
curl -I --http2 https://example.com # 期望首行:HTTP/2 200
openssl s_client -alpn h2 -connect example.com:443 </dev/null 2>/dev/null | grep ALPN
# 期望:ALPN protocol: h2
tail -n 50 /var/log/nginx/error.log # 失败时第一时间看这里
若 curl 返回 HTTP/1.1 200,先执行 curl -V | grep HTTP2 确认 curl 自身编译了 nghttp2;若 openssl s_client 报 no application protocol 或 alert handshake failure,通常是证书链不全或 ssl_protocols 与客户端不重叠。排查顺序固定:版本写法(第 4 步)→ 证书链(第 3 步)→ 协议与套件(第 5 步)。
nginx http2 配置示例:1.25.x 与 1.24.x 的 server 块可直接复制
本节两份 server 块可直接复制,先跑 nginx -v 确认版本再选。原因是 nginx 1.25.1 把 HTTP/2 从 listen 参数改成了独立指令 http2,写错版本会直接启动失败。据 nginx 1.25.1 CHANGES 记录,http2 指令上下文为 http 与 server,默认值 off。
写法 A:nginx 1.25.1 及以上(推荐)
# 适用:nginx 1.25.1+;保存后 nginx -t && nginx -s reload
server {
listen 443 ssl; # 关键:这里不再追加 http2 参数
http2 on; # 独立指令,上下文 http/server,默认 off
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# 以下参数取自 Mozilla SSL Configuration Generator 的 intermediate 档
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off; # 默认 off,交给客户端择优
ssl_session_cache shared:SSL:10m; # 1m 约存 4000 个会话,10m 足够中等站点
ssl_session_timeout 1d;
ssl_session_tickets off; # 关闭 ticket,换取前向安全性
http2_max_concurrent_streams 128; # 默认 128,并发流上限
}
写法 B:nginx 1.24.x 与 1.25.0
# 适用:nginx ≤ 1.25.0;这些版本没有 http2 指令
server {
listen 443 ssl http2; # 唯一正确写法,http2 只能作为 listen 参数
server_name example.com;
# ... ssl_certificate / TLS 参数同上
}
若在 1.24.x 里照抄写法 A,会得到明确报错:
nginx: [emerg] unknown directive "http2" in /etc/nginx/conf.d/example.conf:4
nginx: configuration file /etc/nginx/nginx.conf test failed
反过来,在 1.25.1+ 继续写 listen 443 ssl http2; 不会报错,但 reload 时输出告警 the "listen ... http2" parameter is deprecated,建议尽早迁移。
| nginx 版本 | 正确写法 | 错误组合及后果 |
|---|---|---|
| ≤ 1.24.x | listen 443 ssl http2; |
加 http2 on; → [emerg] unknown directive,进程无法启动 |
| 1.25.0 | listen 443 ssl http2; |
同上,该版本仍未引入指令 |
| 1.25.1+ | listen 443 ssl; + http2 on; |
仍用 listen 参数 → 仅 deprecated 告警,功能正常 |
| 1.27.x | 同 1.25.1+ | http2_max_concurrent_streams 等旧指令部分构建标记 obsolete,升级前务必 nginx -t |
让日志能区分 h2 流量:$server_protocol 会输出 HTTP/2.0 或 HTTP/1.1,把它放进自定义格式即可统计。
log_format main '$remote_addr - $server_protocol $request_method $scheme $request_uri';
access_log /var/log/nginx/access.log main;
# 统计 h2 占比:$server_protocol 落在第 3 列
awk '{print $3}' /var/log/nginx/access.log | sort | uniq -c
反向代理 location 别顺手开 h2:nginx 与上游之间用 HTTP/1.1 即可,上游不需要 HTTP/2。
location /api/ {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1; # 默认 1.0,必须显式改为 1.1 才能复用长连接
proxy_set_header Connection ""; # 配合 1.1 清空,避免透传 close
proxy_set_header Host $host;
}
# 同一 location 内不要再混用 grpc_pass,二者连接模型不同
证书选型:nginx http2 配置本身对证书等级没有任何要求,浏览器地址栏也不区分 DV/OV/EV,按预算选即可。据 Let’s Encrypt 文档,其 DV 证书免费、有效期 90 天,可用 certbot 自动续期。
| 证书类型 | 参考成本 | 典型场景 |
|---|---|---|
| Let’s Encrypt DV | 0 元,90 天自动续期 | 绝大多数站点,首选 |
| 商业 DV | 约 0–100 元/年 | 需要商业支持或保险赔付 |
| OV | 约 300–1500 元/年 | 企业合规、需展示组织信息 |
nginx http2 配置方案对比:http2 on、listen … http2 与 HTTP/3 怎么选
nginx http2 配置到底该写 http2 on; 还是 listen 443 ssl http2;?取决于你的 Nginx 版本。据 nginx 官方 CHANGES 记录,1.25.1 引入了独立的 http2 指令,同时把 listen ... http2 标记为废弃;1.9.5 起支持 HTTP/2(RFC 7540,已被 RFC 9113 取代)。在 1.25.1+ 上沿用旧写法,nginx -t 会输出告警:
nginx: [warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead
两种写法的关键差异是作用域:http2 on; 可放在 http 或 server 级,能按虚拟主机单独开关;listen ... http2 绑定在监听端口上,所有复用同一 listen 的 server 块都会被动启用 h2,想只给某个域名开就做不到。
# 写法 A:Nginx 1.25.1 及以上(推荐)
server {
listen 443 ssl; # 不再写 http2 参数
http2 on; # 可提到 http{} 级做全局默认
server_name example.com;
ssl_certificate /etc/nginx/ssl/example.com.pem;
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_protocols TLSv1.2 TLSv1.3; # 1.23.4+ 默认值即为 TLSv1.2 TLSv1.3
}
# 写法 B:Nginx 1.9.5 ~ 1.25.0
server {
listen 443 ssl http2; # h2 由端口决定,无法按 server 区分
server_name legacy.example.com;
}
HTTP/3 要不要一起上?1.25.0 起提供实验性 QUIC 支持(RFC 9114),但官方预编译包默认未启用,需以 --with-http_v3_module 自行编译。配置上必须额外监听 UDP 443 并通告 Alt-Svc,否则浏览器不会尝试 h3:
# 适用 Nginx ≥ 1.25.0 且编译了 --with-http_v3_module
server {
listen 443 ssl;
listen 443 quic reuseport; # UDP 443,防火墙需放行 udp/443
http2 on; # 保留 h2 作为回退
ssl_protocols TLSv1.3; # QUIC 强制 TLS 1.3
add_header Alt-Svc 'h3=":443"; ma=86400' always; # 缓存 24 小时
}
# 验证:nginx -V 2>&1 | tr ' ' 'n' | grep -E 'http_v2|http_v3'
| 方案 | 最低版本 / 依赖 | 作用域 | 传输层 | 适用与代价 |
|---|---|---|---|---|
http2 on; |
1.25.1+ | http / server,可按虚拟主机开关 | TCP + TLS | 新部署首选;老版本无法使用 |
listen 443 ssl http2; |
1.9.5 ~ 1.25.0 | 仅监听端口 | TCP + TLS | 存量配置兼容写法,1.25.1+ 告警 |
| HTTP/3(QUIC) | 1.25.0+,需 http_v3 模块 | listen 级 | UDP + QUIC + TLS1.3 | 抗丢包、弱网移动端收益明显;企业网常封 UDP 443,必须保留 h2 回退 |
调优参数怎么设?http2_max_concurrent_streams 默认 128(上下文 http/server),调到 256 能让高并发小请求少排队,但每个流都占内存并放大上游压力,静态小站通常无需改动;http2_idle_timeout 默认 3m,移动端建议保留默认,调小会频繁重连反而增加 TLS 握手;http2_max_field_size 默认 4k、http2_max_header_size 默认 16k,只有超长 Cookie 场景才需放宽。
成本上要花多少?h2 本身不额外收费,协议层只要一张证书即可:DV 证书 0–100 元/年(Let’s Encrypt 免费且支持 ACME 自动续期)足以启用 h2;OV 证书 300–1500 元/年主要用于企业身份展示。CDN 侧开启 h2 一般也不加价,可先用 curl -sI --http2 https://example.com | head -1 与 openssl s_client -connect example.com:443 -alpn h2 确认 ALPN 协商结果,再在日志中用 $server_protocol 统计 h2 占比,决定是否灰度 HTTP/3。证书与协议组合可参考 Mozilla SSL Configuration Generator 的 intermediate 配置档。
nginx http2 配置常见报错与排查:unknown directive、deprecated 与 ERR_HTTP2_PROTOCOL_ERROR
先把三条编译期/配置期报错分清楚,它们对应的是完全不同的 Nginx 版本与上下文问题,不要混为一谈。
问:`nginx: [emerg] unknown directive “http2” in /etc/nginx/conf.d/example.conf:8` 怎么办?
这是版本问题,不是拼写问题。`http2` 作为独立指令是 Nginx 1.25.1 才引入的(见 Nginx 1.25.1 changelog),更早的稳定版(如 1.24.x、1.22.x)只认 `listen … http2` 参数。先确认版本:
nginx -v # 输出形如 nginx version: nginx/1.24.0
# 方案 A:版本 < 1.25.1,回退到参数写法
# server { listen 443 ssl http2; ... }
# 方案 B:升级到 1.25.1+,保留新写法
# server { listen 443 ssl; http2 on; ... }
nginx -t && nginx -s reload
问:升级后出现 `nginx: [warn] the “listen … http2” directive is deprecated, use the “http2” directive instead in /etc/nginx/nginx.conf:15`,必须改吗?
不是致命错误,1.25.1+ 仍兼容旧写法,但每次 reload 都会刷警告,且该参数将在未来版本移除。改法是拆成两行:`listen 443 ssl;` 加 `http2 on;`。注意 `http2 on;` 的默认值是 off,写在 `http` 或 `server` 上下文都生效,写在 `server` 里更精确。
问:`nginx: [emerg] “http2” directive is not allowed here` 是什么原因?
- Wildcard 通配符 SSL 证书安装部署续费申请
- 代购 SSL 证书 · DigiCert / GeoTrust / RapidSSL 单域名与通配符
- HTTPS证书申请 · SSL证书安装部署 · 证书续费
把 `http2 on;` 放进了 `location`、`if` 或 `server_name` 附近。该指令的上下文仅限 `http`、`server`,不支持 `location`。协议协商发生在 TLS 握手阶段(ALPN,见 RFC 9113 第 3.3 节),不可能按 URL 路径切换,这也是它不能进 location 的根本原因。
| 报错 | 触发版本 | 根因 | 修法 |
|---|---|---|---|
| unknown directive “http2” | < 1.25.1 | 指令不存在 | 用 `listen 443 ssl http2;` 或升级 |
| listen … http2 is deprecated | ≥ 1.25.1 | 旧参数兼容保留 | 拆为 `listen 443 ssl;` + `http2 on;` |
| not allowed here | 全部 | 写进 location/if | 上移到 server 级 |
问:浏览器报 `net::ERR_HTTP2_PROTOCOL_ERROR`,页面白屏,怎么定位?
先看 `error.log`,常见两类:`client sent invalid HTTP/2 preface`(多为中间设备改写或客户端异常)和响应头超过缓冲区。Nginx 默认 `large_client_header_buffers 4 8k`、`proxy_buffer_size 4k|8k`(随平台),上游返回超大 Set-Cookie 或长 Location 就会崩流。临时放大验证:
# /etc/nginx/conf.d/example.conf 内 server 块
large_client_header_buffers 4 16k; # 默认 4 8k,单块上限受平台页大小约束
proxy_buffer_size 16k; # 默认 4k/8k,需 ≥ 上游最大响应头
# 验证后回看:tail -f /var/log/nginx/error.log
问:`curl: (92) HTTP/2 stream 0 was not closed cleanly: PROTOCOL_ERROR (err 1)` 说明什么?
多为上游返回 HTTP/1.0 响应、`Content-Length` 与实际 body 不符,或头部含非法字符。用 HTTP/1.1 对比即可判定是前端还是后端问题:`curl -v –http1.1 https://example.com/` 正常而 `–http2` 失败,问题在响应本身而非 Nginx 配置。
问:`openssl s_client -alpn h2` 显示 `No ALPN negotiated`,浏览器却回落 HTTP/1.1?
ALPN 未协商成功通常有两种原因:证书链不完整,或 `ssl_protocols` 禁掉了 TLSv1.2(现代浏览器要求 TLS1.2+,据 Mozilla SSL Configuration Generator 的 intermediate 配置为 `TLSv1.2 TLSv1.3`,而 Nginx 1.23.4 起默认值即为这两项)。检查命令:
openssl s_client -connect example.com:443 -servername example.com -alpn h2 </dev/null 2>&1 |
grep -E "ALPN|Verify return code|s:" # 期望看到 ALPN protocol: h2
# 若 Verify return code 非 0,说明缺中间证书,把 fullchain.pem 配到 ssl_certificate
# ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # 注意是 fullchain 不是 cert
# ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
按 Let’s Encrypt 文档的说明,`cert.pem` 只含站点证书,必须用 `fullchain.pem` 才能补全中间链;链不全时部分客户端会直接放弃 ALPN 协商,表现为”配置没错但 HTTP/2 就是不生效”。
nginx http2 配置生效验证:curl、openssl、浏览器与日志四路确认
先用一条命令做快速判定,再分四路交叉确认——单看浏览器绿锁或 curl 返回 200 都不能证明 h2 已生效,因为 TLS 握手成功与 ALPN 协商成功是两件事。值得注意的是,从 nginx 1.25.1 起 listen 443 ssl http2; 已被标记为废弃,升级后启动会看到 nginx: [warn] the "listen ... http2" directive is deprecated, use the "http2" directive instead,所以验证前先确认你查的是不是运行中的配置。
第一路:curl 客户端与服务端协商。先确认本地 curl 支持 HTTP/2,据 curl 官方文档,7.47.0 起内置 nghttp2,Features 行必须包含 HTTP2:
# 1) 客户端能力自检:Features 行应含 HTTP2(curl >= 7.47.0)
curl -V
# 输出示例:curl 8.5.0 (x86_64-pc-linux-gnu) libcurl/8.5.0 OpenSSL/3.0.13 zlib/1.3 nghttp2/1.58.0
# Features: alt-svc AsynchDNS HTTP2 HTTPS-proxy IPv6 ...
# 2) 强制 h2 请求,只看响应首行
curl -I --http2 https://example.com
# 生效:HTTP/2 200
# 未生效:HTTP/1.1 200 <-- 说明 ALPN 未协商到 h2
# 3) 看协商细节(curl >= 7.62.0 用 --write-out %{http_version})
curl -sI -o /dev/null -w '%{http_version}n' https://example.com # 期望输出 2
若第 2 步回落为 HTTP/1.1,不要先怀疑 nginx:curl --http2 只是“允许”而非“强制”h2,回落多半是服务端未开启 ALPN 或没配 h2。
第二路:绕开 curl,直接问 TLS 层要 ALPN 结果。这是排除客户端干扰最干净的方式(OpenSSL 1.0.2+ 支持 ALPN,据 OpenSSL 文档 -alpn 需配合 -servername 触发 SNI):
openssl s_client -connect example.com:443 -servername example.com -alpn h2
</dev/null 2>/dev/null | grep "ALPN protocol"
# 期望:ALPN protocol: h2
# 异常:No ALPN negotiated <-- 查证书链是否完整、是否强制 TLSv1.2+(h2 要求 TLS 1.2 及以上且禁用压缩)
第三路:浏览器实测。Chrome/Edge DevTools → Network 面板 → 表头右键勾选 Protocol 列 → 刷新,看到 h2 即为真;Firefox 打开 about:networking#http2 查看 HTTP/2 连接计数与“HTTP/2 已启用”状态。浏览器与 curl 结论不一致时,优先怀疑中间层(CDN、云 LB、反代)在终止 TLS。
第四路:配置与日志落盘。配置用 nginx -T(nginx 1.9.0+ 提供,含 include 展开后的完整配置)核对,模块用 nginx -V:
nginx -T | grep -nE "listen 443|http2" # 确认运行配置:新版应为 listen 443 ssl; + http2 on;
nginx -V 2>&1 | grep -o with-http_v2_module # 有输出才说明编译进 h2 模块(官方包默认包含)
# 在 http{} 或 server{} 内定义日志格式($server_protocol 自 nginx 1.0 起可用)
# log_format main '$remote_addr $server_protocol $request $status';
awk '{print $2}' /var/log/nginx/access.log | sort | uniq -c
# 生效:大量 HTTP/2.0;仍为 HTTP/1.1 说明流量走了别的 server 块或上游
四路手段对比,按可信度与用途排序:
| 手段 | 命令/位置 | 成功标志 | 主要盲区 |
|---|---|---|---|
| curl | curl -I --http2 |
HTTP/2 200 |
curl 版本过低会静默回落 |
| openssl | s_client -alpn h2 |
ALPN protocol: h2 |
只看 TLS 层,不验证 HTTP 语义 |
| 浏览器 | DevTools Protocol 列 / about:networking#http2 |
显示 h2 |
受 CDN、代理与缓存干扰 |
| 日志 | $server_protocol 聚合 |
HTTP/2.0 占多数 |
需改配置并 reload 才生效 |
最后做一次性能侧写,确认 h2 不只是“协商上了”而是真的在复用连接。据 nghttp2 文档,h2load 是唯一能原生跑 h2 的压测客户端:
# h2load 属 nghttp2-client 包(Debian/Ubuntu: apt install nghttp2-client)
h2load -n 1000 -c 50 https://example.com/ # 关注 requests/s 与总耗时
ab -n 1000 -c 50 https://example.com/ # 注意:ab 不支持 h2,仅作 HTTP/1.1 基线参考
把 ab 的数字当 h2 成绩是常见误判——它每次都退回 HTTP/1.1,两者的 requests/s 差异反映的是协议与多路复用差异,而非同一条件下的调优效果;对比时请固定 -n、-c 与目标路径,并确认服务端未开启 limit_conn 造成额外干扰。
nginx http2 配置上线检查清单:灰度、监控与 3 步回滚
把 listen 443 ssl http2; 或 http2 on; 写进配置只需要几秒钟,但决定这次 nginx http2 配置能否稳定上线的是之后的 10 分钟观测窗口和 1 分钟回滚能力。下面按执行顺序给出清单。
灰度:按 Nginx 实例切流,而不是改 upstream 的 weight。h2 是客户端与 Nginx 之间的协议,而 upstream 的 weight 控制的是 Nginx 到后端之间的 HTTP/1.1 连接,所以调 weight 不会让任何客户端用上 h2。真正的灰度粒度在接入层:先改一台边缘 Nginx,或者用四层 LB 或 DNS 给它 10% 的流量。配置侧只有一处随版本变化,据 Nginx 官方 changelog,1.25.1 起 listen 的 http2 参数被废弃,改为独立指令:
server {
listen 443 ssl; # 1.25.1+ 不再写 http2 参数,否则有 deprecated 警告
http2 on; # 1.9.5–1.25.0 请写 listen 443 ssl http2; 并删掉本行
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 不要为 h2 关掉 TLSv1.2,老客户端会直接握手失败
}
观测窗口固定 10 分钟,只盯两个信号:5xx 比例与 $request_time 的 p95。h2 不改变业务逻辑,但多路复用会把同一连接上的并发请求压到同一个 worker 上,单连接放大效应往往表现为 p95 抬升而非错误率上升。先在日志格式里带上协议与耗时:
log_format h2 '$remote_addr $server_protocol $status rt=$request_time';
access_log /var/log/nginx/access.log h2;
# 5xx 比例(字段 3 是 $status)
awk '$3 ~ /^5/ {e++} {t++} END{printf "5xx=%.2f%% (%d/%d)n", e*100/t, e, t}' /var/log/nginx/access.log
# $request_time p95
awk -F'rt=' '{split($2,a," "); print a[1]}' /var/log/nginx/access.log | sort -n
| awk '{v[NR]=$1} END{print "p95="v[int(NR*0.95)]"s"}'
监控:连接数下降、请求数不变才是正常形态。stub_status(模块自 1.7.5 起可用,默认关闭)只需三行即可开启,它给出 Active connections 与累计请求数:
location = /nginx_status {
stub_status; # 输出 Active connections / accepts / handled / requests / Reading / Writing / Waiting
allow 127.0.0.1;
deny all;
access_log off;
}
| 指标 | 采集方式 | HTTP/1.1 基线 | 启用 h2 后预期 | 异常判定 |
|---|---|---|---|---|
| Active connections | stub_status 首行 | 1000 | 300–600(明显下降) | 不降反升至基线 1.5 倍 |
| requests 增量 | stub_status 第 4 字段差分 | 5000 req/s | 5000±5% | 吞吐同比下降 >10% |
| h2 占比 | $server_protocol == HTTP/2.0 | 0% | 70%–95% | <50% 或长期 100% |
| 5xx 比例 | $status | 0.1% | ≤0.1% | >1% 持续 5 分钟 |
| $request_time p95 | access_log | 120ms | ≤120ms | 抬升 >30% |
h2 占比用一行 awk 就能出:awk ‘{t++; if($2==”HTTP/2.0″) h++} END{printf “h2=%.1f%%n”, h*100/t}’ /var/log/nginx/access.log。长期低于 70% 通常说明前置 LB 在做 TLS 终结、没有透传 ALPN;长期 100% 则要警惕是不是健康检查或内部调用被算进了统计。
回滚:三步,单机通常小于 1 分钟。改配置前先留带日期的备份,回滚时不要手工改回,直接覆盖:
cd /etc/nginx/conf.d
cp example.conf example.conf.bak.2025-01-01 # 变更前备份,回滚靠它
cp example.conf.bak.2025-01-01 example.conf # 1) 恢复
nginx -t # 2) 必须看到 "test is successful"
systemctl reload nginx # 3) 平滑重载,存量连接处理完再退出
如果第 2 步报 nginx: [emerg] unknown directive “http2” in /etc/nginx/conf.d/example.conf:12,说明当前版本低于 1.25.1,把 http2 on; 换回 listen 443 ssl http2; 即可;报 [emerg] “http2” directive is duplicate 则是 listen 参数和新指令同时存在。
安全与兼容。协议保持 ssl_protocols TLSv1.2 TLSv1.3;,不要为了“更安全”顺手删掉 TLSv1.2——h2 只要求 TLS 1.2+ 与 ALPN,而 Android 4.x 自带浏览器、Windows 7/8.1 上的 IE11 都不支持 ALPN,它们会静默回落 HTTP/1.1(Windows 10 的 IE11 支持 h2)。HSTS 用 add_header Strict-Transport-Security “max-age=31536000” always;(always 需 1.7.5+),但只应在全站 HTTPS 且所有子域都可 HTTPS 之后再加,否则回退窗口会被浏览器锁死一年。
文档:把可复现的证据写进变更单。至少记录 nginx -V 2>&1 | tr ‘ ‘ ‘n’ | grep -E ‘nginx/|openssl’ 的版本行、curl -sI –http2 https://example.com | head -1 返回的 HTTP/2 200(curl 需 7.47.0+ 且编译了 nghttp2)、证书到期日 openssl x509 -enddate -noout -in fullchain.pem。据 Let’s Encrypt 文档,证书有效期 90 天,续期后只需 reload 即可加载新证书,不需要改动任何 h2 相关配置——这也是把 http2 指令与证书路径分开写、不要耦合在同一行的现实理由。
官方预编译包通常已含 `–with-http_v2_module`;执行 `nginx -V 2>&1 | grep with-http_v2_module` 有输出即可。源码编译需显式加 `–with-http_v2_module`,Nginx 1.9.5+ 提供该模块。
不能。`http2` 指令在 1.25.1 才引入,1.24 写 `http2 on;` 会报 `unknown directive "http2"`;应使用 `listen 443 ssl http2;`。
先执行 `openssl s_client -connect example.com:443 -servername example.com -alpn h2` 看是否输出 `ALPN protocol: h2`,再查证书链与 `ssl_protocols`。若前面有 CDN,h2 可能终止在边缘,源站看到 h1 是正常的。
不必。先在 443/TCP 开 h2,确认稳定;Nginx 1.25.0+ 可灰度 HTTP/3,需放行 UDP 443 并加 Alt-Svc,h2 保留作回退。
h2 不是独立排名因素;Google 文档明确 HTTPS 是轻量排名信号。h2 多路复用可降低首屏资源加载时间,间接影响 Core Web Vitals。
1.25.1+ 兼容但建议改;把 `listen 443 ssl http2;` 拆成 `listen 443 ssl;` 和 `http2 on;`,`nginx -t` 后 `systemctl reload nginx` 即可。
不冲突。用户到 CDN 可走 h2,CDN 回源可用 h1 或 h2;若源站也开 h2,需确认 CDN 支持回源 h2,否则只在边缘生效。对比看,CDN 开 h2 通常无需改源站,适合不想动 Nginx 的站点;自建 Nginx h2 可控性更高,但需自己维护证书与版本。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。