Ситуация знакомая: товар создан, изображение загружено, а на витрине вместо него пустое место, серый плейсхолдер или старая картинка из кеша. В WooCommerce проблема редко бывает в одном месте. Чаще всего ломается цепочка из медиабиблиотеки, размеров изображений, темы и кеширования.
Ниже разберём не абстрактную «не отображается картинка», а конкретные сценарии: миниатюра товара в каталоге, главное изображение на странице товара, галерея и изображения вариаций. Подход будет практический: сначала диагностика, потом исправление, затем проверка результата.
Когда проблема действительно в WooCommerce, а не в теме
Перед правками важно понять, где именно ломается вывод. Если изображение не видно только в каталоге, но открывается на странице товара, проблема обычно в шаблоне архива, CSS или в размере миниатюры. Если не показывается и на странице товара, смотрим attachment, настройки медиа и саму привязку изображения к товару.
Что проверить в первую очередь
- Открывается ли файл изображения напрямую по URL в медиабиблиотеке.
- Назначено ли изображение товара и есть ли галерея товара.
- Не скрывает ли тема блоки через CSS, например
display:noneилиopacity:0. - Не остались ли старые размеры миниатюр после смены темы.
- Не подменяет ли кеш старую версию файла.
Если у товара есть изображение в админке, но на фронтенде оно не выводится, откройте исходный код страницы и найдите HTML-блоки WooCommerce. Иногда картинка есть в разметке, но не видна из-за сломанного CSS или lazy load-обработчика темы.
Диагностика проблемы: где именно ломается цепочка
Удобнее идти от простого к сложному. Сначала исключите проблемы с самим файлом, потом с настройками WooCommerce, затем с темой и кешем.
1. Проверка файла изображения
Откройте изображение из медиабиблиотеки в новой вкладке. Если файл не открывается или отдаёт 404, проблема не в WooCommerce. Обычно это означает:
- файл удалён с сервера, но запись в медиабиблиотеке осталась;
- права на файл или папку
wp-content/uploadsвыставлены неверно; - после миграции сайта сломались пути к медиа.
2. Проверка привязки к товару
В карточке товара должно быть назначено главное изображение. Для вариативных товаров важно ещё проверить изображения вариаций: если у вариации нет своей картинки, WooCommerce покажет основное изображение товара или ничего, в зависимости от темы и настроек.
3. Проверка размеров изображений
Если тема менялась, старые размеры миниатюр могли остаться в базе, а новые файлы не были пересозданы. В результате каталог может тянуть размер, которого физически нет на диске. Это особенно заметно после перехода на новую тему или после изменения настроек в WooCommerce > Настройки > Товары > Отображение в старых установках.
Пошаговое решение без лишних плагинов
Ниже — рабочая последовательность, которая закрывает большинство случаев. Лучше выполнять её по порядку, а не хвататься сразу за код.
Шаг 1. Сбросить и пересоздать миниатюры
Если размеры изображений изменились, старые миниатюры нужно пересоздать. В админке это обычно делают через инструменты регенерации миниатюр. Если вы работаете на сервере и есть WP-CLI, можно использовать стандартную команду WordPress для регенерации изображений:
wp media regenerate --yesКоманда пересоздаст размеры для существующих вложений. Это не лечит битые файлы, но хорошо исправляет ситуацию, когда WooCommerce ищет не тот размер.
Шаг 2. Проверить, какие размеры реально регистрирует тема
Некоторые темы переопределяют размеры WooCommerce. Если тема зарегистрировала слишком маленький размер, каталог будет выглядеть размытым или обрезанным. В таком случае полезно явно задать размеры через фильтр.
add_filter( 'woocommerce_get_image_size_thumbnail', function( $size ) {
return array(
'width' => 300,
'height' => 300,
'crop' => 1,
);
} );
add_filter( 'woocommerce_get_image_size_single', function( $size ) {
return array(
'width' => 800,
'height' => 800,
'crop' => 0,
);
} );Этот код можно добавить в дочернюю тему или в небольшой mu-plugin. После изменения размеров снова пересоздайте миниатюры, иначе новые параметры не применятся к уже загруженным файлам.
Шаг 3. Убедиться, что тема не ломает вывод галереи
Если на странице товара есть разметка, но изображения не видны, проверьте CSS и шаблонные переопределения. Частая ошибка — тема скрывает стандартные классы WooCommerce и выводит свой слайдер поверх. В таком случае отключение одного скрипта может сразу вернуть изображения.
Для быстрой проверки временно переключитесь на стандартную тему WooCommerce-совместимую тему или откройте страницу товара в режиме инкогнито без кеша. Если картинка появилась, значит проблема в теме, а не в данных товара.
Шаг 4. Очистить кеш и исключить подмену старых файлов
После замены изображения по тому же имени браузер и серверный кеш могут продолжать отдавать старую версию. Это особенно заметно, если картинка обновлялась без смены имени файла. Надёжнее менять имя файла или очищать кеш на уровне плагина, CDN и браузера.
Если используется object cache или page cache, проверьте, не кешируется ли HTML блока товара слишком агрессивно. Для WooCommerce это критично на страницах каталога и карточки товара.
Если нужно исправить вывод изображений программно
Иногда задача не в самих файлах, а в том, что тема выводит не тот размер или не тот HTML. Тогда можно вмешаться через фильтры WooCommerce. Ниже пример, который принудительно задаёт размер миниатюры для каталога и отключает обрезку, если она мешает дизайну.
add_filter( 'woocommerce_get_image_size_thumbnail', function() {
return array(
'width' => 320,
'height' => 320,
'crop' => 0,
);
} );Если проблема в том, что тема подменяет стандартный вывод изображения товара, проверьте, не переопределён ли шаблон single-product/product-image.php. В дочерней теме можно временно вернуть стандартный шаблон WooCommerce и сравнить результат.
Как проверить, что исправление сработало
Проверка должна быть не визуальной «кажется, стало лучше», а технической. Иначе через неделю проблема вернётся после очередного обновления темы или кеша.
- Откройте страницу товара в режиме инкогнито и без кеша браузера.
- Проверьте HTML карточки товара: есть ли тег
<img>и правильныйsrc. - Убедитесь, что URL изображения отдаёт код
200, а не404или редирект на заглушку. - Сравните размер файла в каталоге и на странице товара: не должен подставляться старый размер.
- Проверьте несколько товаров, а не один: иногда ломается только конкретная категория или вариация.
Если у вас есть доступ к DevTools, откройте вкладку Network и обновите страницу. Так видно, подгружается ли изображение вообще, не блокирует ли его lazy load и не меняет ли URL скрипт оптимизации.
Частые ошибки и как их исправить
Изображение загружено, но не назначено товару
Пользователь добавил файл в медиабиблиотеку, но не нажал «Установить изображение товара». В WooCommerce это разные действия. Файл сам по себе на карточке не появится.
После смены темы остались старые размеры
Тема могла зарегистрировать собственные размеры миниатюр. После её замены старые размеры продолжают использоваться, пока вы не пересоздадите изображения. Решение: проверить настройки, затем регенерировать миниатюры.
Кеш показывает старую картинку
Если файл заменили с тем же именем, CDN и браузер часто отдают старую версию. Надёжнее менять имя файла или очищать кеш на всех уровнях.
CSS темы скрывает галерею
Иногда блок есть в DOM, но он невидим из-за display:none, visibility:hidden или перекрытия другим элементом. Проверяется через инспектор: если HTML есть, а изображения нет, смотрите стили.
Проблемы только у вариаций
У вариативного товара может не быть изображения у конкретной вариации. Тогда при выборе атрибута картинка не меняется. Проверьте каждую вариацию отдельно и не полагайтесь на основное изображение товара.
Сравнение подходов: что быстрее в реальной работе
| Подход | Когда подходит | Минус |
|---|---|---|
| Пересоздание миниатюр | После смены темы, размеров, миграции | Не решает битые файлы и CSS-конфликты |
| Фильтры WooCommerce | Когда нужен стабильный размер изображений | Нужно пересобирать миниатюры после изменения |
| Правка темы и CSS | Если изображение есть в HTML, но не видно | Требует аккуратной проверки шаблонов |
Практические советы по безопасности и производительности
Не храните правки в родительской теме: после обновления они затрутся. Для фильтров и точечных исправлений используйте дочернюю тему или mu-plugin. Если нужно массово оптимизировать сайт, имеет смысл отдельно проверить дубли, лишние размеры и мусорные стили — например, через Clearfy Pro, если он уже используется в проекте. Но саму проблему с изображениями он не заменяет: сначала нужно найти источник сбоя.
Ещё один момент — не отключайте все оптимизаторы изображений подряд. Когда несколько плагинов одновременно меняют src, srcset и lazy load, отладка становится почти бессмысленной. Лучше оставить один инструмент и проверить его поведение на тестовой странице.
Если после всех шагов изображения всё ещё не выводятся, полезно сравнить проблемный товар с рабочим: одинаковы ли тип товара, шаблон, категория, атрибуты и наличие вариаций. В WooCommerce такие расхождения часто и дают локальную ошибку, а не глобальную поломку сайта.