9. Кеш браузера, CDN, SuperCache и кеш страниц

Картинки и страницы кешируются на нескольких уровнях: в браузере посетителя, на CDN, в плагинах кеша страниц. Чтобы после замены картинки посетители не видели старую, плагин использует версию в имени файла.

Версия в имени файла

Каждый файл, который создаёт плагин, получает короткую версию перед расширением (и перед @2x):

1234-adaptive-343w-v3fa9c21b.jpg      1234-adaptive-343w-v3fa9c21b@2x.jpg
1234-v3fa9c21b.webp                   1234-lqip-v3fa9c21b.jpg      1234.200-v3fa9c21b.jpg

v3fa9c21b — это 8 символов, вычисленных из содержимого оригинала и параметров обработки витрины (движок, формат, качество, 2x, оптимизация). Что это даёт:

Вы заменили оригинал (например, повернули или восстановили картинку в Shop-Script, имя файла при этом остаётся прежним) — адрес копии меняется, и браузер, CDN, service worker и кеш страниц не покажут старую картинку под новым именем.
Две витрины с разным качеством не перезаписывают файлы друг друга.
Если оригинал «потрогали», но содержимое не изменилось — адрес не меняется.

Управление — в настройках витрины (вкладка «Настройки», «Дополнительные настройки»):

Версия в именах файлов (по умолчанию «Вкл»). «Выкл» — новые файлы получают прежние имена. Уже выданные адреса остаются рабочими в любом случае.
Проверять оригинал на странице (по умолчанию «Вкл») — один системный вызов на картинку при просмотре для обнаружения замены оригинала. Выключайте только на очень медленных сетевых дисках.
Файлы, созданные прежними версиями (3.3.x), сохраняют свои имена и не трогаются. Изменение качества или формата не пересоздаёт уже готовые файлы — для этого удалите созданные изображения и дайте им создаться заново.

Старые файлы

Заменённая версия не удаляется сразу: она «списывается» и хранится 30 дней (настройка «Хранить старые файлы, дней», от 7 до 365). Это нужно, чтобы страницы, закешированные раньше (кеш страниц, service worker, письма, поисковые системы), не получили ошибку 404.

Удаляются старые файлы:

командой фоновой обработки в конце запуска run, либо вручную:
```
php /путь/к/сайту/cli.php shop responsiveimagesPluginBackground sweep
```
(необязательные параметры: --limit 200, --max-time 50, --min-free-disk 200);
запросом посетителя после создания файлов — не более 20 локальных файлов за запрос (в S3 из запроса посетителя ничего не удаляется).

Без cron и без вызова sweep старые файлы не удаляются. Сколько файлов ждёт удаления, показано во вкладке «Диагностика» («Старые файлы») и в status.

Нехватка места: если свободного места меньше --min-free-disk (200 МБ по умолчанию), sweep удаляет старые версии независимо от срока, начиная с самых старых. Страница из кеша может получить 404 раньше 30 дней.

Для S3 плагин удаляет только свои файлы (производные от оригинала); строка из списка удаляется только после подтверждения удаления. Не ставьте на бакет правило удаления по возрасту.

Кеш в браузере посетителя: правила nginx и Apache

Стандартный .htaccess Webasyst отдаёт для картинок Cache-Control: max-age=3153600, public (JPG, PNG, GIF) и ничего для WebP и AVIF. Файл с версией в имени никогда не меняется под этим именем, поэтому его безопасно кешировать на год. Плагин сам файл .htaccess и конфигурацию nginx не меняет — добавить правило нужно самому (или попросить хостинг).

Правило необязательное. Оно нужно, если вы хотите, чтобы браузеры и CDN не перезапрашивали эти файлы. Для S3 плагин отправляет заголовок сам (поле «Cache-Control файлов»).

Правило затрагивает только файлы плагина и только те, у которых в имени -v и 8 шестнадцатеричных знаков. Не распространяйте его на файлы без версии: их адрес не меняется вместе с содержимым.

Apache 2.4

Добавьте в корневой .htaccess сайта после блока Webasyst (порядок важен: побеждает правило, идущее позже):

