# Imagens quebradas ao ligar a CDN do LiteSpeed Cache

A aba CDN não copia arquivo nenhum: ela só reescreve o endereço dos estáticos. Quando o hostname novo não bate com o que a borda aceita, o navegador desenha o ícone partido.

> os campos da aba CDN (CDN URL, Original URLs e Included Directories à frente) explicam quase toda imagem quebrada no LiteSpeed Cache. Antes de investigar, faça 3 coisas: desligue o CDN Mapping, rode Purge All e confirme que as imagens voltaram.

João Rizzon · 2026-09-21 · WordPress

---

## A aba CDN só troca o endereço, não copia arquivo nenhum

O cache de página do LiteSpeed guarda o HTML pronto no servidor. A aba CDN faz outra coisa, em outra camada: ela procura no HTML os endereços dos arquivos estáticos (imagem, CSS, JavaScript, fonte) e reescreve o hostname desses endereços para o hostname da sua CDN.

Um exemplo do que acontece com a chave ligada:

```
antes:  https://exemplo.com.br/wp-content/uploads/2026/01/foto.jpg
depois: https://cdn.exemplo.com.br/wp-content/uploads/2026/01/foto.jpg
```

Nada foi copiado, nada foi enviado. O plugin não sobe arquivo para lugar nenhum. Ele apenas troca o texto do endereço dentro da página. Quem tem que ir buscar o arquivo na sua origem, guardar e servir é a CDN, quando o navegador do visitante bater nela pela primeira vez.

É por isso que a imagem quebra. Se o hostname novo não existe, não tem certificado, ou existe mas devolve erro para aquele caminho, o navegador pede um endereço que ninguém atende e desenha o ícone de imagem partida. O arquivo continua intacto na sua hospedagem. O que está errado é o endereço que a página mandou o navegador visitar.

