跳转至

zstd: NGINX 模块用于 Zstandard 压缩

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

  • RedHat Enterprise Linux 7、8、9 和 10
  • CentOS 7、8、9
  • AlmaLinux 8、9
  • Rocky Linux 8、9
  • Amazon Linux 2 和 Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-zstd

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-zstd

通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用模块：

load_module modules/ngx_http_zstd_filter_module.so;

load_module modules/ngx_http_zstd_static_module.so;

本文档描述了 nginx-module-zstd v0.2.1，发布于 2026 年 7 月 27 日。

## 指定字典
zstd_dict_file /path/to/dict;

server {
    listen 127.0.0.1:8080;
    server_name localhost;

    location / {
        # 启用 zstd 压缩
        zstd on;
        zstd_min_length 256; # 不少于 256 字节
        zstd_comp_level 3; # 设置级别为 3

        proxy_pass http://foo.com;
    }
}

server {
    listen 127.0.0.1:8081;
    server_name localhost;

    location / {
        zstd_static on;
        root html;
    }
}

指令

ngx_http_zstd_filter_module

ngx_http_zstd_filter_module 模块是一个过滤器，使用 "zstd" 方法压缩响应。这通常有助于将传输数据的大小减少一半或更多。

zstd_dict_file

语法: zstd_dict_file /path/to/dict;
默认值: -
上下文: http

指定外部字典。

警告: 请小心！内容编码注册仅指定了一种信号使用 zstd 格式的方法，并未额外指定任何机制来在客户端和服务器之间广告/协商/同步使用特定字典。仅在您能确保两端 (服务器和客户端) 能够使用相同字典的情况下使用 zstd_dict_file（例如，通过 HTTP 头进行广告）。有关详细信息，请参见 https://github.com/tokers/zstd-nginx-module/issues/2。

zstd

语法: zstd on | off;
默认值: zstd off;
上下文: http, server, location, if in location

启用或禁用响应的 zstd 压缩。

zstd_comp_level

语法: zstd_comp_level level;
默认值: zstd_comp_level 1;
上下文: http, server, location

设置响应的 zstd 压缩级别。可接受的值范围为 1 到 ZSTD_maxCLevel()。

zstd_min_length

语法: zstd_min_length length;
默认值: zstd_min_length 20;
上下文: http, server, location

设置将被 zstd 压缩的响应的最小长度。长度仅由 Content-Length 响应头字段确定。

zstd_types

语法: zstd_types mime-type ...;
默认值: zstd_types text/html application/wasm text/wgsl;
上下文: http, server, location

除了 text/html 外，还为指定的 MIME 类型启用响应的 zstd。特殊值 * 匹配任何 MIME 类型。

application/wasm 和 text/wgsl 默认情况下被压缩：这两者都是以非文本媒体类型提供的类文本格式，因此压缩效果良好，但容易被忽视。显式指定 zstd_types 会替换除 text/html 之外的默认值，后者始终包含在内。

zstd_buffers

语法: zstd_buffers number size;
默认值: zstd_buffers 32 4k | 16 8k;
上下文: http, server, location

设置用于压缩响应的缓冲区的数量和大小。默认情况下，缓冲区大小等于一个内存页面。这是 4K 或 8K，具体取决于平台。

ngx_http_zstd_static_module

ngx_http_zstd_static_module 模块允许发送以 .zst 文件扩展名的预压缩文件，而不是常规文件。

zstd_static

语法: zstd_static on | off | always;
默认值: zstd_static off;
上下文: http, server, location

启用（"on"）或禁用（"off"）检查预压缩文件的存在。以下指令也会被考虑：gzip_vary。

使用 "always" 值时，"zstd" 文件在所有情况下都被使用，而不检查客户端是否支持它。

当没有 .zst 文件存在时，请求将保持不变地被拒绝，因此 gzip_static 和 gzip 过滤器仍然会按常规方式应用。

变量

ngx_http_zstd_filter_module

$zstd_ratio

实现的压缩比，计算为原始响应大小与压缩响应大小之间的比率。

GitHub

您可以在 nginx-module-zstd 的 GitHub 仓库 中找到此模块的其他配置提示和文档。