Перейти к содержанию

small-light: Модуль динамической трансформации изображений для NGINX

Установка на Debian/Ubuntu

Эти документы относятся к пакету APT nginx-module-small-light, предоставленному репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-small-light
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия            | Компонент   | Архитектуры   |
|-------------|-------------------|-------------|----------------|
| debian      | bookworm          | main        | amd64, arm64   |
| debian      | bookworm-mainline | main        | amd64, arm64   |
| ubuntu      | focal             | main        | amd64, arm64   |
| ubuntu      | focal-mainline    | main        | amd64, arm64   |
| ubuntu      | jammy             | main        | amd64, arm64   |
| ubuntu      | jammy-mainline    | main        | amd64, arm64   |
| ubuntu      | noble             | main        | amd64, arm64   |
| ubuntu      | noble-mainline    | main        | amd64, arm64   |

Динамический модуль трансформации изображений для nginx.

Начало работы

Добавьте конфигурацию ниже в контекст сервера в nginx.conf и запустите nginx.

small_light on;
location ~ small_light[^/]*/(.+)$ {
    set $file $1;
    rewrite ^ /$file;
}

Если вы можете получить оригинальное изображение image.jpg по следующему URL,

http://$host:$port/img/image.jpg

Вы сможете получить преобразованное изображение image.jpg по следующему URL.

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 -> сгенерировать gif изображение с качеством 100
    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 путь
По умолчанию
Контекст server

Эта директива назначает директорию для встроенных иконок изображений.

small_light_pattern_define

Синтаксис small_light_pattern_define имя_первера параметры
По умолчанию
Контекст server

Эта директива задает имя с параметрами, разделенными запятыми.

small_light_radius_max

Синтаксис small_light_radius_max число
По умолчанию 10
Контекст server,location

Эта директива устанавливает максимальное значение радиуса геометрии для sharpen и unsharp и blur.

small_light_sigma_max

Синтаксис small_light_sigma_max число
По умолчанию 10
Контекст server,location

Эта директива устанавливает максимальное значение сигмы для геометрии для sharpen и unsharp и blur.

small_light_imlib2_temp_dir

Синтаксис small_light_imlib2_temp_dir путь [уровень1 [уровень2 [уровень3 ]]]
По умолчанию small_light_imlib2_temp 1 2
Контекст server

Эта директива назначает директорию для временного файла для обработки Imlib2. Эта директива доступна, когда Imlib2 включен.

small_light_buffer

Синтаксис small_ligh_buffer размер
По умолчанию 1m
Контекст server

Эта директива задает максимальный размер буфера, используемого для чтения изображений когда Content-Length не установлен в заголовках ответа.

Параметры для функции small_light

Параметр Тип По умолчанию Описание ImageMagick Imlib2 GD
p string именованный паттерн из параметров через запятую :o: :o: :o:
e string imagemagick имя движка (imagemagick, imlib2, gd)
q number качество :o: :o: :o:
of string формат выходных данных (jpg, gif, png, webp) :o: :o: :o:
jpeghint char n включить подсказку для jpeg (y, n) :o: :o: :x:
dw coord sw ширина назначения :o: :o: :o:
dh coord sh высота назначения :o: :o: :o:
dx coord sx координата x назначения :o: :o: :o:
dy coord sy координата y назначения :o: :o: :o:
da char l управление соотношением сторон назначения (l, s, n) :o: :o: :o:
ds char n управление масштабированием назначения (s, n) :o: :o: :o:
cw number ширина холста :o: :o: :o:
ch number высота холста :o: :o: :o:
cc color 000000 цвет холста :o: :o: :o:
bw number ширина границы :o: :o: :o:
bh number высота границы :o: :o: :o:
bc color 000000 цвет границы :o: :o: :o:
sw coord ширина источника :o: :o: :o:
sh coord высота источника :o: :o: :o:
sx coord координата x источника :o: :o: :o:
sy coord координата y источника :o: :o: :o:
pt char n управление прохода (y, n) :o: :o: :o:
sharpen string радиус,сигма (например 10x5) :o: :o: :o:
unsharp string радиус,сигма,сила,порог (например 2x5+0.5+0) :o: :x: :x:
blur string радиус,сигма (например 5x10) :o: :o: :x:
embedicon string встроенный файл иконки в small_light_material_dir :o: :x: :x:
ix number 0 координата x встроенной иконки :o: :x: :x:
iy number 0 координата y встроенной иконки :o: :x: :x:
angle number 0 угол вращения (90, 180, 270) :o: :o: :o:
progressive char n сделать JPEG прогрессивным (y, n) :o: :x: :x:
cmyk2rgb char n преобразовать цветовое пространство из CMYK в sRGB (y, n) :o: :x: :x:
rmprof char n удалить профиль (y, n) :o: :x: :x:
autoorient char n включить автоматическую настройку ориентации изображения (y, n) :o: :x: :x:

