# Como corrigir o widget de galeria do Elementor que não carrega imagens no WordPress

A galeria do Elementor não carrega imagens quando o tamanho de miniatura selecionado no widget não existe na biblioteca de mídia, quando um plugin de cache ou lazy load adia o carregamento das fotos, ou quando o caminho dos arquivos quebrou após migração, CDN ou troca de domínio.

## O que é galeria do Elementor que não carrega imagens?

A galeria do Elementor é um widget que monta uma grade de imagens a partir de itens escolhidos na biblioteca de mídia do WordPress. Para cada imagem o widget pede ao WordPress um tamanho específico (miniatura, média, grande ou um tamanho personalizado definido em Image Size) e exibe esse arquivo redimensionado, abrindo a versão completa em um lightbox ao clicar. Quando o widget não encontra o arquivo daquele tamanho, ou quando algo intercepta o carregamento, a grade aparece vazia, com espaços em branco ou com o ícone de imagem quebrada.

O problema raramente está no widget em si. Na prática ele apenas reflete um arquivo que não existe mais naquele tamanho, um endereço de imagem que mudou ou um script de otimização que segura o carregamento da foto. Por isso a correção passa por regenerar miniaturas, alinhar o tamanho pedido pelo widget ao que existe na mídia, e desligar temporariamente cache e lazy load para isolar a causa antes de tratar o caminho real dos arquivos.

## Como identificar

- A grade da galeria aparece montada, mas no lugar de cada foto surge o ícone de imagem quebrada do navegador.
- Os espaços das imagens ficam totalmente em branco e só carregam a foto quando você dá um zoom ou rola a página de novo.
- No editor do Elementor a galeria mostra as imagens, mas no site publicado (frontend) elas não aparecem.
- O console do navegador (F12) registra erros 404 nos arquivos de imagem, com sufixo de tamanho no nome do arquivo, por exemplo 'foto-300x300.jpg'.
- A galeria carrega no desktop, mas no celular as imagens não aparecem ou demoram muito por causa do lazy load.
- Após uma migração ou troca de domínio, todas as galerias do site passaram a exibir imagens quebradas ao mesmo tempo.

**Antes de começar:** Antes de regenerar miniaturas em massa, rodar search-replace no banco ou desativar plugins de cache em produção, faça um backup completo do site (arquivos e banco de dados) ou teste primeiro em um ambiente de staging, para poder reverter caso algo saia errado.

## Como prevenir

- Sempre envie as imagens pela biblioteca de mídia do WordPress, nunca via FTP ou direto no banco, para que todas as versões redimensionadas sejam geradas.
- Ao trocar de tema ou ativar plugins que registram tamanhos de imagem, regenere as miniaturas e revise os tamanhos usados nas galerias.
- Mantenha as imagens da galeria na lista de exclusão de lazy load do plugin de otimização, em vez de desligar o recurso para o site inteiro.
- Em toda migração ou troca de domínio, use uma ferramenta de search-replace que respeite a serialização e teste as galerias antes de tirar o site antigo do ar.
- Ao usar CDN ou hotlink protection, confirme que o próprio domínio do site está liberado para servir as imagens.

Erros relacionados

