# Como corrigir o erro de Lazy Load no Perfmatters

O lazy load do Perfmatters falha quando as imagens travam num placeholder, quebram ou não carregam até o usuário rolar. As causas mais comuns são o script lazyload.min.js ser adiado por outro plugin, dois lazy loaders ativos ao mesmo tempo ou imagens acima da dobra não excluidas.

## O que é o erro de Lazy Load do Perfmatters?

Lazy Load no Perfmatters e o recurso que adia o carregamento de imagens, iframes e vídeos até que entrem na área visivel da tela, reduzindo requisicoes e peso inicial da página. O recurso usa o arquivo lazyload.min.js (cerca de 2,5 KB) e desativa o lazy load nativo do WordPress quando ligado. O erro acontece quando esse mecanismo entra em conflito com outra solução, e a imagem fica presa no placeholder, não aparece ou prejudica métricas como o LCP.

## Como identificar

- Imagens ficam em branco ou presas num placeholder e so aparecem depois que o usuário rola a página manualmente.
- O código-fonte da imagem aparece como data:image/svg+xml em vez do arquivo real (sinal classico do script de lazy load adiado).
- O PageSpeed Insights acusa o aviso Largest Contentful Paint image was lazily loaded apontando a imagem principal acima da dobra.
- Galerias, sliders ou conteúdo de scroll infinito carregam imagens em branco que nunca trocam pela versão final.
- Imagens de fundo via CSS (hero do Elementor, Divi, Oxygen) não carregam ou carregam tarde demais.
- Logo ou imagem destacada do topo pisca ou demora a aparecer porque foi lazy-loaded indevidamente.

## Como prevenir

- Mantenha apenas um lazy loader ativo: ao ligar o do Perfmatters, desative o lazy load de qualquer outro plugin, do tema e do page builder.
- Sempre que usar Delay JavaScript ou Defer JS, deixe o arquivo perfmatters/js/lazyload.min.js na lista de exclusão desses recursos.
- Exclua as imagens acima da dobra (logo, imagem destacada, hero) do lazy load com Exclude Leading Images ou a classe no-lazy para preservar o LCP.
- Após qualquer mudanca, limpe o cache e valide a página deslogado, já que a contagem de imagens e o comportamento mudam quando você esta logado no admin.

Erros relacionados

