CORS no Nginx travou seu site? Como depurar cabeçalhos

O que é o CORS e por que ele bloqueia sua aplicação web

Quando uma página web hospedada em um domínio tenta buscar dados em uma API localizada em outro servidor, o navegador entra em ação para proteger o usuário. Esse mecanismo de segurança nativo é o CORS, ou Compartilhamento de Recursos entre Origens Diferentes. Na prática, ele impede que um site malicioso leia dados sensíveis de outra aplicação sem autorização prévia.

No entanto, para quem está desenvolvendo, essa barreira costuma gerar frustração quando a API e o front-end rodam em portas ou domínios distintos. Quando a configuração do servidor web falha, o navegador exibe aquela mensagem vermelha no console bloqueando a requisição assíncrona. Se você já passou por isso ao integrar sistemas, sabe que entender como corrigir gargalos de CORS em APIs REST economiza horas preciosas de depuração.

Como funcionam as requisições do tipo Preflight no Nginx

Antes de enviar dados reais, como um formulário via JavaScript, o navegador envia uma requisição preliminar chamada de preflight, utilizando o método HTTP OPTIONS. Essa sondagem serve estritamente para perguntar ao servidor Nginx se a origem atual tem permissão para realizar a operação e quais cabeçalhos são aceitos.

Se o servidor web não responder a essa sondagem OPTIONS com os cabeçalhos corretos, o navegador simplesmente aborta a requisição principal antes mesmo de ela tocar na sua aplicação. Na prática, isso significa que configurar apenas o código da sua aplicação backend não resolve o problema se o Nginx no meio do caminho descartar ou ignorar o método OPTIONS sem retornar as permissões exigidas.

A armadilha clássica da duplicação de cabeçalhos no Nginx

Um dos erros mais comuns ao configurar o Nginx é adicionar a diretiva add_header de forma genérica em vários blocos de configuração sem verificar o comportamento de herança. O Nginx herda os cabeçalhos do contexto pai apenas se nenhum cabeçalho for definido no contexto filho, gerando duplicidade ou ausência inesperada de regras.

Quando o servidor retorna múltiplos cabeçalhos Access-Control-Allow-Origin idênticos devido a regras sobrepostas, o navegador rejeita a resposta por violar as normas de segurança. Para evitar esse tipo de conflito e garantir que os recursos estáticos e dinâmicos coexistam sem falhas de cache, vale a pena entender como gerenciar conflitos de cache e assets no frontend.

Como mapear origens dinâmicas usando variáveis no Nginx

Muitas aplicações modernas precisam aceitar requisições de múltiplos subdomínios ou ambientes de homologação sem recorrer ao caractere curinga asterisco, que proíbe o envio de credenciais e cookies. Para resolver isso com elegância, o Nginx permite criar mapeamentos condicionais eficientes.

Abaixo está um exemplo funcional de configuração utilizando o bloco map para validar a origem da requisição antes de injetar os cabeçalhos de segurança:

map $http_origin $cors_origin {
    default ""
    "~^https?://(.*)?meusite" "$http_origin"
}

server {
    listen 80;
    server_name api.exemplo.com;

    location / {
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' '$cors_origin' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type' always;
            add_header 'Access-Control-Max-Age' 1728000;
            add_header 'Content-Type' 'text/plain charset=UTF-8';
            add_header 'Content-Length' 0;
            return 204;
        }

        add_header 'Access-Control-Allow-Origin' '$cors_origin' always;
        proxy_pass http://127.0.0.1:3000;
    }
}

Como inspecionar e validar cabeçalhos na prática

Quando o bloqueio persiste, o melhor caminho não é adivinhar a solução, mas sim inspecionar o tráfego de rede diretamente no navegador. Abra as ferramentas de desenvolvedor, vá até a aba de Rede, clique na requisição que falhou e analise cuidadosamente a aba de cabeçalhos de resposta.

Verifique se os campos Access-Control-Allow-Origin e Access-Control-Allow-Credentials estão presentes exatamente como esperado pela sua aplicação. Caso utilize certificados SSL e proxy reverso, certifique-se também de que o Nginx está repassando corretamente os cabeçalhos de protocolo para evitar discrepâncias entre HTTP e HTTPS. Para aprofundar esses conceitos na prática em produção, confira também nossa análise técnica sobre Como testar capacitor de tântalo em curto com multímetro.

Considerações finais

Depurar cabeçalhos CORS no Nginx exige atenção aos detalhes de escopo, herança de diretivas e tratamento adequado das requisições OPTIONS do tipo preflight. Com uma configuração estruturada utilizando variáveis e blocos map, sua infraestrutura ganha flexibilidade e segurança sem sacrificar a experiência de integração entre diferentes domínios.

Manter o servidor web devidamente ajustado evita dores de cabeça em ambientes de produção e garante que as comunicações assíncronas fluam de maneira previsível e segura para os usuários finais.