HTTP/2服务器推送是Nginx较早引入的一项特性，它允许服务端在客户端尚未发起请求时，主动把页面依赖的资源推送下去，从而减少往返延迟。但推送机制有一个容易被忽视的问题：服务端如何知道某个资源已经推送过了？如果服务端不记得，客户端就会反复收到同一个JS文件或样式表，反而浪费带宽。为了解决这个问题，Nginx内部维护了一个推送日记（push diary），而http2_push_diary_update这条指令，就是控制日记更新条目数量的开关。下面我们从原理、配置和实践三个层面来详细分析。
一、推送日记的工作原理与重复推送的根源
HTTP/2协议本身并没有提供服务端记忆推送状态的机制，客户端可以通过SETTINGS帧中的PUSH_MAX_STREAMS限制推送数量，但服务端是否重复推送某个资源，完全由服务端自己决定。Nginx的做法是在每个HTTP/2连接上维护一个推送日记，本质上是一个记录已推送资源路径的哈希表。每当服务端准备推送一个资源时，先在日记里查一下，如果这个路径已经推送过，就跳过；如果没有，才执行推送并把路径写进日记。
这个日记的容量是有限的。Nginx默认会记录最多64个条目，超出之后新的条目会覆盖旧的条目，类似LRU淘汰的策略。这就带来一个典型的现象：如果一个页面依赖的资源数量超过日记容量，排在最前面的记录会被挤出去，客户端再次请求该资源时，Nginx会认为它没被推送过，于是又推了一遍。用户端的表现就是浏览器开发工具里看到重复的PUSH_PROMISE。
需要特别注意的是，推送日记是基于连接的，而不是基于会话或用户。也就是说，客户端断开连接后重连，日记就清空了。对于HTTP/2长连接场景，日记可以有效避免重复推送；但对于频繁建立连接的客户端，日记的作用会大打折扣。这也是为什么后来Chrome等浏览器逐步放弃了对HTTP/2推送的支持，社区更倾向于使用103 Early Hints这类替代方案。不过在Nginx仍然大量部署的存量环境中，理解并调优日记行为依然有实际价值。
二、http2_push_diary_update指令的配置方法
http2_push_diary_update的作用是指定推送日记的更新条目数量，也就是一次性写入日记的容量大小。它的语法很简单，接受一个数字参数，可以配置在http、server、location三个层级：
http {
# 开启HTTP/2协议（新版本写法，旧版本为listen 443 ssl http2）
listen 443 ssl;
http2 on;
server {
server_name example.ipipp.com;
# 推送日记更新条目数，默认64
http2_push_diary_update 128;
# 开启预加载响应头触发推送
http2_push_preload on;
location / {
root /data/www;
add_header Link "</style.css>; as=style; rel=preload";
}
}
}
这条指令的默认值是64，取值范围为1到128。如果页面依赖的资源数量不多，比如只有十几个CSS和JS文件，默认的64已经完全够用，无需调整。但如果你的站点是资源密集型的，比如首屏就要加载几十个图片、字体、脚本，可以把数值调到128来扩大日记容量，减少条目被过早淘汰的概率。
还有一点值得说明：Nginx官方后来对这个指令做过调整。在较新的版本中，推送日记的匹配采用了一种概率性的布隆过滤思路，Nginx会根据配置的条目数计算过滤器的大小，128条对应256字节。这种设计的好处是内存开销极小，代价是存在极低的误判概率，可能偶尔漏推或重复推，但实际影响可以忽略。配置时不必纠结精确数值，按资源规模选择64或128即可。
除了http2_push_diary_update之外，与之配套的还有http2_push_max_concurrent_pushes（并发推送流数量）、http2_push（直接指定推送资源路径）等指令。建议把它们放在同一个server块里统一管理，避免不同location层级配置混乱导致行为不一致。
三、配置实践中的注意事项与调优建议
第一个常见误区是盲目调大日记容量。有些运维同学发现重复推送就把http2_push_diary_update直接拉满，但日记容量只是缓存条目数，它并不能解决连接重置带来的日记清空问题。如果你的访问日志显示大量短连接，正确的方向是排查keepalive_timeout是否设置过短，或者中间是否有代理设备主动断开HTTP/2连接。把长连接超时设置到合理范围（比如65秒以上），日记的价值才能体现出来。
第二个注意点是推送资源的粒度控制。日记是按资源的路径做匹配的，带查询参数的URL会被视为不同条目。假如你的静态资源引用形如/app.js?v=123，每次版本号变化都会生成新条目，旧条目占用日记空间直到被淘汰。因此更推荐对静态资源采用独立的版本目录或文件名哈希策略，让日记中的路径保持稳定。
第三个建议是结合缓存头来配合推送。Nginx推送资源时会遵循Cache-Control的相关语义，如果推送的资源没有被正确缓存，客户端下次仍然要请求它，日记里的记录也就失去了意义。一个健康的推送策略应该保证：推送的资源带有较长的强缓存头，客户端本地命中缓存后不会再发起请求，日记则负责在缓存失效前的连接生命周期内兜底去重。
最后提醒一点，修改配置后记得用nginx -t验证语法再执行nginx -s reload，并通过浏览器开发者工具的协议面板或curl --http2 -v观察PUSH_PROMISE帧是否出现重复。如果你希望验证日记是否生效，可以构造一个超过日记容量的资源列表页面，依次访问这些资源后再回头请求第一个资源，观察它是否被重新推送，从而判断当前容量设置是否满足站点需求。
四、总结
http2_push_diary_update是一条不起眼但直接影响推送去重效果的指令。它的核心逻辑是在每个HTTP/2连接上维护一个有限容量的推送记录表，默认64条，可调整到最多128条。配置时的关键不在于机械地调大数值，而在于理解它基于连接的生命周期特性，并配合长连接、稳定的资源路径和合理的缓存策略一起使用。只有把这些环节打通，HTTP/2服务器推送才能真正减少重复传输，而不是制造额外的带宽浪费。如果你的站点资源规模持续增长，也别忘了关注Nginx版本更新中对推送模块的调整，必要时可以考虑用Early Hints等更现代的机制替代推送方案。
http2_push_diary_updateNginxHTTP/2服务器推送修改时间：2026-09-08 20:47:09