- [Como corrigir Elementor com widgets que não aparecem](https://full.services/wp-fixer/corrigir-elementor-widgets-nao-aparecem/)
- [Como corrigir CSS do Elementor que não aplica no frontend](https://full.services/wp-fixer/corrigir-elementor-css-nao-aplica/)
- [Como corrigir Elementor com tela cinza ou carregando infinito](https://full.services/wp-fixer/corrigir-elementor-tela-cinza/)

## Causa

- O tamanho de imagem selecionado no campo Image Size do widget (por exemplo Thumbnail 150x150 ou um tamanho personalizado) não foi gerado para aquelas fotos na biblioteca de mídia, então o WordPress não encontra o arquivo daquele tamanho e a galeria fica vazia.
- Um plugin de cache ou de otimização (como WP Rocket ou Perfmatters) está com o lazy load de imagens ativo e adia o carregamento das fotos da galeria, que só aparecem ao rolar, ou nunca aparecem quando o lightbox e o lazy load entram em conflito.
- Houve migração de site, troca de domínio ou mudança de http para https e o caminho gravado das imagens da galeria ainda aponta para o endereço antigo, gerando erro 404 em cada arquivo.
- As miniaturas nunca foram geradas porque as imagens foram importadas direto no banco ou via FTP sem passar pela biblioteca de mídia, então só existe o arquivo original e não as versões redimensionadas que o widget pede.
- Uma CDN ou regra de hotlink protection está bloqueando o acesso aos arquivos de imagem do domínio, fazendo a galeria carregar em branco mesmo com os arquivos presentes no servidor.
- O tema ou outro plugin removeu ou alterou tamanhos de imagem registrados, então o tamanho que a galeria foi configurada para usar deixou de existir nas próximas imagens enviadas.

## Como resolver

1. Confirme se a falha está no editor ou só no frontend: Abra a página no editor do Elementor e veja se as imagens da galeria aparecem ali. Se aparecem no editor mas somem no site publicado, a causa quase sempre é cache ou lazy load, e não a mídia. Isso direciona os próximos passos.

```
Painel WP -> Páginas -> abra a página -> Editar com Elementor
Compare a galeria no editor com a mesma galeria no site publicado (frontend)
```

2. Regenere as miniaturas das imagens: Reconstrua os tamanhos de imagem que o widget pede. Use um plugin como Regenerate Thumbnails ou, se tiver acesso a linha de comando, o WP-CLI. Isso recria as versões redimensionadas faltantes que estavam causando os 404 na galeria.

```
Painel WP -> Plugins -> Adicionar novo -> instale e ative 'Regenerate Thumbnails'
Painel WP -> Ferramentas -> Regenerate Thumbnails -> Regenerate All Thumbnails
Via WP-CLI (alternativa): wp media regenerate --yes
```

3. Ajuste o tamanho da imagem no próprio widget: Abra o widget de galeria e em Image Size troque para um tamanho padrão que existe (como Large ou Full) para validar se o problema é o tamanho personalizado ausente. Se as fotos voltarem, mantenha um tamanho registrado e regenere as miniaturas para o tamanho desejado.

```
Editar com Elementor -> clique no widget Galeria
Aba Conteúdo -> campo Image Size -> selecione 'Large' ou 'Full'
Atualize a página e confira a galeria no frontend
```

4. Desative cache e lazy load para isolar a causa: Limpe o cache do site e desligue temporariamente o lazy load de imagens do plugin de otimização. Se a galeria voltar a carregar, reative o lazy load e adicione a galeria ou as imagens à lista de exclusão do plugin, em vez de deixá-lo desligado.

```
Painel WP -> plugin de cache (ex.: WP Rocket) -> Limpar cache
WP Rocket -> aba Media -> desmarque 'Enable for images' em LazyLoad
Perfmatters -> Assets -> Lazy Loading -> desative 'Images' temporariamente
```

5. Corrija os caminhos das imagens após migração: Se as imagens quebraram após troca de domínio ou de http para https, atualize as URLs gravadas no banco com uma ferramenta de search-replace que respeite a serialização, nunca um find-and-replace cru no SQL. Depois limpe o cache e regenere o CSS do Elementor.

```
Instale 'Better Search Replace' -> Painel WP -> Ferramentas -> Better Search Replace
Busque 'http://site-antigo.com' e substitua por 'https://site-novo.com'
Marque 'Run as dry run' primeiro, confira e só então rode de verdade
Elementor -> Ferramentas -> Regenerar CSS e Dados
```

6. Verifique CDN e hotlink protection: Se os arquivos existem no servidor mas a galeria carrega em branco, abra a URL de uma imagem direto no navegador. Se ela não abrir, a CDN ou uma regra de hotlink está bloqueando o acesso. Libere o domínio do site na CDN ou desative a proteção de hotlink para o próprio domínio.

```
Console do navegador (F12) -> aba Network -> recarregue e veja o status dos arquivos de imagem
Copie a URL de uma imagem 404 e abra em uma aba nova para confirmar
No painel da CDN ou no hotlink protection, adicione o domínio do site à allowlist
```


## Código

```php
<?php
// Registra (ou re-registra) o tamanho de imagem que o widget de galeria usa.
// Vai no functions.php do tema filho ou em um plugin de site (mu-plugin).
add_action( 'after_setup_theme', 'full_galeria_image_size' );
function full_galeria_image_size() {
    add_theme_support( 'post-thumbnails' );
    // Nome do tamanho, largura, altura, recorte (crop) duro.
    add_image_size( 'galeria-elementor', 600, 600, true );
}

// Disponibiliza o tamanho na lista de seleção (caso queira escolhê-lo no editor).
add_filter( 'image_size_names_choose', 'full_galeria_size_label' );
function full_galeria_size_label( $sizes ) {
    $sizes['galeria-elementor'] = 'Galeria Elementor (600x600)';
    return $sizes;
}
```

## Perguntas frequentes

### Por que a galeria do Elementor aparece com imagens quebradas

Na maioria dos casos o tamanho de imagem que o widget pede não existe na biblioteca de mídia, ou o caminho dos arquivos mudou após uma migração. Regenere as miniaturas e confirme em Image Size se o tamanho selecionado existe para aquelas fotos.

### As imagens aparecem no editor do Elementor mas somem no site publicado

Quando a galeria carrega no editor e some no frontend, a causa quase sempre é cache ou lazy load. Limpe o cache, desative o lazy load de imagens temporariamente e, se voltar, adicione as imagens à exclusão do plugin de otimização.

### Regenerar miniaturas resolve a galeria que não carrega

Resolve quando o problema é falta dos tamanhos redimensionados que o widget pede. Use o plugin Regenerate Thumbnails ou o comando WP-CLI wp media regenerate para recriar todos os tamanhos e fazer as imagens 404 voltarem a existir.

### O lazy load do WP Rocket quebra a galeria do Elementor

Pode quebrar quando o lazy load adia o carregamento e entra em conflito com o lightbox da galeria. Em vez de desligar o recurso para o site todo, exclua as imagens da galeria do lazy load nas configurações do WP Rocket ou do Perfmatters.

### Por que a galeria quebrou depois que migrei o site

Após migração ou troca de domínio, as URLs das imagens gravadas no banco continuam apontando para o endereço antigo e geram 404. Use uma ferramenta de search-replace que respeite a serialização para atualizar as URLs e depois regenere o CSS do Elementor.

### Como saber se o problema é a CDN bloqueando as imagens

Abra a URL de uma imagem da galeria direto em uma aba nova do navegador. Se o arquivo existe no servidor mas não abre, a CDN ou uma regra de hotlink está bloqueando. Libere o domínio do site na allowlist da CDN ou ajuste a proteção de hotlink.

### A galeria carrega no desktop mas não no celular

Esse padrão costuma indicar lazy load agressivo no mobile ou um tamanho de imagem que não foi gerado para telas menores. Desative o lazy load para testar e regenere as miniaturas para garantir que todos os tamanhos existam.

### Preciso editar código para corrigir a galeria do Elementor

Na maioria dos casos não. Regenerar miniaturas, ajustar o Image Size e gerenciar o lazy load se resolve pelo painel. Código só é necessário quando você quer registrar ou ajustar um tamanho de imagem personalizado no tema.

**Fonte:** [Elementor — Image Gallery Widget (documentação oficial)](https://elementor.com/help/image-gallery-widget/)