Tamanho de Imagem de Produto no WooCommerce: os Três Tamanhos e Como Mudar Cada Um

O WooCommerce gera três tamanhos de imagem para cada foto de produto que você envia, e só dois deles são editáveis no painel do WordPress. woocommerce_thumbnail é a imagem da grade do catálogo, woocommerce_single é a imagem grande na página do produto, e woocommerce_gallery_thumbnail é a tirinha de miniaturas logo abaixo. Você muda tudo isso em Aparência > Personalizar > WooCommerce > Imagens do Produto — e se esse painel mostra um seletor de corte mas nenhum campo de largura, é porque o seu tema travou as larguras no código de propósito.

Os três tamanhos

Nome do tamanho	Onde aparece	Corte	Editável no personalizador
woocommerce_thumbnail	Página da loja, grades de categoria, produtos relacionados, cross-sells	Corte forçado em quadrado por padrão	Largura e proporção
woocommerce_single	Imagem principal na página individual do produto	Sem corte — mantém a proporção original	Só a largura
woocommerce_gallery_thumbnail	Tirinha pequena embaixo da imagem principal	Quadrado com corte forçado	Não

Esses tamanhos vêm por cima dos tamanhos padrão do WordPress. Uma única foto de produto costuma gerar thumbnail, medium, medium_large, large, os três tamanhos do WooCommerce e possivelmente extras registrados pelo seu tema com add_image_size. É muito arquivo por upload, e é por isso que importar 300 produtos demora tanto.

A miniatura de galeria é a que mais surpreende: ela não tem controle nenhum no painel. Numa instalação padrão é um quadradinho, historicamente de 100px, e é o tamanho com mais chance de parecer sem nitidez em tela retina, porque o arquivo físico é minúsculo mesmo.

Onde as configurações realmente ficam

Aparência > Personalizar > WooCommerce > Imagens do Produto te dá três controles:

• Largura da imagem principal — a largura de woocommerce_single. A altura é automática, então a proporção original é preservada.
• Largura da miniatura — a largura de woocommerce_thumbnail.
• Corte da miniatura — 1:1 (quadrado, o padrão), Personalizado (você digita uma proporção como 4:3) ou Sem corte.

Repare no que falta: não existe campo de altura para a miniatura do catálogo, porque a altura vem da proporção de corte. E não existe absolutamente nada para a miniatura de galeria.

Antes de mudar qualquer coisa, ajuda ver exatamente quais derivadas um arquivo vai gerar — jogue uma foto de produto real na ferramenta de tamanhos de imagem do WordPress e você recebe a lista completa, incluindo se a sua origem é grande o bastante para preencher cada tamanho sem ampliação.

Por que as imagens do seu catálogo ficam estranhas

A miniatura do catálogo faz corte forçado em quadrado. Corte forçado significa que o WooCommerce pega um quadrado central da sua foto e joga o resto fora — não coloca faixas nas laterais e não achata a imagem. Uma foto de produto de 2000x1200 vira uma fatia de 1200x1200 tirada do meio, e depois é reduzida.

Isso está ótimo para uma garrafa fotografada bem no centro com margem em volta. É um desastre para:

• Produtos compridos (esquis, cabos, varões de cortina) — você vê o terço do meio e mais nada
• Composições fora do centro — o produto escorrega para a borda do quadro e é fatiado
• Fotos em que o item preenche o quadro de ponta a ponta — o topo e a base são cortados
• Fotos de estilo de vida com o produto em um canto

O conselho de sempre é “mude o corte para Sem corte”. Funciona, mas seja honesto sobre o custo: sem corte significa que cada miniatura mantém a própria proporção, então uma grade com fotos de orientações variadas fica visualmente irregular, e as linhas param de se alinhar a menos que o CSS do seu tema lide com alturas variáveis. A maioria dos temas presume quadrados.

A solução melhor, se você puder investir nela, está na origem: padronize fotos de produto quadradas, com o item centralizado e espaçamento igual. Aí o corte quadrado forçado não faz diferença nenhuma e tudo lá na frente fica previsível. Mudar a configuração de corte é o remédio paliativo; imagens de origem consistentes são a solução de verdade.

