在 Nginx 的 HTTP/2 配置资料中，偶尔会出现 http2_push_diary_enable 这样的参数拼写，但翻遍官方 http_v2_module 文档也找不到它的位置。这个名称更像是把 http2_push 和 push diary（推送日志）两个概念强行拼接到一起的产物。Nginx 从 1.13.9 版本开始稳定支持 HTTP/2 Server Push，真正可用的指令只有 http2_push 和 http2_push_preload，并不存在一个名为 http2_push_diary_enable 的开关。如果你在配置文件里写上 http2_push_diary_enable on;，Nginx 会直接报 unknown directive 错误，因为解析器根本不认识它。
一、http2_push_diary_enable 为什么搜不到官方说明
先说结论：Nginx 的 HTTP/2 模块没有提供任何带 diary 字样的指令。可能被混淆的来源有两个。一是有人把 http2_push 记成了更长的拼写，再加上 diary 表示希望记录推送日志。二是某些第三方模块或旧版本补丁里出现过类似参数，但主流官方主线并不包含。实际上 Nginx 中与 HTTP/2 推送相关的指令只有 http2_push、http2_push_preload、http2_max_concurrent_pushes 等几个，它们都归属于 http_v2_module，通过 nginx -V 可以检查模块是否编译进去。
理解这一点之后，我们真正要处理的问题就变成了：如何正确启用 HTTP/2 Server Push，以及怎样查看推送是否生效。HTTP/2 Server Push 的机制是客户端请求一个主文档时，服务器可以在主文档响应之前或同时，主动把关键的 CSS、JavaScript、字体等资源推送到客户端缓存中。这样浏览器解析 HTML 时发现需要这些资源，就能直接从缓存读取，省去再次发起请求的往返时间。这个能力依赖 HTTP/2 的多路复用特性，多个推送流可以和主响应并行传输，不会像 HTTP/1.1 那样排队阻塞。
二、启用 HTTP/2 推送的两种正确方式
前置条件很明确：Nginx 必须启用 HTTPS，并且监听端口使用 http2 参数。示例配置为 listen 443 ssl http2;，同时要正确配置 TLS 证书。没有 TLS，浏览器不会启用 HTTP/2，推送自然无从谈起。可以使用 nginx -V 查看编译参数中是否包含 --with-http_v2_module，大多数发行版预编译包已经包含该模块。
第一种方式是在 location 或 http、server 块中使用 http2_push 指令，静态声明需要推送的资源路径。比如你希望访问首页时同时推送 style.css 和 main.js，可以这样写：
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;
location / {
http2_push /assets/style.css;
http2_push /assets/main.js;
}
}
这种方式的优点是配置直观，适合资源路径固定、页面结构相对简单的站点。但缺点也很明显：只要请求匹配该 location，服务器就会无条件推送这些资源，即使浏览器已经缓存过，或者当前页面其实并不需要这些文件。这会造成带宽浪费，尤其在移动网络下体验反而变差。
第二种方式更灵活，使用 http2_push_preload on; 配合响应头中的 Link 字段。具体做法是让 Nginx 读取源站或上游应用返回的 Link 响应头，当看到带有 rel=preload 的链接时，自动触发服务端推送。配置如下：
server {
listen 443 ssl http2;
server_name ipipp.com;
root /var/www/html;
location = /index.html {
add_header Link "</assets/style.css>; rel=preload; as=style";
add_header Link "</assets/main.js>; rel=preload; as=script";
http2_push_preload on;
}
}
这里 http2_push_preload on; 就是很多人容易忽略的开关。如果没有它，Link 头只会被浏览器用来做预加载，不会触发服务器推送。加上之后，Nginx 会解析 Link 头中的资源路径，并主动推送这些文件。应用层（如 PHP、Node.js、Java）可以根据用户登录状态、A/B 测试或资源版本动态输出不同的 Link 头，比静态 http2_push 更可控。
三、验证推送是否真正生效
配置完成之后不能只凭感觉判断，需要实际验证。浏览器开发者工具的 Network 面板是最直观的工具。刷新页面后查看资源的 Protocol 列，确认显示为 h2；再查看 Initiator 列，如果资源是由服务器推送而来，通常会显示 Push 或 Other 字样，而不是具体的脚本行号。还可以在 Timing 视图里看到该资源的请求开始时间早于 HTML 解析之后发起的普通请求。
命令行下可以使用 nghttp2 工具查看 PUSH_PROMISE 帧，示例命令如下：
nghttp -nv https://ipipp.com/index.html 2>&1 | grep PUSH_PROMISE
如果能看到若干 PUSH_PROMISE 帧，说明服务器确实执行了推送。如果没有任何输出，就要逐项排查：监听端口是否包含 http2；证书是否有效；Nginx 版本是否过旧；http2_push_preload 是否放在了正确的 location 块中；以及 add_header 是否被内层 location 覆盖。尤其要注意 add_header 的继承规则，location 中一旦出现自己的 add_header，外层的 Link 头不会自动继承，这是配置阶段最常见的坑。
四、避免推送过度与缓存一致性
服务器推送并非越多越好。推送的资源会占用 HTTP/2 流，如果推送了当前页面不需要的文件，不仅浪费带宽，还可能挤占主文档的传输优先级。针对这种情况，Nginx 提供了 http2_max_concurrent_pushes 指令来限制并发推送数量，例如 http2_max_concurrent_pushes 10; 可以防止单个连接上推送过多。对于静态配置的 http2_push，建议只推送首屏关键资源，并配合合理的 Cache-Control 头，让浏览器缓存后减少重复推送的压力。
另一个容易忽视的问题是缓存一致性。服务器推送发生在主文档响应阶段，如果资源已经更新而推送的仍是旧内容，可能导致页面加载错误。使用 http2_push_preload 配合应用生成的 Link 头时，建议在 Link 头中带上资源版本号或哈希，例如 style.css?v=123，这样既能利用缓存，又能避免推送过时资源。回到开头的 http2_push_diary_enable，它并不能打开任何推送日志记录功能，真正的推送排查还是要依赖 Nginx 的 error.log、access.log 以及浏览器网络面板。把名字记对，把开关放对位置，才是 HTTP/2 推送顺利生效的关键。
Nginx HTTP/2推送http2_push_preload服务器推送修改时间：2026-09-29 15:07:51