# Otimizador de Imagens WebP e AVIF: guia completo
> Apresentação O Otimizador de Imagens WebP e AVIF converte e comprime as imagens da sua loja diretamente no seu servidor e serve depois automaticamente a cada visitante o formato mais…
- Página:
- Idioma: pt
- Atualizado em: 2026-09-09
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/datafireflyimageoptimizer/index.md), [en](https://www.datafirefly.com/en/documentation/datafireflyimageoptimizer/index.md), [es](https://www.datafirefly.com/es/documentation/datafireflyimageoptimizer/index.md), [de](https://www.datafirefly.com/de/documentation/datafireflyimageoptimizer/index.md), [it](https://www.datafirefly.com/it/documentation/datafireflyimageoptimizer/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafireflyimageoptimizer/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafireflyimageoptimizer/index.md)
- Índice:
## Apresentação
O Otimizador de Imagens WebP e AVIF converte e comprime as imagens da sua loja diretamente no seu servidor e serve depois automaticamente a cada visitante o formato mais leve que o navegador dele sabe mostrar. Toda a conversão é local: nenhuma imagem é enviada para um serviço de terceiros, e não há quotas nem créditos.
Ponto essencial: os seus ficheiros originais nunca são substituídos. Para cada imagem `produto.jpg`, o módulo gera `produto.jpg.webp` e `produto.jpg.avif` ao lado do original e serve-os apenas aos navegadores compatíveis. A operação é, por isso, totalmente reversível. O módulo é compatível com PrestaShop 1.7.6, 8 e 9, e funciona com Imagick, GD ou os binários `cwebp` e `avifenc`.
## Pré-requisitos e compatibilidade
- **PrestaShop**: 1.7.6 a 9.x, incluindo em multiloja.
- **PHP**: 7.2 a 8.3.
- **Pelo menos um motor de imagem**: a extensão **Imagick** (recomendada, compilada com suporte WebP/AVIF), ou a extensão **GD** com suporte WebP/AVIF, ou os binários de sistema `cwebp` e `avifenc`.
- **Servidor web**: Apache (entrega transparente por `.htaccess`) ou Nginx (modo `picture`).
Não tem a certeza do que o seu servidor suporta? O módulo integra um botão **Testar os motores** que converte uma imagem de exemplo e indica, formato a formato, que motor está disponível e que peso produz.
## Instalação
1. No back-office, abra **Módulos > Gestor de módulos**.
2. Clique em **Carregar um módulo** e coloque o arquivo ZIP do módulo.
3. Terminada a instalação, clique em **Configurar**.
Na instalação, o módulo cria as suas duas tabelas (estatísticas e fila de espera), regista os seus hooks, aplica definições predefinidas prontas a usar e, se o modo de entrega `.htaccess` estiver ativo, escreve o seu bloco de regras na pasta `/img`. É verificada a presença de pelo menos uma biblioteca de imagem (GD ou Imagick): se nenhuma estiver disponível, a instalação é interrompida com uma mensagem explícita.
## Primeiros passos
Bastam três passos para otimizar todo o catálogo existente:
1. **Teste os motores**: na página de configuração, clique em _Testar os motores_ para confirmar que o WebP e o AVIF podem ser produzidos.
2. **Analise a biblioteca de imagens**: clique em _Analisar a biblioteca_. O módulo percorre as pastas visadas e preenche a fila de espera com as imagens a tratar.
3. **Inicie a conversão**: clique em _Iniciar a conversão_. O tratamento decorre por lotes, com barra de progresso, e pode ser suspenso e retomado a qualquer momento.
As novas imagens adicionadas depois no back-office são convertidas automaticamente (ver _Conversão automática no carregamento_).
## Configuração
A página de configuração reúne um painel (capacidades do servidor e poupanças obtidas), a ferramenta de tratamento em massa, o formulário de definições e um painel de manutenção.
### Formatos de nova geração
- **Gerar WebP**: ativa a criação dos ficheiros `.webp`.
- **Qualidade WebP**: de 1 a 100. O intervalo 80-85 oferece o melhor compromisso entre qualidade e peso.
- **Gerar AVIF**: ativa a criação dos ficheiros `.avif`.
- **Qualidade AVIF**: o AVIF é mais denso do que o WebP, pelo que um valor de 45 a 55 costuma bastar para uma excelente qualidade.
### Motor e entrega
- **Motor de conversão**: _Automático_ (recomendado), _Imagick_, _GD_ ou _Binários_. Em modo automático, o módulo escolhe o melhor motor disponível para cada formato, pela ordem Imagick, GD e binários.
- **Modo de entrega**: _.htaccess_ (negociação Apache transparente), _picture_ (reescrita HTML para Nginx) ou _nenhum_. Em Apache, deixe `.htaccess`: não é preciso mais nada. Em Nginx, escolha `picture`.
### Carregamento diferido (lazy-load)
- **Lazy-load nativo**: acrescenta `loading="lazy"` e `decoding="async"` às imagens, sem JavaScript e sem impacto no SEO.
- **Efeito de aparecimento**: um ligeiro desvanecimento cosmético quando a imagem surge (opcional).
### Compressão dos originais
- **Recomprimir os originais**: volta a gravar os JPEG/PNG de origem numa versão otimizada. É conservada uma cópia `.dforig` que permite o restauro.
- **Qualidade JPEG (originais)**: a qualidade aplicada na recompressão dos JPEG de origem.
A recompressão dos originais é facultativa e está desativada por predefinição. A conversão WebP/AVIF já traz a maior parte do ganho; ative a recompressão apenas se quiser aliviar também os ficheiros servidos aos navegadores antigos.
### Âmbito
- **Tipos de imagens a tratar**: produtos, categorias, fabricantes, fornecedores, lojas e páginas CMS. Os tipos realmente disponíveis na sua instalação são detetados automaticamente.
- **Imagens do tema**: trata também a pasta `assets/img` do seu tema (e aí gere um `.htaccess` dedicado em entrega Apache).
- **Excluir**: um padrão por linha. Qualquer caminho que contenha um destes fragmentos é ignorado (por exemplo `logo` ou `/img/cms/banner`).
### Avançado
- **Conversão automática no carregamento**: converte cada imagem de produto assim que é (re)gerada no back-office.
- **Ignorar as imagens animadas**: os GIF e os PNG animados (APNG) são detetados e deixados intactos.
- **Tamanho mínimo (bytes)**: abaixo deste peso, a imagem é ignorada, já que as imagens muito pequenas não ganham nada em ser convertidas.
- **Dimensão dos lotes**: o número de imagens tratadas por pedido AJAX ou por passagem de cron. Recomendam-se 10 a 30 em alojamento partilhado.
Depois de cada alteração, lembre-se de **gravar**. Se mudar de modo de entrega, o bloco `.htaccess` é acrescentado ou retirado automaticamente em conformidade.
## Como funciona a entrega
O módulo limita-se a _gerar_ os ficheiros de nova geração e a indicar ao servidor como os _servir_. Os URL das suas imagens nunca mudam.
### Modo .htaccess (Apache)
O módulo escreve um bloco de regras em `/img/.htaccess`. Quando um navegador pede `produto.jpg`, o servidor lê o cabeçalho `Accept`: se este anunciar suporte a AVIF e existir `produto.jpg.avif`, é esse ficheiro que é devolvido; caso contrário, tenta-se o WebP e, na falta dele, o JPEG de origem. É acrescentado um cabeçalho `Vary: Accept` para que as caches e as CDN conservem a versão certa por navegador. É tudo transparente: o seu tema não é alterado e nada se parte se desativar o módulo.
O bloco é escrito em `/img/.htaccess` e não na raiz, porque o PrestaShop regenera regularmente o seu `.htaccess` de raiz. A pasta `/img`, essa, não é gerida pelo PrestaShop: o bloco mantém-se estável.
### Modo picture (Nginx)
Nos servidores Nginx, a negociação por `.htaccess` não está disponível. O modo `picture` reescreve então as etiquetas `img` da página em `picture`, com origens AVIF e WebP, mesmo antes do envio da página. O navegador escolhe por si a primeira origem que sabe mostrar.
## Otimizar um catálogo grande (CRON e CLI)
A ferramenta de tratamento em massa por AJAX serve para a maioria das lojas. Para milhares de imagens ou para automatizar o tratamento das imagens novas, use o cron ou a linha de comandos.
### Tarefa CRON
Programe um pedido regular ao URL apresentado no painel _Automatização_ da configuração. Está protegido por um token:
```
https://a-sua-loja/index.php?fc=module&module=datafireflyimageoptimizer&controller=cron&token=O_SEU_TOKEN&scan=1&limit=200
```
O parâmetro `scan=1` relança uma análise antes do tratamento (útil para detetar as novas imagens) e `limit` fixa o número de imagens tratadas por passagem.
### Comando CLI
Para bibliotecas de imagens muito grandes, o comando de linha trata a fila em segundo plano, sem tempo esgotado:
```
php modules/datafireflyimageoptimizer/cli/optimize.php --scan --loop
```
Opções disponíveis: `--scan` (analisar antes de tratar), `--loop` (continuar até esvaziar a fila), `--limit=N` (dimensão dos lotes), `--types=products,categories` (restringir os alvos nesta execução), `--force` (forçar a reconversão mesmo com os ficheiros de nova geração atualizados) e `--quiet` (saída mínima).
## Restauro e reversibilidade
Como os originais nunca são substituídos, pode voltar atrás a qualquer momento. No painel _Manutenção_, o botão **Restaurar tudo** elimina os ficheiros `.webp` e `.avif` gerados, repõe os originais recomprimidos a partir da cópia `.dforig`, retira o bloco `.htaccess` e limpa as estatísticas. O mesmo painel permite ainda **regenerar o .htaccess** se for necessário.
Segurança integrada: se uma versão de nova geração ficar mais pesada do que o original (acontece em algumas imagens já muito comprimidas), é automaticamente rejeitada. O navegador recebe então o ficheiro de origem.
## Desinstalação
A desinstalação retira o bloco `.htaccess` e elimina as tabelas e a configuração do módulo. Os ficheiros `.webp` e `.avif` já gerados permanecem no disco. Para partir de uma biblioteca limpa, use primeiro **Restaurar tudo** no separador Manutenção e só depois desinstale o módulo.
## Resolução de problemas
**As imagens de nova geração não são servidas.** Em modo Apache, confirme que o `mod_rewrite` e o `mod_headers` estão ativos e que os ficheiros `.htaccess` são tidos em conta (diretiva `AllowOverride`). Confirme também, nas ferramentas do navegador, que o pedido da imagem devolve mesmo um tipo `image/avif` ou `image/webp`.
- **O teste dos motores falha no AVIF**: o seu Imagick/GD provavelmente não está compilado com suporte AVIF. Instale os binários `avifenc`, ou desative o AVIF e mantenha o WebP.
- **Página em branco no front-office depois da ativação**: costuma estar ligado ao modo `picture` num tema muito personalizado. Volte ao modo `.htaccess` (Apache) ou a _nenhum_ e contacte o suporte.
- **A conversão é lenta**: reduza a _dimensão dos lotes_, ou passe o tratamento para o cron ou para a CLI, concebidos para grandes volumes.
- **Algumas imagens não são convertidas**: confirme que ultrapassam o _tamanho mínimo_, que não são animadas (se a opção estiver ativa) e que nenhum padrão de _exclusão_ lhes diz respeito.
## Perguntas frequentes
### As minhas imagens são enviadas para um serviço externo?
Não. Toda a conversão é 100 % local, no seu servidor. Nenhuma imagem é transmitida a terceiros e não há quotas nem créditos.
### Os meus ficheiros originais são alterados?
Não, por predefinição: as versões WebP e AVIF são criadas ao lado do original. Se ativar a recompressão dos originais, é conservada uma cópia `.dforig` para os repor.
### Tenho de alterar o meu tema ou o meu servidor?
Em modo Apache, não: o bloco `.htaccess` trata de tudo. Em Nginx, basta ativar o modo `picture` nas definições.
### Que formatos são suportados?
O módulo gera WebP e AVIF a partir dos seus JPEG, PNG e GIF (não animados).
### É compatível com PrestaShop 9 e com multiloja?
Sim, o módulo é compatível com PrestaShop 1.7.6 a 9.x e funciona em contexto multiloja. Utiliza exclusivamente hooks oficiais.
### Como tratar um catálogo de vários milhares de imagens?
Lance a análise e depois a conversão por lotes em AJAX, ou programe a tarefa CRON ou o comando CLI, que tratam a fila em segundo plano sem tempo esgotado.