NGINX `ngx_http_gzip_static_module` 零时延送出预压缩文件

一、模块定位与价值

• 功能：检查请求对应的静态文件（如 app.js）是否存在预先压缩的 app.js.gz，并在合适情况下直接返回该 .gz 文件。

• 收益：

  • 零 CPU：不做任何内嵌压缩运算，节省实时压缩带来的 CPU 消耗；
  • 低延迟：立即读取磁盘文件，无需缓冲与压缩延迟；
  • 带宽优势：同动态压缩策略一样，节省传输量；

• 适用场景：前端静态资源（JS/CSS/JSON），大文件下载，流量暴增峰值应对。

二、编译与启用

1. 安装
   在编译 NGINX 源码时加上：

   ./configure --with-http_gzip_static_module [其他模块…]
   make && sudo make install
   

2. 验证

   nginx -V 2>&1 | grep gzip_static
   # 应显示 --with-http_gzip_static_module
   

三、核心指令

gzip_static on | off | always

值	含义
off	（默认）不启用预压缩文件检查
on	仅当客户端支持 Gzip 时检查并返回 .gz 与 gzip 模块相关策略联动
always	无条件返回 .gz，即使客户端不声明支持 Gzip，也不检查源文件

联动指令：gzip_http_version、gzip_proxied、gzip_disable、gzip_vary 都会在 on 模式下一起生效。

四、配置示例

http {gzip_static on;                 # 开启预压缩文件检查gzip_vary    on;                # 标记 Vary: Accept-Encodinggzip_proxied no-cache;          # 代理请求时亦返回 .gzgzip_disable "msie6";           # 屏蔽老旧浏览器server {listen 80;server_name static.example.com;root /data/static;location /assets/ {# 对 /assets/*.js、*.css 等启用 .gz 优选gzip_static on;expires 30d;add_header Cache-Control "public";}}
}

• 客户端请求 GET /assets/app.js HTTP/1.1：

  • 若 app.js.gz 存在且客户端 Accept-Encoding: gzip → 返回 app.js.gz，响应头自动调整为 Content-Encoding: gzip；
  • 若客户端不支持或 gzip_static always 未设置 → 回退读取原始 app.js。

五、生成与同步 .gz 文件

# 在构建脚本中加入
find dist -type f -name '*.js' -o -name '*.css' | \xargs -I{} gzip -9 -c {} > {}.gz

• 压缩级别：建议 -9 保证最小体积；
• 保留时间戳：使用 -n 或后续文件同步工具，确保 .gz 与源文件同修改时间，方便缓存管理。

六、高级场景与注意事项

1. always 模式

   • 当磁盘上仅保留 .gz 而无原始文件时，或结合 ngx_http_gunzip_module 做反解压；
   • 适合读多写少、缓存预热机制：只存 .gz，必要时动态“解压”给不支持的客户端。

2. CDN 与多级缓存

   • 搭配 gzip_vary on，让 CDN 和浏览器都缓存编码差异版本；
   • 静态内容更新后，只需同步 .gz，无需通知 NGINX 重载。

3. 内容型别限定

   • gzip_static 没有 gzip_types 限定，会对所有请求尝试查找 .gz；
   • 合理组织 location 或配合 map，仅针对 JS/CSS/JSON 等文本文件启用。

4. 文件系统性能

   • 大量并发时，.gz 与源文件并存会带来额外 inode 与磁盘占用；
   • 在 SSD 或分层存储上效果最佳，HDD 下注意随机访问延迟。

5. 日志跟踪

   • 可通过 $sent_http_content_encoding 或自定义日志格式，监控 .gz 命中率。

   log_format static '$remote_addr "$request" ''encoding=$sent_http_content_encoding ';
   access_log /var/log/nginx/static.log static;
   

七、总结

ngx_http_gzip_static_module 是「极简零时延压缩」的王炸方案，适合将离线打包、构建压缩好的静态资源直接推给客户端。配合构建流程自动生成 .gz，再在 NGINX 中一行开启，便可：

1. 立即响应：无需实时压缩，CPU 零开销
2. 精准控制：支持条件返回与“无条件”模式
3. 完美兼容：与代理、旧浏览器和多级缓存无缝配合

在任何对性能与稳定性有苛刻要求的静态资源分发场景下，这个模块都能让你的 NGINX 更加轻盈、高效、可控。掌握它，你的前端发布与运维成本将降到最低。