Gerador de Redirect (Nginx)

Redirects no nginx em profundidade: return vs rewrite, canonicalização HTTPS e redirects em massa com map

Redirects no nginx tendem a ser mais rápidos e enxutos que no Apache porque o nginx é orientado a eventos e a maioria dos redirects pode ser expressa sem invocar o motor de regex. Há três técnicas que você precisa conhecer — return, rewrite e try_files — e escolher a certa importa tanto para performance quanto para o status code que o browser vê.

Este gerador emite uma linha de redirect por par colado; a referência abaixo explica cada técnica, os padrões canônicos de HTTPS e www, variáveis embutidas úteis, a diretiva map para centenas de redirects e como validar a config antes do reload.

return, rewrite e try_files

• return — sempre preferido. return 301 https://exemplo.com$request_uri;. Sem regex, sem motor de rewrite — o nginx só manda a resposta.
• rewrite — suporta regex e grupos de captura. rewrite ^/old/(.*)$ /new/$1 permanent; (permanent = 301, redirect = 302). Mais lento que return porque o padrão precisa ser compilado.
• try_files — não é redirect propriamente, mas indispensável para SPAs e apps PHP: try_files $uri $uri/ /index.php?$query_string; tenta o arquivo, depois o diretório, depois cai no front controller do framework.

Server block dedicado para redirects

# HTTP para HTTPS, www e apex no mesmo hop
server {
  listen 80;
  listen [::]:80;
  server_name exemplo.com www.exemplo.com;
  return 301 https://exemplo.com$request_uri;
}

# Remover o www do lado TLS
server {
  listen 443 ssl http2;
  server_name www.exemplo.com;
  return 301 https://exemplo.com$request_uri;
}

Manter a lógica de redirect em um server dedicado (em vez de ramificar com if) é o estilo idiomático do nginx e evita as armadilhas conhecidas do "if is evil" dentro de contexto location.

Variáveis embutidas úteis

• $host — hostname da request line ou do header Host.
• $request_uri — URI original com query string (preserve o caminho do usuário em redirects entre domínios).
• $scheme — http ou https conforme o listener.
• $args / $arg_param — toda a query string ou um parâmetro específico (ex. $arg_id).
• $uri — URI normalizada sem a query string (use quando não quer carregar a query).

Redirects em massa com map

map $request_uri $new_uri {
  default            "";
  /pagina-antiga     /pagina-nova;
  /produtos/antigo   /produtos/novo;
  /blog/2023/legacy  /blog/legacy;
}

server {
  listen 80;
  server_name exemplo.com;
  if ($new_uri) { return 301 $new_uri; }
}

map escala graciosamente para centenas de entradas porque o nginx constrói um hash no startup. É a ferramenta certa quando você tem um arquivo longo exportado do CMS antigo — muito mais barato que uma parede de regras rewrite.

Validação e reload

sudo nginx -t              # checagem de sintaxe, imprime arquivo/linha em erro
sudo nginx -s reload       # reload gracioso (sem derrubar conexões)
curl -I -L https://exemplo.com/pagina-antiga  # confirma o 301 e a URL final

Em comparação com o Apache, o nginx é geralmente mais rápido para redirects estáticos porque não há rescan de .htaccess a cada request; o Apache continua mais flexível para regras por diretório controladas pelo dono da aplicação.

FAQ

Manter centenas de redirects é ok? Sim. O nginx faz hash das entradas de map e resolve return em tempo constante, então milhares de redirects mal afetam a latência. Evite empilhar muitas linhas rewrite — essas são avaliadas sequencialmente com regex.

O cache de 301 fica preso nos clientes para sempre? Praticamente sim — browsers cacheiam 301 agressivamente. Se um dia precisar reverter um redirect, sobrescreva com add_header Cache-Control "no-store" antes de flipar. Boa prática: ter certeza do destino antes de subir o 301.

Como mover uma subpasta inteira para um caminho novo? Use um bloco location: location /antigo/ { return 301 /novo$request_uri; }. O nginx preserva tudo depois de /antigo/, inclusive a query string.

Como redirecionar só quando um parâmetro de query aparece? Use $arg_nome dentro de if: if ($arg_legado) { return 301 /novo?id=$arg_legado; }. Sempre valide com nginx -t depois de editar.