Nginx中http2_push_diary_ttl_days参数是什么意思？如何配置HTTP/2推送缓存有效期？

HTTP/2带来的多路复用、头部压缩等特性大家已经比较熟悉了，但其中一项叫Server Push的能力在实践中的讨论度一直不低。Nginx从1.13.9版本开始正式支持HTTP/2服务器推送，配套的还有一系列控制指令，其中http2_push_diary_ttl_days这个参数经常被问到：它到底管什么、该怎么设、设大了设小了分别有什么影响。这篇文章就把推送日记机制和这个TTL参数一次讲透。

一、先搞懂HTTP/2推送和推送日记是怎么回事

传统的HTTP交互模式是严格的一问一答：浏览器请求一个HTML页面，解析之后发现里面引用了CSS、JS、图片，再逐个发起请求。HTTP/2的Server Push打破了这个节奏，服务端可以在响应HTML的同时，主动通过PUSH_PROMISE帧告诉客户端：你接下来肯定要用这几个资源，我直接给你发过去了。对于关键的CSS文件来说，这能省掉一次完整的请求往返，在首屏优化上理论收益不小。

但推送有个天然的坑：如果浏览器已经缓存了某个资源，服务端还一个劲地推，就是纯粹的带宽浪费，甚至可能比不推送还慢。为此HTTP/2设计了推送日记这个机制。客户端会维护一份已接收推送资源的记录表，通过请求头里的digest字段告知服务端；服务端对照这份日记，跳过已经推送过的资源。而日记不可能无限期保存，总得有个过期时间，这就是TTL的由来。

Nginx侧对应的控制指令就是http2_push_diary_ttl_days，单位是天，默认值是1天。它的含义很直白：客户端本地保存的推送日记条目在多少天后失效。超过这个天数，客户端会把记录清掉，下次请求时不再声明这些资源已推送过，服务端也就可以重新推送了。

二、http2_push_diary_ttl_days的配置方法与示例

这个指令可以配置在http、server、location三个层级，作用范围遵循Nginx一贯的继承规则。先看一个基础配置示例，把推送和日记TTL一起配好：

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

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

    # 推送日记有效期设为3天
    http2_push_diary_ttl_days 3;

    location / {
        root /data/www;
        index index.html;
        # 主动推送页面依赖的关键CSS
        http2_push /css/main.css;
    }

    location ~* \.(css|js)$ {
        # 静态资源本身也可以按需推送
        http2_push_preload on;
        expires 7d;
    }
}

配置里有几个细节值得展开。http2_push指定要推送的资源路径，路径必须是同源的URI；http2_push_preload设为on时，Nginx会自动读取响应头中的Link字段，把带preload标记的资源转成推送。两种方式可以结合使用，后者在动态页面中更灵活，应用层只需要输出标准的Link响应头，不用侵入Nginx配置。

至于TTL的取值，建议和静态资源的缓存策略对齐。假设你的CSS文件设置了expires 7d，但推送日记只保留1天，那么第二三天浏览器虽然还缓存着资源，日记条目却已经过期，服务端无法通过digest感知，就可能重复推送。反过来，如果TTL设得很长而资源缓存时间很短，日记里记录的资源在客户端早已失效，服务端却不推送，页面就要走正常请求路径。两者错位都会造成浪费，所以让http2_push_diary_ttl_days的值略大于等于资源缓存时长是比较稳妥的做法。

三、实践中的注意事项与现状反思

第一点要注意的是，推送日记的匹配依赖客户端支持。只有客户端在请求头中带上digest信息，服务端的去重逻辑才有意义。不同浏览器、不同版本的实现程度并不一致，所以不能想当然地认为配了这个参数就万事大吉，最好通过抓包或浏览器开发者工具的Network面板确认PUSH_PROMISE的实际行为。

第二点是作用域陷阱。http2_push_diary_ttl_days写在location级别时，只对该location的响应生效，而推送行为和日记判断发生在整个连接维度上。如果你在多个location里设置了不同的TTL值，实际效果可能和预期有出入，建议统一放在server层级，减少排查成本。

更重要的现实是，Chrome等主流浏览器从2022年前后陆续移除了对HTTP/2 Server Push的支持，原因是实测收益有限、复杂度高，且经常出现重复推送浪费带宽的情况。行业的主流做法已经转向103 Early Hints和预加载提示。如果你在维护存量系统，把日记TTL配置正确仍有价值；如果是新项目，更推荐用Link响应头做preload，并关注Nginx对Early Hints的支持进展，把精力放在确定收益更高的优化手段上。

Nginxhttp2_pushServer Push修改时间：2026-09-07 20:06:37