Guia de configuração de redirecionamentos no Nginx

O Nginx é um dos servidores web mais utilizados, e a configuração de redirecionamentos é uma tarefa rotineira ao administrá-lo. As duas ferramentas principais — return e rewrite — são frequentemente confundidas, levando a configurações ineficientes ou quebradas.

return vs rewrite

return (recomendado)

return 301 https://example.com;

• ✅ Rápido — envia a resposta HTTP diretamente, sem motor de regex envolvido
• ✅ Sintaxe simples, difícil de errar
• ✅ Recomendação oficial para a maioria dos casos de redirecionamento
• ❌ Não consegue capturar e reutilizar segmentos de URL

rewrite (poderoso, mas mais lento)

rewrite ^/old-path/(.*)$ /new-path/$1 permanent;

• ✅ Suporta grupos de captura com regex
• ✅ Pode transformar a estrutura da URL
• ❌ Mais lento que return
• ❌ Sintaxe complexa, fácil de criar loops infinitos

Exemplos básicos

Redirecionamento 301 permanente

server {
    listen 80;
    server_name old-domain.com;
    return 301 https://new-domain.com$request_uri;
}

Redirecionamento 302 temporário

server {
    listen 80;
    server_name example.com;
    location /maintenance {
        return 302 /maintenance.html;
    }
}

Redirecionamento de uma única página

location = /old-page.html {
    return 301 /new-page.html;
}

HTTP para HTTPS

Recomendado: blocos server separados

server {
    listen 80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name example.com www.example.com;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    # configuração do site...
}

Canonicalização www

sem www → www

server {
    listen 80;
    listen 443 ssl http2;
    server_name example.com;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    return 301 https://www.example.com$request_uri;
}

www → sem www

server {
    listen 80;
    listen 443 ssl http2;
    server_name www.example.com;
    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;
    return 301 https://example.com$request_uri;
}

Redirecionamentos de caminho

# Redirecionar um diretório, removendo o prefixo
location /blog/ {
    rewrite ^/blog/(.*)$ /articles/$1 permanent;
}

# Redirecionamentos em massa com map (eficiente para listas grandes)
map $uri $new_uri {
    /old-page-1 /new-page-1;
    /old-page-2 /new-page-2;
}
server {
    if ($new_uri) { return 301 $new_uri; }
}

Redirecionamentos com regex

# Remover extensão .html
location ~ ^(.+)\.html$ {
    return 301 $1;
}

# Remover prefixo de URL baseado em data
location ~ ^/\d{4}/\d{2}/\d{2}/(.+)$ {
    return 301 /$1;
}

Erros comuns

1. Loop de rewrite

# ❌ Loop infinito
location /old/ {
    rewrite ^/old/(.*)$ /new/$1;
}

# ✅ Use o flag permanent ou return
location /old/ {
    return 301 /new$request_uri;
}

2. Perda de query strings

# ❌ Query string perdida
location /old { return 301 /new; }

# ✅ Preservar a query string
location /old { return 301 /new$is_args$args; }

3. Falta de configuração SSL no destino HTTPS

Se você redireciona HTTP → HTTPS mas não configurou o bloco server HTTPS com um certificado válido, os usuários verão um erro de conexão. Sempre verifique se o bloco HTTPS existe e se o certificado é válido antes de ativar o redirecionamento.

Dicas de desempenho

• Prefira return em vez de rewrite — sem sobrecarga do motor de regex
• Simplifique as cadeias de redirecionamento: redirecione diretamente de A para C, não A → B → C
• Use map para tabelas grandes de redirecionamento — é avaliado ao carregar a configuração, não por requisição
• Evite regex desnecessárias em blocos location; use correspondências de prefixo ou exatas quando possível
• Sempre execute nginx -t após as mudanças para detectar erros de sintaxe antes de recarregar

Após configurar os redirecionamentos, verifique-os com o 301check.com.