CORS preflight가 실패할 때 가장 먼저 볼 것

CORS 오류는 브라우저에서 자주 보이지만, 실제 원인은 프론트엔드보다 서버 설정이나 프록시 계층에 있는 경우가 많습니다. 특히 No 'Access-Control-Allow-Origin' header 같은 메시지가 보여도, 진짜 문제는 OPTIONS 요청 처리 누락, credentials 설정 불일치, 허용 헤더 누락일 수 있습니다.

1) preflight 요청이란 무엇인가

브라우저는 본 요청 전에 OPTIONS 요청을 먼저 보내서 서버가 교차 출처 요청을 허용하는지 확인할 때가 있습니다. 이 확인 요청을 preflight라고 부릅니다. 단순 GET/POST처럼 보이는 요청도 Authorization 헤더나 JSON Content-Type이 붙으면 preflight가 생길 수 있습니다.

2) 가장 흔한 실패 원인

• 서버가 OPTIONS 메서드를 처리하지 않음
• Access-Control-Allow-Origin이 현재 Origin과 맞지 않음
• Access-Control-Allow-Headers에 Authorization, Content-Type 등이 빠짐
• credentials: 'include'를 쓰는데 Access-Control-Allow-Credentials: true가 없음
• 프록시나 CDN이 응답 헤더를 덮어씀

3) 먼저 확인할 순서

1. 브라우저 네트워크 탭에서 본 요청이 아니라 OPTIONS 요청부터 찾습니다.
2. 응답 상태 코드와 응답 헤더를 확인합니다.
3. 요청 헤더의 Origin, Access-Control-Request-Method, Access-Control-Request-Headers를 확인합니다.
4. 서버, 프록시, 배포 플랫폼 중 어디에서 헤더를 붙이는지 추적합니다.

여기서 중요한 점은 콘솔 에러 메시지만 보면 정보가 부족하다는 것입니다. 반드시 네트워크 탭에서 preflight 요청 자체를 열어봐야 합니다.

4) *로 열면 끝나는가

테스트 단계에서는 Access-Control-Allow-Origin: *로 쉽게 통과하는 것처럼 보일 수 있습니다. 하지만 쿠키나 세션을 포함하는 요청에서는 *를 쓸 수 없습니다. credentials: true가 필요한 요청은 정확한 Origin을 명시해야 하고, 이 경우 허용 출처 목록을 운영 환경에 맞게 관리해야 합니다.

5) 프런트 문제처럼 보이지만 서버 문제인 경우

프런트엔드 코드는 바뀐 것이 없는데 배포 후 CORS가 터진다면, API 서버 앞단의 리버스 프록시나 서버리스 플랫폼 설정이 바뀌었을 가능성을 먼저 봐야 합니다. 로컬에서는 잘 되고 운영에서만 실패하는 CORS 문제는 애플리케이션 코드보다 인프라 설정 차이에서 자주 발생합니다.

6) preflight 없이 동작하던 요청이 갑자기 실패하는 이유

요청 헤더 하나만 추가되어도 preflight가 생길 수 있습니다. 예를 들어 인증 토큰을 넣기 위해 Authorization 헤더를 붙였거나, fetch에서 Content-Type: application/json을 명시한 순간부터 브라우저가 preflight를 보내기 시작할 수 있습니다. 따라서 “어제까지 되던 요청”이 갑자기 막히면 최근에 추가한 헤더나 credentials 설정부터 확인하는 것이 빠릅니다.

7) 점검 예시

• 프런트 Origin: https://app.example.com
• API Origin: https://api.example.com
• 요청 헤더: Authorization: Bearer ...

이 경우 서버는 최소한 다음을 맞춰야 합니다.

• Access-Control-Allow-Origin: https://app.example.com
• Access-Control-Allow-Methods: GET, POST, OPTIONS
• Access-Control-Allow-Headers: Authorization, Content-Type

쿠키까지 쓴다면 여기에 Access-Control-Allow-Credentials: true도 필요합니다.

8) 실무 체크리스트

• OPTIONS 요청이 200/204로 응답하는가
• 요청 Origin과 응답 Origin 허용 값이 일치하는가
• 필요한 헤더가 Access-Control-Allow-Headers에 포함되는가
• 프록시나 CDN이 헤더를 제거하거나 덮어쓰지 않는가
• 쿠키 사용 시 credentials와 서버 응답이 서로 맞는가

9) 자주 하는 오해

Postman에서 되는데 브라우저에서만 실패하는 것은 이상한 일이 아닙니다. CORS는 브라우저 보안 정책이기 때문에 Postman이나 서버 간 요청에는 동일하게 적용되지 않습니다. 따라서 브라우저 실패를 재현하려면 반드시 실제 브라우저 네트워크 탭에서 확인해야 합니다.

10) 관련 페이지

에러 메시지 자체를 먼저 빠르게 확인하려면 오류 가이드의 cors-error 페이지를 보고, 운영 API 디버깅 흐름은 이 문서처럼 preflight 중심으로 보는 것이 더 효율적입니다.