跳到主要内容
安装配置教程

nginx http2 配置全流程:版本差异、server 块示例、报错排查与生效验证

nginx http2 配置 — 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` 是什么原因?

把 `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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。