<IfModule mod_headers.c>
    <If "%{REQUEST_URI} =~ m#^/wa-data/public/shop/responsiveimages/images/.+-v[0-9a-f]{8}(@[23]x)?\.(jpe?g|png|gif|webp|avif)$#">
        Header set Cache-Control "public, max-age=31536000, immutable"
    </If>
</IfModule>

Требуется модуль mod_headers. Если сайт стоит не в корне домена (в подпапке), путь в правиле нужно скорректировать.

nginx

nginx не читает .htaccess. Блок добавляется в конфигурацию сайта до общего location для статических файлов:

location ~ "^/wa-data/public/shop/responsiveimages/images/.+-v[0-9a-f]{8}(@[23]x)?\.(jpe?g|png|gif|webp|avif)$" {
    add_header Cache-Control "public, max-age=31536000, immutable" always;
}

Важно:

Кавычки обязательны: nginx воспринимает {8} без кавычек как начало блока и отказывается принимать конфигурацию.
Знак ~, а не ~*: версия записывается строчными буквами и цифрами; -v3FA9C21B не версия.
Если в этом блоке не задавать собственные expires или Cache-Control, будет один заголовок. Заголовки add_header из внешнего блока в location со своими add_header не наследуются — повторите их при необходимости.
После правки проверьте конфигурацию командой nginx -t, затем перезагрузите nginx.

Эти фрагменты — общий шаблон. Если у вас хостинг без доступа к конфигурации, передайте этот раздел поддержке хостинга.

CDN

CDN перед сайтом или бакетом работает с версионными адресами корректно: замена оригинала даёт новый адрес. Однако:

Плагин не очищает кеш CDN сам.
HTML страницы с картинками может отличаться для разных посетителей (см. ниже); настройте CDN так, чтобы он не отдавал всем HTML первого посетителя.
Работа CDN перед бакетом S3 не проверялась.

Кеш страниц и особенность HTML

HTML страницы, который формирует плагин, зависит от трёх признаков посетителя:

cookie responsiveimages_resolution (ширина экрана),
cookie responsiveimages_dpr (плотность экрана),
заголовка Accept (поддержка WebP/AVIF).

Если плагин кеша страниц (или CDN) не различает посетителей по этим признакам, он отдаст всем HTML первого посетителя: например, мобильную ширину для компьютера. Версионные адреса эту проблему не решают.

Что можно сделать: настроить плагин кеша так, чтобы он учитывал эти cookie и заголовок, либо исключить страницы с картинками из кеша. Если вы разработчик плагина кеша: плагин вызывает событие responsiveimages_derivatives_updated (без гарантии доставки) после обновления адресов в журнале страницы; подписчик объявляет его в handlers своего plugin.php.

SuperCache

Проверено на тестовом стенде сочетание SuperCache 3.4.0 с локальным хранилищем (две витрины). Что нужно знать:

Включите в SuperCache опцию «Responsive Images PRO». По умолчанию она выключена. Включённая, она не обслуживает из кеша посетителей с cookie ширины и не пишет для них в кеш: в кеш попадает только страница без этой cookie (с оригинальными картинками). Выключенная — HTML первого посетителя с шириной его экрана сохраняется и отдаётся всем.
SuperCache не подписан на событие плагина. Страница, которую SuperCache уже закешировал, не обновляется, когда копии становятся готовыми или заменяется оригинал, пока SuperCache сам её не сбросит (по своим правилам, событиям Shop-Script или вручную). Адреса внутри такой страницы остаются рабочими весь срок хранения старых файлов (по умолчанию 30 дней).
Кеш SuperCache ведётся отдельно для каждого хоста: страницы двух витрин не смешиваются.
Если вы изменили настройки так, что какой-то тип файлов стал не нужен, эти файлы удаляются не сразу, а по тому же сроку хранения: закешированный раньше HTML продолжает работать.
S3 вместе с SuperCache не заявляется: это сочетание не проверялось. Если SuperCache работает с S3, заведите для него отдельный закрытый бакет.
Плагин не очищает кеши SuperCache, PWA (service worker) и CDN. После массовых изменений очистите их сами.

Если на сайте остались старые картинки

Очистите кеш страниц (SuperCache и т. п.), кеш CDN и кеш браузера (Ctrl+F5).
Проверьте вкладку «Диагностика» → «Почему изображение не обработано?».
См. Решение проблем.