Nginx中http2_push_diary_min_uses最小使用次数怎么设置？

HTTP/2 Server Push 的本质是让服务器在响应主文档时，通过 PUSH_PROMISE 帧提前告知客户端即将发送的关联资源。Nginx 通过 http2_push 指令实现主动推送，但光有推送列表还不够，服务器还要判断某个资源是否值得继续推送。如果客户端已经有缓存，或者资源从来没有被真正使用过，再推就是纯粹的带宽浪费。http2_push_diary_min_uses 这一参数正是用来设置资源在推送记录中被实际使用的最小次数阈值，达到这个次数后才允许后续继续推送。下面结合配置和验证过程说明它到底应该怎么设。

http2_push_diary_min_uses 的作用机制与适用场景

Nginx 的 http2_push 指令可以在 http、server 或 location 上下文使用，语法为 http2_push uri;。当客户端请求一个 HTML 页面时，Nginx 会按照配置把对应的 CSS、JavaScript、字体等资源一并推送到连接上。这个过程不等待浏览器解析 HTML 后再发起请求，因此能明显降低首屏时延。不过，http2_push_diary_min_uses 则属于扩展指令，它维护的是一个资源使用记录表，也常被称为推流日记。这个日记会记录每类资源在连接生命周期内被客户端真正消费的次数。只有当统计次数大于或等于该阈值时，资源才会在后续连接中被继续推送。

举例来说，如果某个 CSS 文件因为页面入口变化而不再被使用，它的使用次数会降为零。此时若把最小使用次数设置为 1，服务器就会停止推送该文件，从而避免无效推送。反过来，如果阈值设成 0，等于关闭判断，每次都会推送所有 http2_push 指定的资源。对于单页应用这类入口稳定的项目，阈值通常可以设为 2 或 3，让资源至少被真实消费几次后再固定推送；对于活动页面或短时落地页，则建议保持为 1，保证首访加载速度。

这个机制的核心价值不是让推送更多，而是让推送更准。HTTP/2 的连接可以承载大量并发流，但带宽和客户端内存始终有限。如果一次性推送了多个大体积的未使用资源，反而会阻塞关键请求。通过使用次数作为过滤条件，服务器能够根据历史消费情况动态收缩推送范围，在不改动业务代码的前提下实现一定程度的自适应优化。

在 Nginx 中配置最小使用次数的完整示例

首先需要确认 Nginx 已经启用 HTTP/2 模块，并且监听 listen 443 ssl http2;。如果使用的是包含 http2_push_diary_min_uses 指令的定制版本或第三方模块，可以直接在 location 中写入该参数。基础配置如下：

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;
    index index.html;

    location = /index.html {
        http2_push /assets/css/main.css;
        http2_push /assets/js/app.js;
        http2_push_diary_min_uses 2;
    }

    location /assets/ {
        expires 7d;
        add_header Cache-Control "public, max-age=604800";
    }
}

这段配置中，location = /index.html 精确匹配首页，只有请求首页时才会触发 http2_push。两个资源分别被指定为主动推送对象，http2_push_diary_min_uses 设置为 2，表示这些资源至少要被客户端实际使用两次后，才会在后续连接中继续自动推送。资源本身仍然通过 /assets/ 路径正常访问，缓存策略由 expires 和 Cache-Control 控制。

如果更希望由后端或应用层通过 HTTP 头决定推送哪些资源，可以开启 http2_push_preload on;，然后让上游返回 Link 响应头。这样 Nginx 会解析 preload 关系并执行推送，同时用最小使用次数进行过滤。示例配置如下：

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

这里把阈值提高到 3，适合已经稳定运行一段时间的应用。当资源使用次数低于 3 时，Nginx 不会继续推送，但资源仍可通过正常请求获取。需要注意的是，add_header 会直接在响应中下发 Link 头，浏览器收到后也可能发起预加载请求，因此要结合 Cache-Control 避免重复传输。

验证推送效果与阈值调优思路

配置完成后不能只看 Nginx 日志，还要从客户端视角确认推送是否真正生效。可以使用 curl 命令检查响应头中的 Link 和 HTTP/2 连接信息：

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

浏览器开发者工具中，打开 Network 面板可以看到资源的 Initiator 列为 Push，表明它来自服务器主动推送而不是普通请求。抓包工具则可以更清晰地看到 PUSH_PROMISE 帧。如果发现大量推送资源没有被页面使用，就应提高 http2_push_diary_min_uses 的值；如果首屏关键资源没有被推送，则要降低阈值或检查 http2_push 路径是否正确。

阈值调优没有绝对的标准值，它和页面结构、资源体积、缓存策略以及用户访问路径都有关。一般经验是：核心 CSS 和入口 JS 可以保持较低阈值，比如 1 到 2；体积较大的图片、字体或首屏之外的组件则建议设置为 2 到 3，甚至不启用推送。对于返回 304 的缓存命中场景，服务器应跳过推送，但在 HTTP/2 协议中，服务器只能根据自身的 diary 信息估算客户端缓存状态，因此最小使用次数是其中一个重要的判断依据。

最后还需要关注连接复用带来的影响。HTTP/2 的长连接会持续较长时间，diary 中的使用次数也会随着连接不断累积。如果 Nginx 重启或连接断开，这些记录是否持久化取决于模块实现。对于多实例部署，建议将推流记录保存到共享存储或用统一的推送策略代替。这样才能保证不同后端节点对同一资源的推送判断一致，避免出现用户在某个节点上反复收到无效推送的问题。

Nginx HTTP/2 Server Pushhttp2_push最小使用次数修改时间：2026-10-04 18:08:23