Quando o tema trava as larguras

Se o seu painel de Imagens do Produto só oferece corte, o seu tema declarou larguras fixas ao registrar o suporte ao WooCommerce:

add_theme_support( 'woocommerce', array(
    'single_image_width'    => 800,
    'thumbnail_image_width' => 400,
) );

Quando um tema passa esses valores, o WooCommerce remove os controles de largura do personalizador e deixa só a proporção. Isso não é bug e não é o tema sendo hostil — o CSS de layout de produto do tema foi construído em cima daquelas larguras exatas em pixels, e deixar você mudá-las quebraria a grade.

Você pode sobrescrever isso pelo functions.php de um tema filho usando o filtro por tamanho:

add_filter( 'woocommerce_get_image_size_single', function ( $size ) {
    $size['width']  = 1000;
    $size['height'] = '';
    $size['crop']   = 0;
    return $size;
} );

add_filter( 'woocommerce_get_image_size_gallery_thumbnail', function ( $size ) {
    $size['width']  = 150;
    $size['height'] = 150;
    $size['crop']   = 1;
    return $size;
} );

O mesmo padrão vale para woocommerce_get_image_size_thumbnail. Esse também é o único jeito de mudar a miniatura de galeria, já que ela não tem interface.

O custo real, dito de forma direta: ao sobrescrever uma largura travada, o arquivo que o WooCommerce gera deixa de bater com o que o CSS do tema espera. Normalmente a imagem só é redimensionada pelo navegador e fica boa, porque agora é maior que a caixa. Às vezes o tema tem um contêiner de altura fixa e você acaba com faixas ou transbordamento. Teste em um produto antes de regenerar 2.000.

Mudar os tamanhos significa regenerar

Toda configuração de tamanho só afeta uploads novos. Os produtos existentes continuam entregando os arquivos gerados quando foram enviados, então nada muda visualmente até você reconstruí-los.

O WooCommerce dispara uma regeneração em segundo plano quando você salva o personalizador. Em um catálogo pequeno isso basta. Em um catálogo grande, depende do WP-Cron disparar de forma confiável, o que em uma loja de pouco tráfego muitas vezes não acontece, e você fica com uma biblioteca regenerada pela metade. Rode você mesmo:

wp media regenerate --yes

Para reconstruir só as imagens de produto:

wp media regenerate --yes --post_type=product

Se quiser tirar o processo em segundo plano do caminho enquanto faz isso manualmente:

add_filter( 'woocommerce_background_image_regeneration', '__return_false' );

Duas coisas que a regeneração não faz. Ela não apaga os arquivos antigos — o seu diretório de uploads guarda cada derivada órfã das configurações anteriores, e ele vai crescer. E ela não consegue criar um tamanho maior que a sua origem, porque o WordPress não amplia. Se você definir a largura da imagem principal em 1200 mas as suas fotos de produto tiverem 800px de largura, nenhum arquivo de 1200px é criado; o navegador recebe um arquivo de 800px e o estica, e o srcset não tem nada melhor a oferecer.

O tamanho que você deve realmente enviar

Mire em imagens de origem quadradas com cerca do dobro da sua maior largura configurada — 1200x1200 para uma imagem principal de 600px, 1600x1600 se o seu tema usa 800px. Isso cobre telas retina 2x e dá ao WordPress pixels suficientes para gerar todas as derivadas sem ampliação. Mantenha todos os produtos nas mesmas dimensões para a grade ficar uniforme.

Ainda travado?

Se os tamanhos estão configurados corretamente, você já regenerou e um produto continua estranho, abra a imagem em uma nova aba e leia o nome do arquivo. Um sufixo de dimensão que não corresponde a nenhum tamanho configurado por você significa que outra coisa registrou aquele tamanho. Nenhum sufixo significa que o WooCommerce recorreu ao arquivo em tamanho original, o que quase sempre quer dizer que a origem era pequena demais para o tamanho pedido. Passe esse arquivo de origem pela ferramenta de tamanhos de imagem e compare o que o WordPress deveria gerar com o que o navegador realmente carregou — quando os dois divergem, geralmente tem um plugin de otimização ou um redimensionador de imagem de CDN sentado no meio.