small-light: NGINX 动态图像转换模块
安装
您可以在任何基于 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-small-light
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-small-light
通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用模块：
load_module modules/ngx_http_small_light_module.so;
本文档描述了 nginx-module-small-light v0.9.4，于 2020 年 5 月 27 日发布。
这是一个用于 nginx 的动态图像转换模块。
入门
将以下配置添加到 nginx.conf 的某个服务器上下文中，然后启动 nginx。
small_light on;
location ~ small_light[^/]*/(.+)$ {
set $file $1;
rewrite ^ /$file;
}
如果您可以从以下 URL 获取原始图像 image.jpg，
http://$host:$port/img/image.jpg
您将能够从以下 URL 获取转换后的 image.jpg 图像。
http://$host:$port/small_light(dw=300,dh=300)/img/image.jpg
small_light(...) 部分称为 small_light 函数。
配置示例
以下是一些配置示例。
server {
listen 8000;
server_name localhost;
small_light on;
small_light_pattern_define msize dw=500,dh=500,da=l,q=95,e=imagemagick,jpeghint=y;
small_light_pattern_define ssize dw=120,dh=120,da=l,q=95,e=imlib2,jpeghint=y;
# http://localhost:8000/small_light(p=msize)/img/filename.jpg -> 生成 msize 图像
# http://localhost:8000/small_light(p=ssize)/img/filename.jpg -> 生成 ssize 图像
# http://localhost:8000/small_light(of=gif,q=100)/img/filename.jpg -> 生成质量为 100 的 gif 图像
location ~ small_light[^/]*/(.+)$ {
set $file $1;
rewrite ^ /$file;
}
}
指令
small_light
| 语法 | small_light on | off |
|---|---|
| 默认 | off |
| 上下文 | server, location |
此指令设置在服务器上下文中是否启用 ngx_small_light 的图像处理。
small_light_getparam_mode
| 语法 | small_light_getparam_mode on | off |
|---|---|
| 默认 | off |
| 上下文 | server, location |
此指令设置是否通过 GET 参数启用图像转换，而不是使用 small_light 函数（例如 /small_light(dw=200,dh=200)）。启用此功能的代价是 small_light 函数 被禁用。但您需要将 small_light 和 small_light_getparam_mode 都设置为 on 才能启用此指令的功能。
small_light_material_dir
| 语法 | small_light_material_dir path |
|---|---|
| 默认 | |
| 上下文 | server |
此指令分配嵌入图标图像的目录。
small_light_pattern_define
| 语法 | small_light_pattern_define pattern_name parameters |
|---|---|
| 默认 | |
| 上下文 | server |
此指令命名以逗号分隔的参数。
small_light_radius_max
| 语法 | small_light_radius_max number |
|---|---|
| 默认 | 10 |
| 上下文 | server,location |
此指令设置 sharpen、unsharp 和 blur 的几何最大半径值。
small_light_sigma_max
| 语法 | small_light_sigma_max number |
|---|---|
| 默认 | 10 |
| 上下文 | server,location |
此指令设置 sharpen、unsharp 和 blur 的几何最大 sigma 值。
small_light_imlib2_temp_dir
| 语法 | small_light_imlib2_temp_dir path [level1 [level2 [level 3 ]]] |
|---|---|
| 默认 | small_light_imlib2_temp 1 2 |
| 上下文 | server |
此指令分配用于 Imlib2 处理的临时文件目录。此指令在启用 Imlib2 时可用。
small_light_buffer
| 语法 | small_light_buffer size |
|---|---|
| 默认 | 1m |
| 上下文 | server |
此指令分配用于读取图像的最大缓冲区大小，当响应头中未设置 Content-Length 时。
small_light 函数的参数
| 参数 | 类型 | 默认 | 描述 | ImageMagick | Imlib2 | GD |
|---|---|---|---|---|---|---|
| p | string | 以逗号分隔的参数的命名模式 |  |
|
|
|
| e | string | imagemagick | 引擎名称（imagemagick, imlib2, gd） | |||
| q | number | 质量 | |
|
|
|
| of | string | 输出格式（jpg, gif, png, webp） | |
|
|
|
| jpeghint | char | n | 启用 jpeg 提示（y, n） | |
|
 |
