Mudou o tema do WooCommerce e as imagens dos produtos ficaram desconfiguradas? Já passei por isso. Depois de trocar de template, as miniaturas antigas permanecem cortadas nas dimensões do tema anterior, enquanto o novo tema exige proporções completamente diferentes. O resultado: cortes em alguns sítios, distorções noutros e espaços em branco onde deveriam estar as imagens de destaque.

Editar manualmente cada produto é um beco sem saída quando o catálogo tem centenas de artigos. Felizmente, o WordPress oferece três métodos eficazes para regenerar miniaturas automaticamente: um plugin, o mecanismo nativo do WooCommerce e o WP-CLI. Cada um adequa-se a situações diferentes.

Vamos percorrer os cinco passos, do mais simples ao mais avançado.

💡 Visão geral rápida:

• Instale o plugin gratuito Regenerate Thumbnails do repositório do WordPress.org: resolve a grande maioria das tarefas de regeneração.
• Execute uma regeneração completa através de Ferramentas → Regenerate Thumbnails: o plugin processa todas as imagens de uma só vez.
• Para uma única imagem, use a regeneração a partir da biblioteca de multimédia: rápido e sem reconstrução em massa.
• Se tiver uma versão recente do WooCommerce (3.3+), ative a regeneração em segundo plano nativa: é acionada automaticamente quando as dimensões mudam.
• Para lojas grandes com acesso à shell, use o WP-CLI wp media regenerate: mais rápido do que o plugin e sem a sobrecarga do HTTP.

Passo 1: Instalar o plugin Regenerate Thumbnails

É um plugin gratuito com um milhão de instalações ativas no WordPress.org, mantido pela equipa da Automattic. Faz exatamente o que o nome promete, sem interface ou configurações desnecessárias.

Vá a Plugins → Adicionar Novo, procure por «Regenerate Thumbnails», clique em Instalar Agora e depois em Ativar. O plugin não requer configuração: após a ativação, o item de menu Ferramentas → Regenerate Thumbnails aparece imediatamente no painel de administração.

Note que o plugin trabalha com os ficheiros originais carregados. Não comprime novamente as imagens de origem, mas cria novas miniaturas usando as dimensões atuais definidas nas configurações do tema e em Configurações → Multimédia. As miniaturas antigas são opcionalmente eliminadas (marque «Eliminar miniaturas antigas não utilizadas»).

Passo 2: Executar uma regeneração completa de todas as miniaturas

Abra Ferramentas → Regenerate Thumbnails. A interface é minimalista: um botão e três opções.

Antes de começar, certifique-se de que a opção Saltar a regeneração de miniaturas existentes com o tamanho correto está selecionada: isto poupa tempo ao ignorar miniaturas que já correspondem às dimensões necessárias.

Clique em Regenerar Todas as Miniaturas. O plugin processa cada imagem da biblioteca de multimédia, uma a uma. Para cem imagens, o processo demora 2 a 3 minutos. Para vários milhares, até 15 a 20 minutos.

Não feche o separador do navegador enquanto a regeneração estiver a decorrer. Se a página for atualizada sozinha, não há problema: as imagens já processadas permanecem reconstruídas e o plugin simplesmente continua de onde parou.

Após a conclusão, verá um resumo a mostrar quantas miniaturas foram recriadas com sucesso e quantas tiveram erros. Os erros geralmente estão relacionados com ficheiros corrompidos (JPEG danificado ou formato não padrão), que ficam visíveis no registo.

O resultado é irreversível. Não pode reverter as miniaturas reconstruídas para versões anteriores, por isso faça uma cópia de segurança do site antes de uma regeneração em massa.

Passo 3: Restaurar uma imagem específica

A regeneração em massa nem sempre é necessária. Se substituiu a ficha de um único produto e quer reconstruir apenas as suas miniaturas, o plugin permite fazê-lo de forma seletiva.

Vá a Multimédia → Biblioteca e mude para a Vista de Lista. Ao lado de cada imagem, na linha, verá um link Regenerate Thumbnails.

Clique nele e o plugin reconstruirá as miniaturas apenas para esse ficheiro. O tempo de processamento para uma única imagem é de 1 a 2 segundos.

Este mesmo método funciona para regeneração em lote: marque as caixas ao lado das imagens de que precisa, selecione Regenerate Thumbnails no menu suspenso de ações em massa e clique em Aplicar. Conveniente quando as edições afetaram algumas dezenas de imagens em vez de todo o catálogo.

A propósito, a mesma opção está disponível na página de edição individual do anexo: clique numa imagem na biblioteca de multimédia e um botão de regeneração aparece na barra lateral.

Passo 4: Ativar a regeneração nativa do WooCommerce

A partir do WooCommerce 3.3, a regeneração de miniaturas em segundo plano está incorporada no núcleo. É acionada automaticamente em dois casos: quando altera as dimensões das imagens através do personalizador e as publica, ou quando muda de tema.

Funciona assim: o WooCommerce deteta uma incompatibilidade entre os tamanhos atuais das miniaturas e os tamanhos definidos, coloca uma tarefa em segundo plano na fila e reconstrói gradualmente tudo o que é necessário. O personalizador fornece uma pré-visualização ao vivo, pelo que as alterações são visíveis de imediato, mesmo antes de publicar.

Pode verificar se a fila está a correr em WooCommerce → Estado → Registos: selecione o registo wc-background-regeneration. Se o processo estiver ativo, um aviso com um botão de cancelamento aparece no painel de administração.

