如何配置Nginx实现HTTP/2服务器推送并完成访问日志格式转换？

HTTP/2服务器推送虽然已经推出较长时间，但在Nginx中的落地配置并不复杂，关键在于把推送策略和日志记录同步调整到位。很多站点升级到HTTP/2后只修改了listen参数，日志仍然沿用旧的combined格式，导致推送资源是否生效、连接是否真正复用都无从验证。本文以常见的静态资源优化场景为例，说明如何启用HTTP/2推送，并将访问日志转换为便于分析的结构化格式。

一、启用HTTP/2与配置基本的资源推送

Nginx从1.9.5版本开始支持HTTP/2，前提是编译时加入了ngx_http_v2_module模块。在服务端启用HTTP/2只需要在listen指令后添加http2参数，同时必须开启TLS。一个典型的HTTPS服务块如下：

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

    ssl_certificate     /etc/nginx/ssl/ipipp.com.crt;
    ssl_certificate_key /etc/nginx/ssl/ipipp.com.key;

    root /var/www/html;
    index index.html;
}

启用HTTP/2后，Nginx并不会自动推送任何资源，需要使用http2_push指令显式声明。这个指令通常放在location块中，后面跟上需要推送的文件路径。例如当用户访问首页时，希望同时推送全局样式表和核心脚本：

location = /index.html {
    http2_push /assets/css/style.css;
    http2_push /assets/js/app.js;
}

这样配置后，Nginx在返回index.html的同时，会主动向客户端发送style.css和app.js的PUSH_PROMISE帧，浏览器如果接受推送，就能省去后续的请求握手时间。需要注意，http2_push指令后面跟的是相对于root目录的URI路径，而不是文件系统绝对路径。如果路径错误，Nginx会记录错误，但不会影响主响应。

更灵活的方式是让Nginx根据响应头中的Link字段自动推送预加载资源。在http或server级别开启http2_push_preload，然后在需要推送的资源响应中添加Link头即可：

server {
    listen 443 ssl http2;
    http2_push_preload on;

    location = /index.html {
        add_header Link "</assets/css/style.css>; as=style; rel=preload";
        add_header Link "</assets/js/app.js>; as=script; rel=preload";
    }
}

这里在代码块中使用了HTML转义，把尖括号显示出来。实际配置文件中直接写<和>即可被add_header正确识别为Link头格式。自动推送的好处是后端应用可以通过响应头控制推送资源，而不需要在Nginx中逐个列出，适合多页面或动态场景。

二、自定义日志格式并转换为结构化输出

默认的Nginx访问日志格式是combined，字段包括了客户端地址、时间、请求行、状态码、用户代理等，但它没有记录HTTP协议版本。即使连接使用了HTTP/2，日志中的请求行仍然显示为HTTP/1.1，因为$request变量来源于客户端发送的请求行，而真实协议版本需要单独使用$server_protocol或$http2变量。$http2变量在Nginx 1.11.0及以上版本可用，值为h2表示HTTP/2 over TLS，h2c表示明文HTTP/2。

为了后续分析推送效果，建议新建一个JSON格式的日志模板。JSON结构化日志方便使用jq、Logstash、ClickHouse等工具解析，也能避免传统空格分隔日志中字段包含特殊字符导致的切割问题。以下是一个常用的JSON日志格式定义：

log_format json_http2 escape=json
    '{'
        '"remote_addr":"$remote_addr",'
        '"time_local":"$time_local",'
        '"request_method":"$request_method",'
        '"request_uri":"$request_uri",'
        '"status":$status,'
        '"protocol":"$server_protocol",'
        '"http2":"$http2",'
        '"body_bytes_sent":$body_bytes_sent,'
        '"request_time":$request_time,'
        '"http_referer":"$http_referer",'
        '"user_agent":"$http_user_agent"'
    '}';

access_log /var/log/nginx/access.json json_http2 buffer=32k flush=5s;

这里的escape=json参数非常关键，它会把变量值中的双引号、反斜杠等字符自动转义，保证每一行都是一个合法JSON。如果没有这个参数，当用户代理字符串里出现双引号时，日志行就会变成损坏的JSON，下游解析器直接报错。此外，buffer=32k和flush=5s可以降低频繁写入磁盘的压力，同时保证日志延迟不超过5秒。

如果已经积累了旧格式的日志，也可以使用命令行工具进行转换。例如用awk重新组合字段，或者使用vector、fluentd等采集器把原始日志解析后再输出为JSON。对于已经采用JSON格式的日志，直接使用jq过滤HTTP/2请求即可：

