# Como corrigir o lazy load de vídeos do YouTube no WP Rocket

O lazy load de vídeos do YouTube no WP Rocket adia o carregamento dos iframes e troca o embed por uma miniatura; ele falha quando o tema usa CSS de proporção no container, quando o plugin Complianz bloqueia o iframe ou quando o vídeo está num bloco que o WP Rocket não processa.

## O que é lazy load de vídeos do YouTube no WP Rocket?

O lazy load de vídeos do YouTube no WP Rocket é a combinação de duas opções da aba Mídia: LazyLoad para iframes e vídeos, que adia o carregamento do embed até o visitante rolar até ele, e Substituir iframe do YouTube por imagem de pré-visualização, que troca o iframe do vídeo por uma tag img com a miniatura do YouTube. Quando o visitante clica na miniatura, o iframe é carregado e o vídeo toca. O objetivo é reduzir o peso da página e resolver a auditoria de recursos de terceiros do PageSpeed.

O problema aparece quando essa troca de marcação não termina como deveria. Segundo a documentação do WP Rocket, o LazyLoad insere atributos como data-rocket-lazyload e data-lazy-src no iframe e adiciona a classe rll-youtube-player ao substituir o vídeo pela miniatura. Se um plugin de consentimento como o Complianz reescreve esse iframe antes, se o container do tema tem CSS de aspect-ratio ou padding em porcentagem, ou se o vídeo está numa tag vídeo em vez de iframe, o resultado é vídeo que não carrega, miniatura ausente ou um bloco de espaço em branco no lugar do player.

## Como identificar

- O vídeo do YouTube não carrega ao clicar na miniatura: a área fica preta ou em branco e o player nunca abre.
- A miniatura do YouTube não aparece e no lugar do vídeo surge apenas um retângulo vazio com a classe 'rll-youtube-player'.
- Sobra um espaço em branco acima ou abaixo do vídeo depois de ativar 'Substituir iframe do YouTube por imagem de pré-visualização'.
- O console do navegador mostra que o iframe ficou com 'data-lazy-src' preenchido mas o atributo 'src' nunca é populado ao rolar a página.
- O vídeo carrega normalmente com o cache do WP Rocket limpo, mas volta a falhar assim que o cache é gerado de novo.

**Antes de começar:** Antes de editar o functions.php do tema ou adicionar filtros do WP Rocket, faça backup do site (arquivos e banco de dados) ou teste primeiro em um ambiente de staging, para reverter caso algum embed pare de carregar.

## Como prevenir

- Insira vídeos do YouTube com o bloco de vídeo padrão do Gutenberg, que não traz CSS de proporção no container e evita o espaço em branco descrito pela doc do WP Rocket.
- Ao usar plugins de consentimento como o Complianz, decida uma única camada para tratar o YouTube e não deixe os dois reescrevendo o mesmo iframe.
- Sempre limpe o cache do WP Rocket depois de mexer na aba Mídia, para o HTML com a miniatura ser regenerado.
- Documente quais embeds estão na lista de exclusão do LazyLoad para não esquecer por que um vídeo carrega sem a otimização.

Erros relacionados

