dynamic-etag: módulo NGINX para adicionar ETag a conteúdo dinâmico
Instalação
Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:
- RedHat Enterprise Linux 7, 8, 9 e 10
- CentOS 7, 8, 9
- AlmaLinux 8, 9
- Rocky Linux 8, 9
- Amazon Linux 2 e Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-dynamic-etag
yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-dynamic-etag
Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:
load_module modules/ngx_http_dynamic_etag_module.so;
Este documento descreve o nginx-module-dynamic-etag v0.3.0 lançado em 14 de novembro de 2026.
ETag para as respostas que sua aplicação gera dinamicamente.
O NGINX adiciona um ETag a arquivos estáticos, e nada ao que vem do PHP-FPM,
de uma aplicação via proxy ou de qualquer outro upstream. Essas páginas são então baixadas
por completo a cada visita, mesmo quando nenhum byte foi alterado. Este módulo calcula o hash do
corpo da resposta, envia o hash como ETag e responde a um
If-None-Match correspondente com 304 Not Modified e sem corpo.
Funciona com todos os módulos de upstream: proxy_pass, fastcgi_pass,
uwsgi_pass, scgi_pass, grpc_pass.
Sinopse
location ~ \.php$ {
dynamic_etag on;
fastcgi_pass unix:/run/php-fpm/www.sock;
include fastcgi_params;
}
$ curl -sI -X GET https://example.com/ | grep -i etag
ETag: "6f5902ac237024bdd0c176cb93063dc4"
$ curl -s -o /dev/null -w '%{http_code} %{size_download}\n' \
-H 'If-None-Match: "6f5902ac237024bdd0c176cb93063dc4"' https://example.com/
304 0
Como funciona
O ETag precisa estar no cabeçalho da resposta, e o cabeçalho é enviado antes do
corpo. Por isso o módulo retém a resposta: ele coleta o corpo conforme o
upstream o entrega, calcula o hash de todo ele (MD5) e só então envia o cabeçalho,
agora com o ETag, seguido do corpo.
- O hash sempre cobre o corpo inteiro, independentemente de como ele chega: em uma única
parte ou em várias, com
proxy_bufferingativado ou desativado, da memória ou de um arquivo temporário para o qual o NGINX o gravou. - Um corpo maior que
dynamic_etag_buffer_sizenão recebeETage é repassado sem alterações. Nunca há um hash parcial. - Requisições condicionais são respondidas pelo próprio NGINX, com base no
ETagcalculado:If-None-Matchrecebe um304, umIf-Matchque falha recebe um412. - O hash do corpo é calculado antes da compressão. O
gzipe outros filtros de compressão então enfraquecem oETag(W/"..."), como fazem para arquivos estáticos.
Diretivas
dynamic_etag
- sintaxe:
dynamic_etag on | off | $variable - padrão:
off - contexto:
http,server,location
Ativa o ETag para respostas de upstream. Com uma variável, o ETag é adicionado
quando seu valor for on; veja Uso condicional.
dynamic_etag_types
- sintaxe:
dynamic_etag_types mime-type ... - padrão:
text/html - contexto:
http,server,location
Adiciona o ETag a respostas com os tipos MIME listados, além de
text/html. O valor especial * corresponde a qualquer tipo.
dynamic_etag_strength
- sintaxe:
dynamic_etag_strength strong | weak | $variable - padrão:
strong - contexto:
http,server,location
Torna o ETag gerado forte ("...") ou fraco (W/"..."). Um ETag fraco
indica que a página é equivalente, não idêntica byte a byte. Com uma variável, o
ETag é fraco quando seu valor for weak.
dynamic_etag_buffer_size
- sintaxe:
dynamic_etag_buffer_size size - padrão:
1m - contexto:
http,server,location
O maior corpo de resposta que o módulo mantém na memória para calcular o hash. Uma resposta maior
é enviada sem ETag, exatamente como o NGINX a enviaria com o módulo desativado.
Quais respostas recebem um ETag
Todas estas condições precisam ser verdadeiras:
- a resposta vem de um upstream (não de um arquivo estático,
returnou uma página de erro: o NGINX cuida dos arquivos estáticos por conta própria); - seu status é
200; - seu tipo está listado em
dynamic_etag_types; - a requisição não é
HEAD(não há corpo para calcular o hash); - o corpo não está vazio e cabe em
dynamic_etag_buffer_size; - o upstream não enviou um
ETagpróprio. Esse é mantido, e o NGINX responde a requisições condicionais com base nele.
Observações
A página precisa ser a mesma para obter o mesmo ETag. Uma página que incorpora um
timestamp, um token aleatório ou um nonce por requisição muda a cada requisição, e
o mesmo acontece com seu hash. Verifique com:
diff <(curl -s https://example.com/) <(curl -s https://example.com/) && echo stable
A resposta é enviada quando está completa. O cliente recebe o primeiro
byte somente quando a aplicação produziu o último. Para uma página comum, isso
representa alguns milissegundos de diferença; para uma resposta que faz streaming de propósito
(saída de progresso, server-sent events), deixe o dynamic_etag desativado.
Uma resposta que o upstream não consegue terminar não é enviada de forma alguma. Se
a aplicação falhar no meio da página, o cliente recebe uma conexão fechada, não meia página
com um 200 e um ETag.
Testando com curl. curl -I envia uma requisição HEAD, que não recebe
ETag. Use curl -sI -X GET em vez disso.
Uso condicional
As diretivas não são válidas dentro de if. Use map:
map $request_uri $dyn_etag {
default on;
~^/checkout off;
~^/api/ off;
}
map $http_user_agent $etag_strength {
default strong;
~*legacybot weak;
}
server {
location / {
dynamic_etag $dyn_etag;
dynamic_etag_strength $etag_strength;
proxy_pass http://backend;
}
}