open_file_cache_valid 必须与 open_file_cache、open_file_cache_min_uses、open_file_cache_errors 等参数协同配置于 http 块中才生效,用于控制 Nginx 每隔指定时间对缓存文件元数据执行 stat() 检查的频率,以判断缓存有效性。

open_file_cache_valid 不是独立生效的指令,它必须嵌入完整的 open_file_cache 机制中才能发挥作用。它的作用很明确:控制 Nginx 主动对已缓存文件元数据(存在性、权限、修改时间)执行 stat() 检查的频率,从而判断缓存条目是否依然有效。
要让它真正“定期检查缓存文件有效性”,需满足三个前提:配置完整、参数协同、位置正确。
open_file_cache_valid 必须配合其他四参数一起用
只写 open_file_cache_valid 60s; 是无效的。它必须和以下四项共存于 http { ... } 块内:
open_file_cache max=10000 inactive=60s;
设置缓存容量上限与“不活跃”淘汰窗口(不是校验周期,而是条目存活时限)open_file_cache_valid 60s;
每隔 60 秒,Nginx 会随机抽查部分缓存条目,调用stat()验证其对应文件是否仍存在、是否被修改或权限变更open_file_cache_min_uses 2;
同一文件在inactive时间窗内至少被访问 2 次才进入缓存,避免低频路径污染open_file_cache_errors on;
把404、403等错误结果也缓存起来,并同样受inactive和valid管理,防止反复探测无效路径
校验行为的实际逻辑
- Nginx 不监听文件变化,而是被动轮询:每过
valid秒,它从缓存中选取一部分条目做stat() - 若发现文件已被删除、重命名、权限变更或 mtime/inode 变化,该条目被标记为“过期”
- 下次请求命中该路径时,Nginx 才会重新
open()+stat(),刷新缓存 - 如果
valid设得太长(比如 3600s),而文件在中间被删了,Nginx 会继续返回旧缓存结果,直到下一次校验——这就是变更感知延迟
推荐值与场景匹配
- 静态资源带哈希指纹(如
app.a1b2c3.js)且极少回滚:open_file_cache_valid 3600s安全 - 生产环境无自动发布,资源月更:
300s–1800s平衡性能与一致性 - CI/CD 每小时部署新静态包:
60s–120s,避免缓存 stale 文件导致样式错乱或 404 - 开发环境或热更新频繁:
10s–30s,但需注意valid过短会增加stat()系统调用压力
注意 reload 不重置缓存
修改 open_file_cache_valid 后执行 nginx -s reload,老 worker 进程仍按旧值校验,新 worker 才用新值。这意味着变更不会立即生效,真实生效需重启或等待旧进程自然退出。
不复杂但容易忽略


















