Nginx HTTP/2 Server Push 日志级别怎么设置？http2_push_diary_log_level 存在吗？

想要把 Nginx HTTP/2 Server Push 的推送过程记录到日志，查看文档时却看不到 http2_push_diary_log_level 这个配置项。其实 Nginx 从未提供过这样一个指令，HTTP/2 Push 的可观测性需要从 error_log 的调试级别和 access_log 的协议变量入手。很多配置文件里出现的所谓 diary log level，要么是某个自定义脚本里的变量名，要么是对 Nginx 日志机制的误解。下面直接说明正确做法。

一、Nginx 的 HTTP/2 Push 配置与日志级别现状

Nginx 从 1.9.5 版本开始通过 ngx_http_v2_module 支持 HTTP/2，并提供了 http2_push 和 http2_push_preload 两条指令用于服务器推送。你可以在 location 或 server 块中明确列出要推送的资源，例如样式表和脚本文件：

server {
    listen 443 ssl http2;
    server_name ipipp.com;

    ssl_certificate     /etc/nginx/ssl/server.crt;
    ssl_certificate_key /etc/nginx/ssl/server.key;

    root /var/www/html;

    location / {
        http2_push /style.css;
        http2_push /app.js;
    }
}

在这个配置里，并没有任何叫做 http2_push_diary_log_level 的指令。Nginx 的日志级别只由 error_log 指令控制，可选值包括 debug、info、notice、warn、error、crit、alert、emerg。默认级别是 error，此时根本看不到 HTTP/2 Push 相关的内部事件，因为那些调试信息属于 debug 级别。

换句话说，如果你希望观察 Nginx 是否真的对某个资源发起了推送、推送的 URI 是否被正确识别、以及推送帧是否成功发出，就必须把 error_log 的级别调到 debug。不过全局开启 debug 会带来巨大的日志量和磁盘 I/O 压力，生产环境通常不会长期开启，而是配合 debug_connection 指令只对指定的客户端 IP 启用调试日志。

error_log /var/log/nginx/error.log debug;

更精细的做法是在 events 块里使用 debug_connection 限定调试范围。下面的例子中，只有来自 192.0.2.10 的连接会输出 debug 级别日志，其他连接仍然按照 info 级别记录：

events {
    debug_connection 192.0.2.10;
}

http {
    error_log /var/log/nginx/error.log info;
    # 其他配置省略
}

这样既能获得详细的 HTTP/2 Push 调试信息，又不至于让生产服务器的日志文件迅速膨胀。需要注意的是，debug_connection 的 IP 地址要填写实际发起测试请求的客户端公网 IP，而且如果测试客户端经过了 NAT 或代理，Nginx 看到的是代理 IP。

二、通过 error_log debug 观察 HTTP/2 Push 事件

当 error_log 设置为 debug 并且测试连接命中 debug_connection 后，Nginx 会输出大量内部事件日志，包括 HTTP/2 连接建立、SETTINGS 帧协商、PUSH_PROMISE 帧发送以及流状态变化等。在这些日志里，你可以搜索包含 http2 push 或 push uri 等关键字的内容，从而判断 Nginx 是否尝试推送了某个资源。不同版本的输出措辞略有差异，但核心信息都是围绕推送决策和推送结果展开的。

实际排查时，可以用 tail -f 配合 grep 实时过滤相关日志行。例如你的错误日志文件是 /var/log/nginx/error.log，执行下面的命令就能只看 HTTP/2 相关条目：

tail -f /var/log/nginx/error.log | grep -i "http2"

如果过滤后仍然看不到任何 push 相关记录，通常有几个原因：客户端不支持 HTTP/2 或禁用了服务器推送；http2_push 指令所在 location 根本没有匹配到请求；资源路径写错导致 Nginx 无法定位文件；或者客户端的 SETTINGS 帧里明确关闭了推送功能。此时可以先确认浏览器开发者工具中请求是否使用了 h2 协议，再检查 Nginx 的 access_log 中 $http2 变量值。

还有一点需要注意，debug 级别日志会包含大量连接读写、缓冲区操作等信息，推送相关的内容只占很小一部分。建议把日志短时间输出到独立文件，配合 grep 或 awk 提取有用片段，避免长时间盯着刷屏。

三、用 access_log 确认协议与辅助排查

access_log 默认只记录主请求，服务器推送的子资源一般不会单独生成访问日志行。因此，你不能指望通过访问日志看到每个被推送文件的 200 状态码。不过，可以利用 Nginx 内置的 $http2 变量来判断主请求是否在 HTTP/2 连接上完成。下面是一个自定义日志格式的示例：

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" http2=$http2';

access_log /var/log/nginx/access.log main;

在这个格式中，$http2 变量在 HTTP/2 连接上会输出 h2（TLS 加密）或 h2c（明文），如果值为空或显示为 http/1.1，说明协议协商没有成功，HTTP/2 Push 自然无法发生。你可以通过查看访问日志快速确认客户端是否走对了协议。

如果想要更直观地看到哪些资源被推送到客户端，建议结合浏览器开发者工具的网络面板，将请求列表按 Initiator 排序，标记为 Push 的请求就是服务器主动推送的内容。命令行环境下，也可以用 nghttp2 客户端发起请求并查看 PUSH_PROMISE 帧。日志只能告诉你 Nginx 是否执行了推送动作，最终是否被浏览器接受还要看客户端侧的表现。

四、生产环境日志级别建议与常见误区

生产环境长期使用 error_log debug 会迅速消耗磁盘空间并增加 CPU 负载，因为每个连接都会产生大量调试输出。通常建议将全局级别设置为 warn 或 error，只在需要排查 HTTP/2 Push 问题时临时加入 debug_connection 指令，并限定到测试机的 IP。排查完成后可以注释掉该指令并重新加载 Nginx，日志级别自动恢复为全局设置。

events {
    debug_connection 203.0.113.7;
}

http {
    error_log /var/log/nginx/error.log warn;
    server {
        listen 443 ssl http2;
        # 其余配置省略
    }
}

常见的误区包括：认为存在一个专门的 http2_push_diary_log_level 指令来控制推送日志；把 error_log 级别设置为 notice 就想看到推送事件；以及误以为 access_log 会为每个推送资源单独记录一行。实际情况是，Nginx 并没有针对 HTTP/2 Push 的独立日志级别，所有调试信息都整合在通用错误日志中，访问日志也只反映主请求。

总结下来，排查 Nginx HTTP/2 Push 的日志策略就是：平时保持 warn 或 error 级别，需要时用 debug_connection 临时打开特定客户端的 debug 日志，再结合 access_log 中的 $http2 变量和浏览器开发者工具，就能完整判断 Push 是否生效以及问题出在哪个环节。

Nginx HTTP/2 Server Push日志级别http2_push修改时间：2026-10-04 20:09:51