Zstandard（zstd）压缩

本文将详细介绍如何在 OpenResty Edge 中配置和使用 Zstandard（zstd）压缩功能。

# 配置层级概述

OpenResty Edge 提供了多个层级的 zstd 压缩配置选项，按照优先级从高到低排列如下：

1. 页面规则配置：应用 > HTTP 应用 > 具体应用 > 页面规则 > 动作 > 启用网关 Zstandard/设置 Zstandard 类型
2. 全局自定义动作配置（被 HTTP 应用引用）：全局配置 > 全局自定义动作 > 动作 > 启用网关 Zstandard/设置 Zstandard 类型
3. 应用设置配置：应用 > HTTP 应用 > 具体应用 > 设置 > Zstandard
4. 全局改写规则配置：全局配置 > 全局改写规则 > 动作 > 启用网关 Zstandard/设置 Zstandard 类型
5. 全局通用配置：全局配置 > 通用配置 > Zstandard 配置（默认启用）

注意：当多个层级同时配置时，高优先级的配置会覆盖低优先级的配置。

# 全局通用配置

全局通用配置是 zstd 压缩的基础配置，为整个系统提供默认的压缩参数。

# 配置参数说明

# 默认压缩类型

系统默认对以下 MIME 类型启用 zstd 压缩：

text/plain text/css text/xml text/javascript text/cache-manifest
text/vtt text/x-component application/javascript application/json
application/ld+json application/xml application/xhtml+xml
application/rss+xml application/atom+xml application/manifest+json
application/x-web-app-manifest+json application/vnd.geo+json
application/vnd.ms-fontobject application/x-font-ttf application/wasm
font/opentype image/svg+xml image/bmp

提示：text/html 类型默认包含在压缩范围内，无需在此处重复配置。

# 全局改写规则配置

通过全局改写规则可以为特定条件的请求配置 zstd 压缩。

# 可用动作

• 启用网关 Zstandard：动态启用或禁用 Zstandard 压缩
• 设置 Zstandard 压缩类型：自定义需要压缩的 MIME 类型

注意：此处设置的压缩类型默认不包含 text/html，如需压缩 HTML 内容，请手动添加。

# 全局自定义动作配置

自定义动作提供了可复用的 zstd 压缩配置，可在多个应用中引用。

配置方式与全局改写规则相同，但具有更高的优先级。

# 应用级别配置

在应用设置中可以为特定应用配置 zstd 压缩策略。

# 配置选项

• 跟随全局：使用全局通用配置中的设置
• 启用：为当前应用启用 zstd 压缩
• 禁用：为当前应用禁用 zstd 压缩

# 页面规则配置

页面规则提供最精细的 zstd 压缩控制，可以针对特定的 URL 路径或条件进行配置。

配置方式与全局改写规则相同，但具有最高的优先级。

# 实际应用示例

以下示例展示了 zstd 压缩的实际效果。

# 测试场景

示例中配置了一条简单的页面规则，直接响应 “Hello World” 文本。由于全局通用配置默认启用了 zstd 压缩，因此无需额外配置。

# 压缩效果测试

启用 zstd 压缩的请求：

$ curl test.com/enable --resolve test.com:80:127.0.0.1 -H 'Accept-Encoding: zstd' -v
*   Trying 127.0.0.1:80...
* Connected to test.com (127.0.0.1) port 80 (#0)
> GET /enable HTTP/1.1
> Host: test.com
> User-Agent: curl/7.76.1
> Accept: */*
> Accept-Encoding: zstd
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Content-Type: text/html
< Transfer-Encoding: chunked
< Connection: keep-alive
< Req-ID: 0000008000046f7f9e280008
< Content-Encoding: zstd
<
Warning: Binary output can mess up your terminal. Use "--output -" to tell
Warning: curl to output it to your terminal anyway, or consider "--output
Warning: <FILE>" to save to a file.

响应头中包含 Content-Encoding: zstd，确认压缩已生效。

未启用 zstd 压缩的请求：

$ curl test.com/enable --resolve test.com:80:127.0.0.1 -v
*   Trying 127.0.0.1:80...
* Connected to test.com (127.0.0.1) port 80 (#0)
> GET /enable HTTP/1.1
> Host: test.com
> User-Agent: curl/7.76.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Fri, 30 May 2025 08:42:51 GMT
< Content-Type: text/html
< Transfer-Encoding: chunked
< Connection: keep-alive
< Req-ID: 0000008000046f7fac58000b
<
Hello World

未包含 Accept-Encoding: zstd 请求头时，服务器返回未压缩的原始内容。

# 更多说明

当同时启用 Gzip、Brotli、zstd 压缩时，优先级是 zstd > Brotli > Gzip。