A [documentação do LSCWP](https://docs.litespeedtech.com/lscache/lscwp/cdn/) separa duas coisas na mesma aba: o uso da CDN do QUIC.cloud e o **CDN Mapping**, que é o mapeamento manual para qualquer outra CDN. Este artigo trata do mapeamento manual, que é onde mora o problema de hostname.

## O plano de volta atrás, decorado antes de ligar a chave

Ligar a chave é reversível e leva menos de um minuto para desfazer. Decore o caminho de volta antes de ligar, porque você vai querer usá-lo com o site já quebrado e com pressa.

### Como desfazer em quatro passos, com o Purge All que todo mundo esquece

- No painel do WordPress, vá em **LiteSpeed Cache > CDN**.
- Desligue a chave do **CDN Mapping** (volte para OFF) e salve.
- Vá em **LiteSpeed Cache > Toolbox** e clique em **Purge All**. Isso descarta o HTML antigo, que ainda contém os endereços da CDN dentro dele.
- Abra o site numa janela anônima e force o recarregamento com `Ctrl+F5` (`Cmd+Shift+R` no Mac).
- Confirme que as imagens voltaram antes de investigar qualquer outra coisa.

O **Purge All** é o que mais gente esquece. Você desliga a chave, recarrega, a imagem continua quebrada e conclui que o problema é outro. Não é: o visitante está recebendo uma página em cache gerada quando a chave ainda estava ligada.

Se você for mexer em mais do que a aba CDN (editar `.htaccess`, trocar tema, alterar URL do site), faça backup de arquivos e banco antes. Para o que está descrito aqui, a chave e o purge dão conta.

## A CDN precisa responder no hostname antes de você tocar no plugin

A ordem correta é: primeiro a CDN funciona sozinha, depois o plugin aponta para ela. Quem inverte essa ordem passa a depurar dois sistemas ao mesmo tempo.

O teste é direto. Pegue uma imagem qualquer que você sabe que existe, por exemplo `https://exemplo.com.br/wp-content/uploads/2026/01/foto.jpg`, e peça o mesmo caminho no hostname da borda, trocando só o domínio. Cole no navegador:

```
https://cdn.exemplo.com.br/wp-content/uploads/2026/01/foto.jpg
```

Se a imagem aparece, com cadeado fechado na barra de endereço, o pré-requisito está cumprido. Se aparece aviso de certificado, erro 403, 404 ou uma página de erro da CDN, pare aqui: o plugin não tem como consertar isso.

Quem tem acesso a um terminal pode ver o motivo em uma linha:

```
curl -I https://cdn.exemplo.com.br/wp-content/uploads/2026/01/foto.jpg
```

O que cada parte faz: `curl` busca o endereço, e `-I` pede só os cabeçalhos da resposta, sem baixar a imagem inteira. O resultado esperado é uma primeira linha com `200`, um `content-type: image/jpeg` e, na maioria das CDNs, algum cabeçalho de cache próprio da borda indicando HIT ou MISS. Um `403` ou `404` na primeira linha significa que a borda recusou aquele caminho. Um erro de SSL antes de qualquer cabeçalho significa que o certificado não cobre o hostname `cdn.`.

Três coisas precisam estar de pé antes de ligar a chave:

- O registro DNS do hostname da CDN existe e aponta para a borda.
- O certificado HTTPS cobre exatamente esse hostname. Certificado emitido para `exemplo.com.br` não vale para `cdn.exemplo.com.br` a menos que seja wildcard ou inclua o nome.
- A zona da CDN tem a sua origem configurada e busca o arquivo lá quando não tem cópia.

## Os seis campos que decidem se a imagem carrega

Dentro de **LiteSpeed Cache > CDN**, com o CDN Mapping ligado, são poucos campos que importam para o sintoma de imagem quebrada.

| Campo | O que ele controla | Erro comum | Sintoma |
|---|---|---|---||
| CDN URL | O hostname que substitui o seu nas URLs reescritas | Digitar sem `https://`, ou usar um hostname sem certificado válido | Imagem quebrada em todo o site, cadeado com aviso |
| Include Images / CSS / JS / File Types | Que tipos de arquivo entram na reescrita | Ligar JS e CSS antes de validar a borda | Layout desmontado, não só foto quebrada |
| Original URLs | Quais endereços da sua página são substituídos | URL do site com `www` no campo e sem `www` no HTML (ou o contrário) | Nada muda, ou só parte das imagens troca |
| Included Directories | Quais diretórios entram na reescrita. O campo já vem preenchido pelo plugin com os diretórios de estático do WordPress | Remover `wp-content`, ou acrescentar `wp-admin` | Sem `wp-content`, os uploads não vão para a CDN. Com `wp-admin`, o painel quebra |
| Exclude Path | Caminhos que ficam de fora mesmo estando num diretório incluído | Deixar vazio quando há arquivo protegido ou gerado dinamicamente | 403 em arquivos específicos |
| HTML Attribute To Replace | Em que atributos do HTML o plugin procura endereço (src, href e similares) | Mexer sem necessidade | Imagem de lazy load ou de tema que usa atributo próprio não troca, ou troca e quebra |

Os nomes dos campos e o que cada um controla seguem a [documentação do LSCWP para a aba CDN](https://docs.litespeedtech.com/lscache/lscwp/cdn/), linkada na primeira seção. As colunas de erro comum e sintoma são observação de prática, não algo que esteja documentado: se o seu comportamento divergir, a documentação é que manda.

Detalhe que gera confusão em fórum: o exemplo de **CDN URL** na documentação aparece com barra no final do endereço. Ou seja, a barra final não é o vilão que costumam dizer que é. Use o formato do exemplo da documentação e confira o resultado na aba Rede do navegador, que é onde você vê o endereço que de fato foi montado.

A regra prática: **`wp-content` fica dentro, `wp-admin` fica fora, sempre**. Os uploads do WordPress vivem em `wp-content/uploads`, então tirar `wp-content` da lista de diretórios incluídos é a forma mais rápida de a CDN não servir nenhuma foto. E o painel administrativo não deve nunca passar pela borda: ele é dinâmico, autenticado, e a CDN vai devolver conteúdo errado ou negar acesso.

### Ligue imagens primeiro, CSS e JS depois, um de cada vez

A sequência que dá menos trabalho de depurar:

- Ligue o CDN Mapping com **apenas Include Images** marcado, deixe CSS e JS desligados.
- Salve, purgue tudo, verifique o site.
- Só depois ligue CSS, verifique de novo.
- Por último JS e demais tipos de arquivo.

Se quebrar ao ligar o CSS, você já sabe a causa, e não precisa adivinhar entre quatro mudanças feitas ao mesmo tempo.

## O que continua saindo da origem e nunca deve passar pela borda

Nem tudo ganha alguma coisa passando pela borda, e uma parte perde.

- **Painel e login.** `wp-admin` e os arquivos de tela de login não entram. É conteúdo autenticado, muda por usuário, e não tem por que ser distribuído.
- **Downloads protegidos.** Se você vende arquivo, entrega PDF por área de membro ou usa plugin que checa permissão antes de servir, esse caminho vai para o **Exclude Path**. A CDN não conhece a sessão do seu WordPress. Se ela guardar uma cópia do arquivo, qualquer pessoa com o endereço baixa sem passar pela checagem.
- **Arquivos gerados dinamicamente por PHP.** Qualquer endereço que na verdade é um script devolvendo conteúdo, e não um arquivo em disco, tende a dar problema na borda. Exclua o caminho.
- **Uploads muito grandes.** Vídeo bruto e arquivos de dezenas de megabytes podem esbarrar em limite de tamanho da zona ou consumir cota rápido. Vale checar o limite da sua CDN antes, e excluir o diretório se não compensar.
- **Sitemap, robots.txt, arquivos de verificação de domínio.** São pedidos raros e precisam vir do domínio principal. Deixe na origem.

A lista de **Exclude Path** aceita um caminho por linha. Um caminho parcial já basta para excluir o que estiver abaixo dele.

## Três passos para verificar a reescrita sem depender de ninguém

Depois de salvar e purgar, abra o site numa janela anônima. Os dois primeiros passos levam menos de dois minutos. O terceiro é uma comparação com repetições e purges no meio: reserve alguns minutos para ele.

### Confira o hostname na barra de endereço da imagem

Clique com o botão direito em uma foto do site e escolha **Abrir imagem em nova guia** (o nome varia por navegador: pode ser "Abrir imagem em uma nova aba"). Olhe a barra de endereço.

- Se aparece `cdn.seudominio.com.br/wp-content/...` e a imagem carrega, a reescrita funcionou.
- Se aparece o hostname da CDN e a imagem não carrega, o problema é da borda ou do caminho, não do plugin.
- Se aparece o seu domínio original, o plugin não reescreveu. Revise **Original URLs** e **Included Directories**.

### Leia o código HTTP da imagem quebrada na aba Rede

Pressione `F12` para abrir as ferramentas do desenvolvedor e vá na aba **Rede** (Network). Com ela aberta, force o recarregamento com `Ctrl+F5` para ignorar o cache do seu próprio navegador.

Procure as linhas em vermelho. A coluna **Status** mostra o código HTTP. A coluna **Tempo** mostra quanto cada arquivo demorou. Clique na linha da imagem quebrada e veja o endereço completo em **Cabeçalhos** (Headers). Esse é o dado que resolve a discussão: você sabe exatamente qual endereço o navegador pediu e o que recebeu de volta.

### Compare o tempo do mesmo arquivo com e sem CDN

Este é o número que interessa para você, medido da sua conexão, no seu horário, do seu lugar no Brasil. Ninguém pode medir isso por você, porque o resultado depende do seu provedor e do ponto de presença que a borda te entrega.

- Escolha uma imagem grande do site, de preferência acima de 200 KB.
- Com a aba Rede aberta e a CDN ligada, dê `Ctrl+F5`, ache a linha daquele arquivo e anote o valor da coluna **Tempo**.
- Desligue o CDN Mapping, purgue tudo, dê `Ctrl+F5` de novo e anote o **Tempo** do mesmo arquivo servido pela origem.
- Repita cada medição três vezes e use o menor valor de cada lado. A primeira leitura com a CDN costuma ser a pior, porque a borda ainda não tem cópia do arquivo e vai buscá-lo na origem.

Exemplo ilustrativo de como a anotação fica, com números fictícios apenas para mostrar o formato (isto não é medição nossa, é modelo de planilha):

| Arquivo | Origem | CDN, 1º acesso | CDN, 2º acesso |
|---|---|---|---||
| hero.jpg, 480 KB | 310 ms | 420 ms | 95 ms |
| logo.png, 24 KB | 90 ms | 130 ms | 40 ms |

Se, no seu teste, o segundo acesso pela CDN não for mais rápido que a origem, a CDN não está te entregando ganho de entrega para aquele tipo de arquivo, e vale reavaliar se ela precisa estar ligada.

## Diagnóstico pelo código que apareceu na aba Rede

| Código ou sintoma | Causa provável | O que fazer |
|---|---|---||
| 404 na URL da CDN, 200 no domínio original | A zona da CDN aponta para origem errada, ou o caminho reescrito ficou duplicado (`/wp-content/wp-content/`) | Confira a origem configurada na zona e compare, na aba Rede, o endereço montado com o endereço real do arquivo. Caminho duplicado indica que o valor do campo CDN URL já traz parte do caminho, e não só o hostname |
| 403 em todos os estáticos | A borda não aceita a origem, ou há regra de hotlink protection bloqueando o referer | Libere o hostname da CDN na proteção de hotlink e revise as regras da zona |
| 403 só em alguns arquivos | Caminho protegido por autenticação ou gerado por PHP passando pela borda | Adicione o caminho em Exclude Path e purgue |
| Aviso de certificado ou cadeado aberto | HTTPS sem certificado válido para o hostname da CDN, ou mistura de http e https | Emita ou vincule certificado no hostname da borda antes de religar |
| Fonte não carrega, erro de CORS no console | A borda não está repassando o cabeçalho de origem permitida para arquivos de fonte | Configure o cabeçalho na zona da CDN, ou exclua o diretório de fontes |
| Painel administrativo quebrado | `wp-admin` entrou em Included Directories | Remova, salve e purgue |
| Tudo continua igual, nada foi reescrito | Original URLs não bate com o que está no HTML, normalmente por causa do `www` | Copie a URL exata que aparece em Configurações > Geral |

A diferença entre `https://exemplo.com.br` e `https://www.exemplo.com.br` no campo **Original URLs** é uma causa silenciosa e frequente. O plugin faz substituição de texto: se o texto não bate, não há substituição, e você fica olhando para uma tela idêntica achando que não salvou.

## Checklist para ligar a CDN sem quebrar o site

- Hostname da CDN respondendo sozinho, com certificado válido, testado no navegador ou com `curl -I`.
- Chave do CDN Mapping ligada com **CDN URL** completo, incluindo `https://`, no mesmo formato do exemplo da documentação do LSCWP.
- **Original URLs** com a URL exata do site, copiada de Configurações > Geral.
- **Included Directories** com os diretórios de estático que o plugin já traz preenchidos e sem `wp-admin`.
- **Exclude Path** com downloads protegidos, arquivos gerados por PHP e o que for autenticado.
- Apenas imagens ligadas na primeira rodada. CSS e JS depois, um de cada vez.
- Purge All em Toolbox depois de cada mudança, sempre.
- Verificação em janela anônima com `Ctrl+F5`, botão direito na imagem e aba Rede aberta.

Se em qualquer ponto a página quebrar, execute o plano de volta atrás da segunda seção antes de continuar mexendo. Um site fora do ar durante a depuração custa mais caro que trinta segundos de espera pelo purge.

E vale dizer o óbvio: se o seu público é quase todo brasileiro e o site já está hospedado no Brasil, o ganho de colocar uma CDN na frente dos estáticos pode ser pequeno. Meça antes com o procedimento da seção anterior. Se o segundo acesso pela borda não for mais rápido que a origem na sua conexão, deixe desligado e ganhe uma peça a menos para dar problema.

