CORS sem mistério
Por que o navegador bloqueia a resposta da sua API, como funciona o preflight e como liberar só o necessário.
6 min de leitura · Iniciante · Revisado em
O erro que todo mundo encontra
Console do navegador
Access to fetch at 'https://api.loja.com/pedidos' from origin
'http://localhost:5173' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present.A requisição chegou ao servidor e ele respondeu. Quem bloqueou foi o navegador, que não entregou a resposta ao seu JavaScript porque o servidor não autorizou essa origem. Por isso o mesmo endpoint funciona no curl, no Postman e no backend, mas falha na página.
Origem e a política de mesma origem
A origem é a combinação de esquema, domínio e porta. Por segurança, o navegador só deixa um script ler respostas da mesma origem da página, a não ser que o outro servidor diga que aceita.
| Endereço | Mesma origem? | Motivo |
|---|---|---|
https://loja.com/api | Sim | Só o caminho muda |
http://loja.com | Não | Esquema diferente |
https://api.loja.com | Não | Subdomínio diferente |
https://loja.com:8443 | Não | Porta diferente |
Como o navegador pede permissão
Requisições que podem mudar algo, ou que levam cabeçalhos como Authorization e Content-Type: application/json, passam antes por um preflight: uma requisição OPTIONS perguntando se pode.
Um POST com JSON de localhost:5173 para api.loja.com
- Navegador → API: OPTIONS /pedidos. Origin: http://localhost:5173 · Access-Control-Request-Method: POST · Access-Control-Request-Headers: content-type, authorization
- API → Navegador: 204 No Content. Access-Control-Allow-Origin: http://localhost:5173 · Allow-Methods: GET, POST · Allow-Headers: content-type, authorization
- Navegador → API: POST /pedidos. A requisição real, com o corpo JSON.
- API → Navegador: 201 Created. Precisa repetir Access-Control-Allow-Origin, senão o navegador esconde a resposta.
Como corrigir
Express com o pacote cors: libere só as origens que você conhece
import cors from 'cors';
const origens = ['https://loja.com', 'http://localhost:5173'];
app.use(
cors({
origin: origens,
credentials: true, // só se usar cookies
}),
);No desenvolvimento, o proxy do Vite evita o CORS: tudo vira mesma origem
// vite.config.js
export default {
server: {
proxy: { '/api': 'http://localhost:3000' },
},
};
// no código: fetch('/api/pedidos')| Sintoma | Causa provável |
|---|---|
| Funciona no GET, falha no POST | O servidor não responde ao OPTIONS do preflight |
| Erro 401 no preflight | A autenticação está bloqueando o OPTIONS, que não leva token |
| Cookies não vão junto | Falta credentials: 'include' no fetch e Allow-Credentials: true no servidor |
* com credenciais é rejeitado | Com cookies, a origem precisa ser explícita |
| Só falha em produção | A lista de origens não inclui o domínio publicado |