Значения da это l, s и n. Они имеют следующие значения.

  • l: основано на длинной стороне
  • s: основано на короткой стороне
  • n: нет

Существуют следующие ограничения.

  • of=gif и of=webp не поддерживаются, когда e=imlib2.
  • autoorient доступен в ImageMagick версии 6.9.0 или более поздней.
  • Значение radius,sigma для sharpen и unsharp и blur ограничено small_light_radius_max и small_light_sigma_max.

Вот типы каждого параметра.

Тип Описание
coord координата или пиксель, процент при добавлении 'p'
char символ
number целое число
color rrggbb или rrggbbaa
string string

Именованный паттерн

ngx_small_light поддерживает именованные параметры, разделенные запятыми, с помощью small_light_define_patern.

small_light_pattern_define small dw=120,dh=120,q=80,e=imagemagick,jpeghint=y;

Если строка выше добавлена в контекст сервера в nginx.conf, два URL ниже вернут одинаковый ответ.

  • http://$host:$port/small_light(p=small)/img/image.jpg
  • http://$host:$port/small_light(dw=120,dh=120,q=80,e=imagemagick,jpeghint=y)/img/image.jpg

Использование GET параметров

ngx_small_light поддерживает конвертацию изображения не только с помощью функции small_light, но и через GET параметры в 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 поддерживает трансформацию WebP с ImageMagick и GD. Укажите of=webp для функции small_light, ngx_small_light преобразует формат изображения в WebP. Но ImageMagick требует libwebp, а GD требует libvpx. Вам необходимо встроить эти библиотеки в сборку ImageMagick и GD для включения трансформации WebP.

Если трансформация WebP недоступна, nginx выводит строку, подобную следующей, в error.log при обработке изображения с of=webp.

WebP is not supported

Если трансформация WebP с ImageMagick доступна, вывод команды convert -list format включает строку, подобную следующей.

$ convert -list format | grep -i webp
     WEBP* WEBP      rw-   WebP Image Format (libwebp 0.5.0[0208])

Если трансформация WebP с GD доступна, вывод команды gdlib-config --libs включает -lvpx.

В общем, пакеты ImageMagick и GD, предоставляемые дистрибутициями linux, такими как Ubuntu и CentOS, не встраивают библиотеку для трансформации WebP по умолчанию. В таких случаях вам нужно собрать ImageMagick или GD самостоятельно.

Советы по оптимизации

Существуют некоторые советы по оптимизации для ngx_small_light.

Подсказка для JPEG

Когда формат выходных данных JPEG, а движок конвертации изображений - ImageMagick или Imlib2, вы можете добавить jpeghint=y. Скорость обработки изображений значительно увеличивается.

Ограничьте количество потоков с помощью OpenMP

Когда движок конвертации изображений - ImageMagick и версия ngx_small_light ниже v0.6.14, рекомендуется установить 1 для OMP_NUM_THREADS или MAGICK_THREAD_LIMIT в nginx.conf. Поскольку OpenMP включен в ImageMagick по умолчанию, работа с включенным OpenMP в многопроцессорной среде очень медленная.

env OMP_NUM_THREADS=1; # или env MAGICK_THREAD_LIMIT=1;

Или вы можете избежать этой проблемы, собрав ImageMagick с --disable-openmp.

В 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