- [Como corrigir o Lazy Load do WP Rocket em imagens do Elementor](https://full.services/wp-fixer/corrigir-lazyload-wp-rocket-elementor/)
- [Como corrigir o Delay JavaScript do WP Rocket que quebra funções do site](https://full.services/wp-fixer/corrigir-delay-javascript-wp-rocket/)
- [Como corrigir o erro de Preload no WP Rocket](https://full.services/wp-fixer/corrigir-erro-preload-wp-rocket/)

## Causa

- O container do vídeo no tema usa CSS com aspect-ratio ou padding em porcentagem; segundo a doc do WP Rocket, esse cálculo não considera a imagem inserida no lugar do iframe e gera o espaço em branco acima ou abaixo da miniatura.
- O plugin Complianz está com o bloqueio de YouTube ativo: ele altera a marcação do iframe antes do WP Rocket, e a documentação afirma que isso impede a opção Substituir iframe do YouTube por imagem de pré-visualização de funcionar.
- O vídeo foi inserido com a tag HTML vídeo (player local) em vez de um iframe do YouTube; o LazyLoad para iframes e vídeos do WP Rocket processa apenas iframes e, pela doc, vídeos em tag vídeo não são processados.
- O iframe do YouTube está na lista de exclusões do LazyLoad (campo da aba Mídia) por conter um trecho como 'youtube.com' ou o título do vídeo, então o WP Rocket pula esse embed de propósito.
- O cache antigo do WP Rocket ainda serve o HTML sem a substituição da miniatura porque o cache não foi limpo após ativar a opção, mantendo o iframe original sem o lazy load aplicado.

## Como resolver

1. Confirme as opções de LazyLoad na aba Mídia: Em Configurações do WP Rocket, abra a aba Mídia e verifique se LazyLoad para iframes e vídeos está marcado e se a opção Substituir iframe do YouTube por imagem de pré-visualização está ativa. As duas juntas são o que aplica o lazy load com miniatura no embed do YouTube.

```
Painel WP -> Configurações -> WP Rocket -> aba Mídia
Marque 'LazyLoad' para iframes e vídeos
Marque 'Substituir iframe do YouTube por imagem de pré-visualização'
Salve as alterações
```

2. Limpe o cache do WP Rocket: Depois de qualquer mudança na aba Mídia é preciso limpar o cache, senão o WP Rocket continua servindo o HTML antigo sem a substituição da miniatura. A documentação reforça limpar o cache para as mudanças entrarem em vigor.

```
Painel WP -> WP Rocket (barra superior) -> Limpar cache
Recarregue a página do vídeo com Ctrl+F5
```

3. Resolva o espaço em branco do container: Se sobra espaço em branco, a causa é o CSS de proporção do container do tema. A doc recomenda usar o bloco de vídeo padrão do Gutenberg, que não traz essas regras, ou pedir ao suporte do tema para remover o aspect-ratio e o padding em porcentagem do wrapper do vídeo.

```
Reinsira o vídeo usando o bloco 'Vídeo' ou 'YouTube' padrão do Gutenberg
Ou ajuste o CSS do wrapper do tema para remover padding em porcentagem
```

4. Verifique conflito com o Complianz: Se você usa o Complianz e a miniatura não aparece, o bloqueio de YouTube do consentimento reescreve o iframe antes do WP Rocket. Desative o bloqueio de YouTube no Complianz (ou exclua esse serviço) e teste de novo a substituição pela imagem.

```
Painel WP -> Complianz -> Integrações/Serviços
Desative o bloqueio do serviço YouTube
Limpe o cache do WP Rocket e recarregue o vídeo
```

5. Exclua o iframe do lazy load se ainda quebrar: Se um vídeo específico precisa carregar de imediato, adicione um identificador dele (como youtube.com ou o título) ao campo de exclusão do LazyLoad na aba Mídia, ou use o filtro do WP Rocket para desativar o lazy load de iframes em páginas escolhidas.

```
Painel WP -> WP Rocket -> aba Mídia -> campo Excluir do LazyLoad
Adicione um trecho do iframe, ex.: youtube.com
Limpe o cache e recarregue a página
```


## Código

```php
<?php
// Desativa o lazy load de iframes do WP Rocket apenas em paginas escolhidas.
function full_wp_rocket_off_lazyload_iframes() {
    // Ajuste a condicao: pagina de contato, produto, post especifico, etc.
    if ( is_page( 'contato' ) ) {
        add_filter( 'do_rocket_lazyload_iframes', '__return_false' );
    }
}
add_action( 'wp', 'full_wp_rocket_off_lazyload_iframes' );

// Opcional: serve a miniatura do YouTube em WebP em vez de JPG.
add_filter( 'rocket_lazyload_youtube_thumbnail_extension', function( $extension ) {
    return 'webp';
} );
```

## Perguntas frequentes

### Por que meu vídeo do YouTube não carrega depois de ativar o lazy load no WP Rocket

Na maioria dos casos o iframe foi reescrito por outro plugin (como o Complianz) ou caiu na lista de exclusão do LazyLoad. Verifique a aba Mídia, desative o bloqueio de YouTube do plugin de consentimento e limpe o cache do WP Rocket.

### O que faz a opção Substituir iframe do YouTube por imagem de pré-visualização

Segundo a doc do WP Rocket, ela detecta os iframes do YouTube e troca a marcação por uma tag img com a miniatura do vídeo. Ao clicar na imagem, o iframe é carregado e o vídeo toca, o que reduz o peso da página e resolve a auditoria de recursos de terceiros.

### Por que aparece um espaço em branco abaixo do vídeo do YouTube

O espaço vem do CSS do container do tema com aspect-ratio ou padding em porcentagem, que não considera a imagem inserida no lugar do iframe. A doc recomenda usar o bloco de vídeo padrão do Gutenberg ou remover essas regras do wrapper.

### O LazyLoad do WP Rocket funciona com vídeos hospedados no próprio site

Não. A documentação do WP Rocket afirma que o LazyLoad para iframes e vídeos processa apenas iframes; vídeos inseridos com a tag HTML vídeo não são processados pela função.

### Como excluir um vídeo específico do lazy load do WP Rocket

Na aba Mídia, no campo de exclusão do LazyLoad, adicione um trecho do iframe como o domínio youtube.com ou o título do vídeo. O WP Rocket passa a ignorar esse embed e o carrega normalmente.

### Posso desativar o lazy load de iframes só em algumas páginas

Sim. O WP Rocket oferece o filtro do_rocket_lazyload_iframes para desligar o lazy load de iframes via código, podendo ser condicionado a um tipo de página específico, sem desativar a opção no site inteiro.

### Por que a miniatura do YouTube não aparece mesmo com a opção ativa

Costuma ser cache antigo ou conflito com o plugin de consentimento. Limpe o cache do WP Rocket após ativar a opção e desative o bloqueio de YouTube do Complianz, que segundo a doc impede a substituição pela imagem de funcionar.

### Dá para escolher a qualidade da miniatura do YouTube no WP Rocket

Sim. O WP Rocket permite definir a resolução da pré-visualização entre valores como mqdefault, sddefault, hqdefault e maxresdefault, escolhendo o equilíbrio entre nitidez da miniatura e peso da imagem carregada.

**Fonte:** [WP Rocket — Replace YouTube iframe with preview image](https://docs.wp-rocket.me/article/1488-replace-youtube-iframe-with-preview-image)