Por que as imagens do WordPress ficam com baixa qualidade após o upload (e como resolver)

Nove em cada dez vezes suas imagens não estão realmente desfocadas — o WordPress reduziu a resolução delas no upload e agora entrega a cópia limitada. Desde o WordPress 5.3, qualquer imagem com largura ou altura acima de 2560px é silenciosamente substituída por uma versão -scaled limitada a 2560px na maior dimensão, e é esse arquivo menor que o seu tema estica para preencher um hero, um bloco de largura total ou uma tela retina. A solução é comprovar que foi isso que aconteceu e, então, aumentar o limite ou parar de subir imagens que precisam ser maiores que a caixa onde ficam.

Por que isso acontece

Quando você faz o upload de uma foto, o WordPress executa wp_create_image_subsizes() (em wp-admin/includes/image.php). Se a maior dimensão ultrapassar o big_image_size_threshold — 2560px por padrão — ele chama _wp_image_meta_replace_original(), gera your-photo-scaled.jpg e reescreve os metadados do anexo para que o tamanho full passe a apontar para a cópia reduzida. Seu original verdadeiro continua no disco como your-photo.jpg e é referenciado por wp_get_original_image_path(), mas nada no front-end o entrega. Todo tamanho intermediário e todo candidato de srcset é gerado a partir do arquivo reduzido de 2560px, não do que você enviou.

E aqui está a perda de qualidade. Você sobe uma imagem nítida de 4000px para um cabeçalho de largura total. O WordPress a limita a 2560px. Em uma tela padrão, dentro de um container de 1600px de largura, tudo certo. Numa tela retina 2x, o navegador precisa de aproximadamente 3200 pixels reais para preencher esse container com nitidez, só tem 2560 e amplia a diferença. Bordas suaves, texto dentro da imagem embaçado — exatamente o sintoma de “baixa qualidade após o upload”.

A outra metade do mesmo problema é o srcset escolhendo um tamanho pequeno demais. Se o seu tema informa uma largura de conteúdo que não corresponde à caixa realmente renderizada, o WordPress entrega ao navegador um intermediário -1024x683 ou -1536x1024 e ele é esticado. Mesma causa — caixa de exibição maior que os pixels disponíveis — gatilho diferente.

Verifique o que o WordPress realmente entregou

Não adivinhe. Clique com o botão direito na imagem com baixa qualidade, abra-a em uma nova aba e observe o nome do arquivo na URL. Se ele terminar em -scaled.jpg ou com um sufixo de dimensão como -1024x683.jpg, está confirmado: o navegador está renderizando uma derivada de resolução reduzida, não o seu upload. Você também pode inspecionar o elemento e ler currentSrc para ver exatamente qual candidato o navegador escolheu.

Para ter o quadro completo antes de fazer qualquer novo upload, coloque a imagem na ferramenta de tamanhos de imagem do WordPress — ela mostra todas as derivadas que o WordPress vai gerar a partir daquele arquivo exato, incluindo se uma cópia -scaled será criada e em quais dimensões, para que você saiba de antemão se a sua origem é grande o bastante para onde vai colocá-la.

No servidor você pode listar todos os arquivos limitados:

find wp-content/uploads -name '*-scaled.*'

Como resolver, na ordem

1. Se as suas imagens realmente precisam ser maiores que 2560px (heros grandes, retina, galerias com qualidade de impressão), aumente o limite:

// functions.php or a small mu-plugin
add_filter( 'big_image_size_threshold', function () {
    return 3840; // longest edge, in pixels
} );

Ou desative completamente o limite:

add_filter( 'big_image_size_threshold', '__return_false' );

2. Refaça o upload das imagens afetadas. Esse é o passo que as pessoas pulam. Alterar o limite só afeta uploads novos. As imagens que já estão na sua biblioteca mantêm os metadados antigos, e regenerar as miniaturas reconstrói os tamanhos intermediários a partir do arquivo -scaled limitado — isso não devolve a resolução que foi descartada. O caminho confiável é: alterar o filtro, excluir o anexo e subir de novo.

3. Se a sua origem já tem ≤2560px e mesmo assim está com baixa qualidade, o limite não é o seu problema — a caixa de exibição é maior que a imagem. Suba uma origem maior ou reduza o container. Para nitidez em retina, a sua origem precisa ter cerca do dobro da largura em pixels CSS da caixa que ela preenche.

4. Só depois de tudo isso, regenere as miniaturas para que os tamanhos intermediários fiquem consistentes — mas entenda que isso é limpeza, não cura.

O que não fazer

Não force a qualidade JPEG para 100. O WordPress comprime com uma qualidade padrão de 82 via wp_editor_set_quality, e metade dos conselhos on-line manda você sobrescrever isso:

add_filter( 'wp_editor_set_quality', function () { return 90; } );

Isso serve para reduzir artefatos de compressão, mas uma imagem esticada e ampliada é um problema de resolução, não de compressão. Ir de 82 para 100 incha os seus arquivos e não faz quase nada pela suavidade que você está vendo.

Não desative o -scaled por reflexo. Desligar o limite (há uma ferramenta para isso) é a decisão certa se você entrega imagens acima de 2560px — mas se o seu problema real é um intermediário pequeno demais sendo esticado, desativá-lo não muda nada e você perde a economia de banda à toa. Diagnostique primeiro.

Não culpe o cache nem regenere as miniaturas primeiro. A regeneração lê a partir da mesma origem limitada, então não consegue restaurar detalhes. Limpar um CDN ou um cache de página não muda nada num arquivo que já era pequeno no disco desde o início.

Não recorra ao CSS do tema nem ao object-fit. Nenhuma estilização adiciona pixels. Se o arquivo entregue termina em -scaled ou com um sufixo de dimensão, o problema é o arquivo, não o layout.

Ainda com problema?

Se você confirmou que o arquivo entregue é o seu upload em resolução completa — sem -scaled, sem sufixo de dimensão — e ele ainda está suave, verifique se algum plugin (um otimizador, um redimensionador de imagens de CDN ou uma biblioteca de lazy-load) está reescrevendo o seu src para um proxy comprimido. Passe a imagem pela ferramenta de tamanhos de imagem para confirmar o que o WordPress deveria estar gerando e, então, compare com o que o navegador realmente carrega. Quando esses dois discordam, algo entre o WordPress e o navegador é o culpado.