- [Como corrigir o conflito de otimização entre Perfmatters e WP Rocket](https://full.services/wp-fixer/corrigir-conflito-perfmatters-wp-rocket/)
- [Como corrigir LCP alto no WordPress (Core Web Vitals)](https://full.services/wp-fixer/corrigir-lcp-alto-wordpress/)
- [Como corrigir imagens que não aparecem no WordPress](https://full.services/wp-fixer/corrigir-imagens-nao-aparecem-wordpress/)

## Causa

- O arquivo perfmatters/js/lazyload.min.js esta sendo adiado por outro otimizador (opção Delay JavaScript ou Defer JS do WP Rocket, por exemplo). Sem o script, a imagem fica travada no placeholder data:image/svg+xml.
- Existe mais de uma solução de lazy load ativa ao mesmo tempo: o lazy load de outro plugin de otimização, o Cloudflare Mirage ou o lazy load nativo de um page builder como o Bricks competindo com o do Perfmatters.
- A imagem principal acima da dobra não foi excluida do lazy load, entao o Perfmatters adia a imagem de LCP e o PageSpeed acusa o aviso Largest Contentful Paint image was lazily loaded.
- A opção CSS Background Images não foi habilitada ou o seletor do container do fundo não foi informado, deixando os fundos de page builder sem lazy load (ou com o fundo do hero indevidamente adiado).
- Uma regra CSS com !important na imagem de fundo impede o Perfmatters de controlar o carregamento do background, já que !important sobrescreve qualquer ajuste do plugin.
- A opção DOM Monitoring esta desligada num site com galeria, carrossel ou scroll infinito, entao imagens injetadas via JavaScript depois do carregamento nunca recebem o lazy load.

## Como resolver

1. Confirme que o lazy load do Perfmatters esta ativo e isolado: No painel, abra as configurações do Perfmatters e a submenu de lazy loading. Garanta que a opção de imagens esta ligada e desligue qualquer outro lazy loader (outro plugin de cache, Cloudflare Mirage ou lazy load do tema ou page builder) para não haver dois mecanismos competindo.

```
Perfmatters -> Lazy Loading -> Images (ligado)
```

2. Libere o script de lazy load do Delay e do Defer JavaScript: Se a imagem aparece como data:image/svg+xml no código-fonte, o script do Perfmatters esta sendo adiado. No plugin que faz o delay ou defer (WP Rocket, por exemplo), adicione o arquivo a lista de exclusão para que o script execute normalmente.

```
perfmatters/js/lazyload.min.js
```

3. Exclua as imagens acima da dobra para corrigir o LCP: Para o aviso de LCP image lazily loaded, use a opção Exclude Leading Images para excluir automaticamente as primeiras imagens do topo, ou exclua a imagem específica pela classe ou por um trecho do atributo no campo de exclusão. Faca a contagem deslogado, porque o número de imagens muda quando você esta logado.

```
Perfmatters -> Lazy Loading -> Exclude Leading Images
class="attachment-full size-full
no-lazy
```

4. Trate as imagens de fundo via CSS: Se o problema for em fundos de page builder, ligue a opção CSS Background Images e informe o ID ou a classe do container do fundo, um por linha e sem o prefixo de ponto ou cerquilha. Para o hero acima da dobra, adicione a classe de exclusão do Perfmatters no container em vez de lazy-loadar o fundo principal.

```
Perfmatters -> Lazy Loading -> CSS Background Images
perfmatters-lazy-css-bg
```

5. Ligue o DOM Monitoring em sites dinâmicos e valide deslogado: Se as imagens em branco aparecem em galerias, carrosseis ou scroll infinito, ligue a opção DOM Monitoring para que o Perfmatters aplique lazy load nos elementos adicionados depois pelo JavaScript. Depois limpe o cache e teste a página numa aba anonima.

```
Perfmatters -> Lazy Loading -> DOM Monitoring
```


## Código

```php
<?php
// Exclui imagens especificas do lazy load do Perfmatters por atributo.
// Util quando a imagem acima da dobra (LCP) nao tem classe unica no campo da UI.
function full_perfmatters_excluir_lazyload($attributes) {
    $attributes[] = "class='size-full";          // imagem destacada do post
    $attributes[] = 'src="/wp-content/uploads/logo.png"'; // logo do topo
    return $attributes;
}
add_filter('perfmatters_lazyload_excluded_attributes', 'full_perfmatters_excluir_lazyload');
```

## Perguntas frequentes

### Por que as imagens ficam em branco depois que ligo o lazy load do Perfmatters?

Quase sempre porque o script de lazy load esta sendo adiado por outro plugin. Quando a imagem aparece como data:image/svg+xml no código-fonte, exclua o arquivo perfmatters/js/lazyload.min.js do Delay ou Defer JavaScript desse plugin e as imagens voltam a carregar.

### Como corrijo o aviso Largest Contentful Paint image was lazily loaded?

Esse aviso aparece quando a imagem principal acima da dobra foi adiada. Use a opção Exclude Leading Images do Perfmatters para excluir as primeiras imagens do topo, ou exclua a imagem de LCP pela classe ou por um trecho do atributo no campo de exclusão do lazy load.

### Posso usar o lazy load do Perfmatters junto com o de outro plugin de cache?

Não. Dois lazy loaders ativos ao mesmo tempo entram em conflito e quebram o carregamento das imagens. Escolha um: ao ligar o do Perfmatters, desligue o lazy load do outro plugin de otimização, do Cloudflare Mirage e do tema ou page builder.

### Como excluo uma imagem específica do lazy load no Perfmatters?

Você pode adicionar a classe no-lazy diretamente na imagem, informar a URL do arquivo ou um trecho único do atributo no campo de exclusão do Perfmatters, ou usar o seletor do container pai quando a imagem não tem uma classe única própria.

### Por que minhas imagens de fundo via CSS não recebem lazy load?

O Perfmatters so adia fundos inline automaticamente. Para fundos definidos no CSS de um page builder, ligue a opção CSS Background Images e informe a classe ou o ID do container. Se houver !important na regra do fundo, o plugin não consegue controlar esse background.

### O lazy load do Perfmatters funciona em galerias e scroll infinito?

Sim, mas você precisa ligar a opção DOM Monitoring. Sem ela, imagens adicionadas depois pelo JavaScript de carrosseis, galerias e scroll infinito não são detectadas e podem ficar em branco. Com o DOM Monitoring ligado, o Perfmatters aplica lazy load nesses elementos dinâmicos.

### Preciso testar deslogado depois de ajustar o lazy load?

Sim. A quantidade de imagens e o comportamento do lazy load mudam quando você esta logado no admin. Limpe o cache e abra a página numa aba anonima ou deslogado para conferir de verdade quantas imagens carregam e se o LCP melhorou.

**Fonte:** [Perfmatters — How to enable lazy load in WordPress (Troubleshooting)](https://perfmatters.io/docs/lazy-load-wordpress/)