jq 'select(.http2 == "h2")' /var/log/nginx/access.json | head -n 20

该命令会输出所有通过HTTP/2协议访问的记录。结合request_uri和request_time字段，可以快速统计哪些页面在HTTP/2下响应更快，也可以对比推送资源前后的请求次数变化。

三、HTTP/2推送的常见误区与日志驱动的调优

HTTP/2推送最大的误区是无差别推送所有静态资源。对于一些已经缓存在浏览器中的资源，重复推送反而浪费带宽，甚至可能抢占关键资源的传输优先级。理想做法是根据请求头中的Cookie或ETag信息来决定是否推送，不过Nginx的http2_push指令本身不支持条件判断。常见的替代方案是使用map配合变量控制Link头，再结合http2_push_preload自动推送。例如只对首次访问的用户推送CSS：

map $http_cookie $push_css {
    default        "</assets/css/style.css>; as=style; rel=preload";
    "~*css_loaded=1" "";
}

server {
    listen 443 ssl http2;
    http2_push_preload on;

    location = /index.html {
        add_header Link $push_css;
    }
}

当浏览器带有css_loaded=1的Cookie时，$push_css变量为空，就不会添加Link头，Nginx也就不会推送style.css。这种方式比在location中硬编码http2_push更灵活，适合有用户状态管理的应用。需要注意的是，map必须放在http上下文中，不能直接写在server块内部。

日志中的request_time和status字段还能帮助发现推送是否真正减少了加载时间。如果推送的资源状态码正常，但页面整体request_time没有明显下降，可能是客户端不支持推送或者推送资源并不是关键渲染路径。此时可以结合$sent_http_link变量记录实际返回的Link头内容，验证Nginx是否正确生成预加载提示。虽然$sent_http_link不能直接证明推送成功，但至少可以确认后端添加了预加载声明。

另一个容易被忽略的是日志文件轮转后的格式变化。如果使用logrotate管理日志，建议在postrotate中发送USR1信号让Nginx重新打开日志文件，同时保证新的日志文件仍然使用相同的JSON格式。否则在轮转后可能会出现几行默认combined格式的日志，破坏数据一致性。相应的配置如下：

/var/log/nginx/access.json {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    sharedscripts
    postrotate
        if [ -f /var/run/nginx.pid ]; then
            kill -USR1 $(cat /var/run/nginx.pid)
        fi
    endscript
}

这段配置每天轮转一次，保留14天，并通知Nginx重新打开日志文件，确保后续日志继续写入新文件而不是被压缩文件占用。

四、完整的生产配置示例与验证步骤

将上述内容整合起来，可以得到一个较为完整的HTTP/2推送与日志转换配置。下面的示例展示了入口页面推送、JSON日志记录和缓冲区设置：

http {
    log_format json_http2 escape=json
        '{'
            '"remote_addr":"$remote_addr",'
            '"time_local":"$time_local",'
            '"request_method":"$request_method",'
            '"request_uri":"$request_uri",'
            '"status":$status,'
            '"protocol":"$server_protocol",'
            '"http2":"$http2",'
            '"body_bytes_sent":$body_bytes_sent,'
            '"request_time":$request_time'
        '}';

    access_log /var/log/nginx/access.json json_http2 buffer=64k flush=3s;

    map $http_cookie $push_css {
        default        "</assets/css/style.css>; as=style; rel=preload";
        "~*css_loaded=1" "";
    }

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

        ssl_certificate     /etc/nginx/ssl/ipipp.com.crt;
        ssl_certificate_key /etc/nginx/ssl/ipipp.com.key;

        root /var/www/html;

        location = /index.html {
            add_header Link $push_css;
            http2_push /assets/js/app.js;
        }

        location /assets/ {
            expires 7d;
            add_header Cache-Control "public";
        }
    }
}

保存配置后，先执行nginx -t检查语法，再通过systemctl reload nginx重载。验证HTTP/2是否生效可以使用curl命令：

curl -I --http2 https://ipipp.com/index.html

响应头中出现HTTP/2 200以及Link字段，说明服务端推送配置已经生效。接着查看JSON日志中对应的请求记录：

tail -n 5 /var/log/nginx/access.json | jq .

输出结果中http2字段应为h2，protocol字段为HTTP/2.0，request_uri为/index.html。如果使用jq统计推送资源请求数量，可以进一步分析推送命中的频率。经过上述配置，Nginx不仅能有效减少HTTP/2页面的资源加载时间，还能通过结构化日志为后续性能调优提供可靠的数据基础。

NginxHTTP/2 Server Push日志格式转换修改时间：2026-09-22 14:56:49