| dw | coord | sw | 目标宽度 | |
|
|
| dh | coord | sh | 目标高度 | |
|
|
| dx | coord | sx | 目标 x 坐标 | |
|
|
| dy | coord | sy | 目标 y 坐标 | |
|
|
| da | char | l | 目标纵横比控制（l, s, n） | |
|
|
| ds | char | n | 目标缩放控制（s, n） | |
|
|
| cw | number | 画布宽度 | |
|
|
|
| ch | number | 画布高度 | |
|
|
|
| cc | color | 000000 | 画布颜色 | |
|
|
| bw | number | 边框宽度 | |
|
|
|
| bh | number | 边框高度 | |
|
|
|
| bc | color | 000000 | 边框颜色 | |
|
|
| sw | coord | 源宽度 | |
|
|
|
| sh | coord | 源高度 | |
|
|
|
| sx | coord | 源 x 坐标 | |
|
|
|
| sy | coord | 源 y 坐标 | |
|
|
|
| pt | char | n | 直通控制（y, n） | |
|
|
| sharpen | string | 半径，sigma（例如 10x5） | |
|
|
|
| unsharp | string | 半径，sigma，数量，阈值（例如 2x5+0.5+0） | |
|
|
|
| blur | string | 半径，sigma（例如 5x10） | |
|
|
|
| embedicon | string | 在 small_light_material_dir 中嵌入的图标文件 |
|
|
|
|
| ix | number | 0 | 嵌入图标 x 坐标 | |
|
|
| iy | number | 0 | 嵌入图标 y 坐标 | |
|
|
| angle | number | 0 | 旋转角度（90, 180, 270） | |
|
|
| progressive | char | n | 使 JPEG 逐步显示（y, n） | |
|
|
| cmyk2rgb | char | n | 将颜色空间从 CMYK 转换为 sRGB（y, n） | |
|
|
| rmprof | char | n | 移除配置文件（y, n） | |
|
|
| autoorient | char | n | 启用自动调整图像方向（y, n） | |
|
|
da 的值为 l、s 和 n，它们的含义如下。
l: 基于长边s: 基于短边n: 不适用
以下是一些限制。
- 当
e=imlib2时，不支持of=gif和of=webp。 autoorient在 ImageMagick-6.9.0 或更高版本中可用。sharpen、unsharp和blur的radius,sigma值受small_light_radius_max和small_light_sigma_max的限制。
以下是每个参数的类型。
| 类型 | 描述 |
|---|---|
| coord | 坐标或像素。当附加 'p' 时为百分比 |
| char | 字符 |
| number | 整数 |
| color | rrggbb 或 rrggbbaa |
| string | string |
使用 GET 参数
ngx_small_light 支持通过 GET 参数转换图像，不仅仅是通过 small_light 函数，从 v0.5.0 开始。您需要将 small_light 和 small_light_getparam_mode 都设置为 on 才能启用此功能。启用此功能的代价是 small_light 函数（例如 /small_light(dw=300,dh=300)/img.jpg）被禁用。
small_light on;
small_light_getparam_mode on;
在上述配置中，以下 URL 不返回转换后的图像。
http://localhost:8000/small_light(dw=200,dh=200)/img/image.jpg
相反，以下 URL 返回预期的转换图像。
http://localhost:8000/img/image.jpg?dw=200&dh=200
启用 WebP 转换
ngx_small_light 支持使用 ImageMagick 和 GD 进行 WebP 转换。将 of=webp 传递给 small_light 函数，ngx_small_light 将图像格式转换为 WebP。但是，ImageMagick 需要 libwebp，GD 需要 libvpx。您需要在构建 ImageMagick 和 GD 时嵌入这些库，以启用 WebP 转换。
如果 WebP 转换不可用，nginx 在处理带有 of=webp 的图像时会在 error.log 中输出如下行。
WebP is not supported
如果 ImageMagick 的 WebP 转换可用，convert -list format 的输出将包含如下行。
$ convert -list format | grep -i webp
WEBP* WEBP rw- WebP Image Format (libwebp 0.5.0[0208])
如果 GD 的 WebP 转换可用，gdlib-config --libs 的输出将包含 -lvpx。
通常，来自 Linux 发行版（如 Ubuntu 和 CentOS）的 ImageMagick 和 GD 软件包默认不嵌入 WebP 转换库。在这种情况下，您需要自己构建 ImageMagick 或 GD。
优化提示
以下是一些针对 ngx_small_light 的优化提示。
JPEG 提示
当输出格式为 JPEG 且图像转换引擎为 ImageMagick 或 Imlib2 时，您可以设置 jpeghint=y。图像处理的速度会显著提高。
限制 OpenMP 的线程数
当图像转换引擎为 ImageMagick 且 ngx_small_light 的版本低于 v0.6.14 时，强烈建议将 OMP_NUM_THREADS 或 MAGICK_THREAD_LIMIT 设置为 1。在多进程环境中，默认启用 OpenMP 的 ImageMagick 性能非常慢。
env OMP_NUM_THREADS=1; # 或 env MAGICK_THREAD_LIMIT=1;
或者，您可以通过使用 --disable-openmp 构建 ImageMagick 来避免此问题。
在 v0.6.14 或更高版本中，这些不再需要。因为 ngx_small_light 始终将 OpenMP 的线程数设置为 1。
限制
ngx_small_light 具有以下限制。
Imlib2 不支持的特性
使用 Imlib2 进行转换不支持写入 GIF 图像。因为 Imlib2 有加载 GIF 图像的功能，但没有保存的功能。此外，使用 Imlib2 的转换不支持写入和读取 WebP 图像。因此，不能同时指定 of=gif 和 e=imlib2。如果同时指定，ngx_small_light 将返回 415（不支持的媒体类型）。
GD 不支持的特性
使用 GD 进行转换支持写入 WebP 图像。但这是实验性功能。
不支持动画 GIF
ngx_small_light 不支持保持动画的动画 GIF 转换。因为转换（例如调整大小、裁剪）保持动画的动画 GIF 需要很长时间。因此，ngx_small_light 支持动画 GIF 并不现实。
如果提供动画 GIF，ngx_small_light 仅转换第一帧。
运行测试
perl Build.PL
cpanm --installdeps .
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx ./Build test
## 或
NGINX_BIN=${nginx_prefix_dir}/sbin/nginx prove t/**/*.t
GitHub
您可以在 nginx-module-small-light 的 GitHub 仓库 中找到有关此模块的其他配置提示和文档。