FAQ

Общее

Чем ImageOptimizer отличается от Thumb3x / pThumb?

ImageOptimizer создаёт статические WebP/AVIF рядом с оригиналом и оборачивает <img> в <picture> на выходе страницы. Thumb3x и pThumb делают on-the-fly ресайз по URL. Пакеты можно комбинировать, но не дублируйте responsive на одних и тех же картинках. См. Совместимость.

Нужен ли MiniShop3?

Нет. Inject работает на любом HTML-сайте MODX. MS3 чаще всего на витрине магазина.

Ломается ли SVG?

SVG не конвертируется и не попадает в очередь. Обрабатываются растровые форматы: jpg, png, gif; webp как source тоже пропускается.

Очередь и конвертация

После установки тысячи pending — это нормально?

Да, если вы сделали rebuild по корню assets/ или большому каталогу. Ограничьте path при rebuild (assets/images/catalog) или используйте cron с меньшим imageoptimizer_cron_limit.

Очередь сама не обрабатывается?

Worker не стартует от upload или rebuild. Варианты:

1. Обработать очередь в админке — батчи до pending = 0, можно Остановить (Админка)
2. Cron: cron/convert.php (фон без открытой вкладки)
3. CLI: cli/convert.php --limit=N

Нужно ли жать «Обработать» много раз?

С версии 1.0.4 — нет. Одна кнопка крутит батчи, пока очередь не опустеет или вы не нажмёте Остановить. При лимите времени PHP дожмите cron или нажмите снова.

Rebuild по папке показывает 0?

Путь относительно корня media source (basePath), без ведущего /. Пример MS3: images/resources, не /images/resources. Dry-run считает файлы; строк очереди будет больше (breakpoints × formats).

Почему статус skipped?

Частые причины: upscale=0 (картинка меньше breakpoint), preflight (SVG, animated GIF, HEIC без декодера), MemoryLimit.

Failed: «Unable to create cache directory»

Обновите пакет: worker создаёт core/cache/imageoptimizer/ перед копированием. Либо вручную:

mkdir -p core/cache/imageoptimizer
chmod 775 core/cache/imageoptimizer

Как переконвертировать после смены quality?

Удалите варианты *.webp / *.avif на диске, удалите записи done или сделайте rebuild по path.

Фронтенд

<picture> не появляется

1. imageoptimizer_enabled и imageoptimizer_inject_frontend = 1
2. Плагин активен, событие OnWebPagePrerender
3. Путь <img src> резолвится в media source (локальный assets/...)
4. На диске есть готовые варианты (status done)
5. Очистите кэш MODX и HTML-кэш ImageOptimizer

Подробнее: Решение проблем.

Кириллица превратилась в Д после inject

Обновите до 1.0.4+. Старый HTML-кэш удалите: Очистить кэш MODX или Очистить варианты в админке. Подробнее: Авто-inject и picture.

Как отключить для одной картинки?

class="no-optim" (из skip_classes), атрибут data-imageoptimizer-skip или свой класс в imageoptimizer_skip_classes.

Уже есть srcset на img

ImageOptimizer не перезаписывает ваш srcset; может добавить lazy/decoding. Для полного <picture> уберите ручной srcset или используйте skip.

Inject не кэшируется для авторизованных

Так задумано: HTML-кэш inject отключён для залогиненных на фронте. Проверяйте страницу в режиме инкогнито или после выхода из аккаунта.

Работает ли inject в письмах?

Нет. imageoptimizer_inject_email в настройках зарезервирован, код inject для email не реализован.

Админка

Белый экран / VueTools

Установите VueTools ≥ 1.1.2-pl, очистите кэш браузера. Пересборка админки нужна только при установке из исходников, не из ModStore. См. README на GitHub.

Нет пункта меню

Проверьте ACL: группа должна иметь imageoptimizer_view. Переустановите пакет или добавьте права вручную. См. Админка.

Ошибка JSON в Overview («Unexpected token '<'»)

Коннектор вернул HTML. Обновите страницу, проверьте Network → connector.php. См. Решение проблем.

Live не обрабатывает очередь

Live только обновляет цифры на экране. Фоновая обработка — cron (команда на вкладке Server).

Server: все энкодеры «Не найден» (macOS Valet)

FPM часто без imagick и с пустым PATH. CLI и FPM должны быть одной версии PHP. См. Решение проблем.

Производительность

Нагрузка на cron

Уменьшите imageoptimizer_cron_limit. Конвертируйте ночью большими --limit через CLI.

Размер диска

Каждый breakpoint × format — отдельный файл. Для каталога из 10k фото × 5 breakpoints × 2 formats планируйте место или сократите breakpoints/formats.

Связанные разделы

• Решение проблем — пошаговая диагностика
• Системные настройки — все ключи
• Авто-inject и picture — разметка и inject

Баги и предложения: Issues на GitHub.