Quando o mecanismo nativo não funciona (por exemplo, o site está protegido por BasicAuth e a fila em segundo plano não consegue fazer pedidos HTTP para si mesmo), desative-o com um filtro:

1
add_filter( 'woocommerce_background_image_regeneration', '__return_false' );

Depois disso, execute a regeneração manualmente através do plugin ou do WP-CLI.

Para a maioria das lojas em versões recentes do WooCommerce, este mecanismo nativo é suficiente. O plugin Regenerate Thumbnails é necessário quando quer controlo manual sobre o processo ou quando quer limpar miniaturas antigas não utilizadas.

Passo 5: Regenerar via WP-CLI (para lojas grandes)

A linha de comandos é o método mais rápido porque não há sobrecarga de pedidos HTTP e interface do navegador. Adequado se tiver acesso SSH e o WP-CLI instalado.

Comando básico para regenerar todas as miniaturas:

1
wp media regenerate --yes

O sinalizador --yes salta a confirmação. Sem ele, o WP-CLI pede confirmação para cada anexo, o que é inútil com milhares de imagens.

Para um único anexo, especifique o seu ID:

1
wp media regenerate 123

A opção útil --image_size especifica um tamanho particular para regeneração. Por exemplo, se o tema adicionou um novo tamanho shop_catalog e os outros não precisam de ser alterados:

1
wp media regenerate --image_size=shop_catalog

Para lojas muito grandes (dezenas de milhares de produtos), execute o comando dentro do screen ou tmux para que o processo não seja interrompido se a sessão SSH se desligar. E faça definitivamente uma cópia de segurança antes de executar: o WP-CLI, tal como o plugin, substitui as miniaturas de forma irreversível.

⁉️🤔 Perguntas frequentes

Preciso de regenerar miniaturas depois de atualizar o WooCommerce?

Atualizar o WooCommerce por si só não altera as dimensões das imagens, pelo que a regeneração não é necessária. Mas se a atualização incluir uma reposição das configurações do personalizador ou se atualizou o tema ao mesmo tempo, verifique as dimensões das miniaturas e execute a regeneração se houver uma incompatibilidade.

O que devo fazer se a regeneração ficar bloqueada?

Atualize a página Ferramentas → Regenerate Thumbnails. O plugin continuará do mesmo ponto: processa as imagens uma a uma e não perde o progresso. Se continuar a bloquear no mesmo ficheiro, a imagem de origem está provavelmente corrompida. Descarregue-a da biblioteca de multimédia, volte a guardá-la num editor de imagem e carregue-a novamente.

Posso regenerar miniaturas num site de teste e depois transferi-las para produção?

Tecnicamente sim: copie a pasta /wp-content/uploads/ após a regeneração. Mas isto é arriscado: as miniaturas estão fortemente ligadas às dimensões definidas no tema e em Configurações → Multimédia. Se o site de produção tiver configurações diferentes, as miniaturas voltarão a não corresponder. É mais fiável executar a regeneração diretamente no servidor de produção depois de fazer uma cópia de segurança.

Porque é que o WP-CLI é melhor do que o plugin?

Velocidade. O plugin faz um pedido HTTP para si mesmo via AJAX: cada ficheiro significa um pedido. O WP-CLI trabalha diretamente com o sistema de ficheiros e a base de dados, sem a camada do servidor web. Em mil imagens, a diferença é de minutos contra meia hora. Mas o WP-CLI requer acesso à shell, que nem todos os alojamentos fornecem.

A regeneração elimina as imagens originais?

Não. Tanto o plugin como o WP-CLI e o mecanismo nativo do WooCommerce trabalham apenas com miniaturas: cópias geradas a partir do original em dimensões específicas. O ficheiro original carregado permanece intacto. É por isso que pode executar a regeneração quantas vezes quiser.

Devo eliminar miniaturas antigas não utilizadas?

Sim, se o espaço em disco do seu alojamento estiver a esgotar-se. A caixa de verificação «Eliminar miniaturas antigas não utilizadas» no plugin Regenerate Thumbnails encontra e remove miniaturas cujos tamanhos já não estão registados nem no tema nem em Configurações → Multimédia. Faça definitivamente uma cópia de segurança antes de o fazer: os ficheiros eliminados só podem ser restaurados a partir de uma cópia de segurança.

O que fazer se as imagens ainda não estiverem corretas após a regeneração?

Percorra uma pequena lista de verificação. Primeiro: abra Configurações → Multimédia e Aparência → Personalizar → WooCommerce → Imagens de Produtos, compare as dimensões. Se não corresponderem ao que está definido no tema, a regeneração produz miniaturas diferentes das que o modelo espera. Segundo: verifique se um plugin de cache ou CDN está a armazenar em cache miniaturas antigas e limpe a cache. Terceiro: abra o ficheiro de origem na biblioteca de multimédia: se o próprio original tiver baixa resolução, nenhuma regeneração melhorará a qualidade.

Para a maioria das situações, o Regenerate Thumbnails gratuito é suficiente. Se a sua loja for grande e precisar de regeneração regularmente, aprenda WP-CLI: um comando poupa dezenas de minutos. E nas versões recentes do WooCommerce, o mecanismo em segundo plano muitas vezes é acionado sozinho: basta publicar as novas dimensões no personalizador.