CORS 에러 해결 방법: 브라우저 보안 정책 이해와 서버/프록시 설정 가이드

CORS 에러는 브라우저가 보안을 위해 다른 도메인(Origin) 간의 자원 요청을 차단할 때 발생하며, 서버 응답 헤더에 Access-Control-Allow-Origin을 명시하는 것이 가장 근본적인 해결책입니다. 프론트엔드 개발을 하다 보면 로컬 호스트(localhost)에서 API 서버로 요청을 보낼 때 빨간색 에러 메시지를 마주하게 되는데, 이는 브라우저의 '동일 출처 정책(SOP)' 때문입니다.

단순히 에러를 없애기 위해 모든 도메인을 허용하는 와일드카드(*)를 사용하는 것은 보안상 매우 위험할 수 있습니다. 특히 인증 정보가 포함된 요청이라면 설정 방식이 완전히 달라지기 때문에 상황에 맞는 적절한 헤더 구성이 필수적입니다.

이 글에서는 CORS가 왜 발생하는지 원론적인 이유부터 시작하여, 실무에서 자주 쓰이는 프록시(Proxy) 설정법, 그리고 서버 측에서 반드시 체크해야 할 헤더 항목들을 구체적으로 다룹니다. 단순히 '작동하게 만드는 법'을 넘어, 보안을 유지하며 문제를 해결하는 판단 기준을 제시합니다.

네트워크 통신 과정에서 발생하는 다른 오류들, 예를 들어 서버 과부하로 인한 503 에러나 API 호출 제한인 429 에러와는 성격이 다르므로, 브라우저의 보안 메커니즘을 먼저 이해하는 것이 디버깅의 첫걸음입니다.

CORS 에러 해결 방법 주제를 읽기 전에 먼저 보면 좋은 대표 이미지 · 핵심 포인트: 왜 생기는지, 헤더 설정, 로컬 개발 환경

핵심 내용 먼저 보기

핵심 키워드 CORS 에러 해결 방법 · 연관 검색어 CORS 에러 해결 방법, Access-Control-Allow-Origin 설정, 프론트엔드 API 연결 에러, SOP 보안 정책, Preflight 요청 원인

왜 내 요청만 차단될까? 동일 출처 정책(SOP)과 CORS의 관계

브라우저는 기본적으로 자신이 로드된 도메인과 다른 곳으로 데이터를 요청하는 것을 의심합니다. 이를 SOP(Same-Origin Policy)라고 하며, 해커가 사용자의 권한을 가로채 다른 사이트에 요청을 보내는 CSRF 공격 등을 방지하기 위한 핵심 보안 모델입니다. 하지만 현대의 웹 개발은 여러 서버에서 자원을 가져오는 것이 필수적이기에, 이를 안전하게 허용하는 표준 절차가 바로 CORS(Cross-Origin Resource Sharing)입니다.

CORS 에러는 서버의 문제가 아니라 브라우저가 '서버로부터 받은 응답 헤더'를 검사한 뒤, 허용되지 않은 출처라고 판단하여 차단하는 것입니다. 즉, 서버는 정상적으로 응답을 보냈더라도 브라우저 단에서 이를 폐기하기 때문에 프론트엔드 코드에서는 데이터를 받을 수 없게 됩니다. 따라서 해결의 핵심은 서버가 브라우저에게 "이 도메인은 믿을 수 있으니 데이터를 넘겨줘도 된다"는 허락(Header)을 명확히 전달하는 데 있습니다.

서버에서 설정해야 할 핵심 헤더 3가지와 주의점

가장 먼저 확인해야 할 것은 Access-Control-Allow-Origin입니다. 여기에 요청을 보내는 프론트엔드의 도메인을 명시해야 합니다. 하지만 실무에서는 단순히 도메인만 맞춘다고 해결되지 않는 경우가 많습니다. 만약 쿠키나 Authorization 헤더를 포함한 인증 요청을 보낸다면, 서버 응답에 Access-Control-Allow-Credentials: true가 반드시 포함되어야 합니다.

여기서 주의할 점은 Credentials가 true일 때는 Origin에 와일드카드(*)를 사용할 수 없다는 것입니다. 보안상의 이유로 브라우저가 이를 거부하기 때문입니다. 또한, PUT이나 DELETE 같은 메서드를 사용할 때는 본 요청 전에 Preflight(예비 요청)가 발생하는데, 서버가 OPTIONS 메서드에 대해 200 OK 응답과 함께 허용하는 메서드 리스트(Access-Control-Allow-Methods)를 보내주는지도 확인해야 합니다.

로컬 개발 환경에서 서버 수정 없이 CORS 우회하기

백엔드 설정을 즉시 바꿀 수 없거나 외부 API를 테스트해야 하는 상황이라면 프론트엔드 개발 서버의 프록시(Proxy) 기능을 활용하는 것이 가장 효율적입니다. Webpack Dev Server나 Vite의 설정을 이용하면, 브라우저는 API 요청을 프론트엔드 서버(localhost)로 보내는 것으로 인식합니다. 이후 개발 서버가 중간에서 실제 API 서버로 요청을 전달하고 응답을 받아오는 방식입니다.

이 방식은 브라우저의 SOP 제약을 교묘하게 피할 수 있게 해주지만, 어디까지나 '개발 편의성'을 위한 임시 방편임을 잊지 말아야 합니다. 실제 배포 환경(Production)에서는 Nginx 같은 웹 서버에서 리버스 프록시 설정을 하거나, 백엔드 코드에서 정식으로 CORS 설정을 적용해야 합니다. 로컬에서 잘 된다고 해서 배포 시에도 문제가 없을 것이라 낙관하는 것은 위험합니다.

실무 디버깅 팁: CDN 캐싱과 네트워크 탭 확인

서버 설정을 마쳤는데도 여전히 에러가 난다면 캐싱 문제를 의심해봐야 합니다. CloudFront나 Akamai 같은 CDN을 사용 중이라면, 서버에서 CORS 헤더를 추가하기 전의 '에러 응답'이 CDN 노드에 캐싱되어 있을 수 있습니다. 이 경우 서버 설정을 아무리 바꿔도 브라우저는 계속 예전의 잘못된 헤더를 받게 됩니다. 반드시 CDN 캐시 무효화(Invalidation)를 수행한 뒤 테스트하십시오.

또한, 브라우저 개발자 도구의 'Network' 탭을 열어 실제 요청 헤더와 응답 헤더를 대조하는 습관이 중요합니다. Origin 헤더에 담긴 값이 서버의 Access-Control-Allow-Origin 리스트에 정확히 포함되어 있는지, 오타는 없는지 확인하는 것만으로도 대부분의 문제를 해결할 수 있습니다. 간혹 서버 내부 로직에서 에러가 발생해 500번대 응답이 나갈 때 CORS 헤더가 누락되어, 실제 원인인 서버 에러 대신 CORS 에러가 전면에 표시되는 착시 현상도 자주 발생하므로 주의가 필요합니다.

CORS는 개발자를 괴롭히는 귀찮은 장애물이 아니라, 사용자의 소중한 정보를 보호하기 위한 브라우저의 최후의 보루입니다. 에러 메시지가 떴을 때 무작정 구글링한 코드를 복사해 붙여넣기보다는, 현재 내 서비스의 보안 수준에 맞는 적절한 허용 범위를 고민하는 과정이 필요합니다.

특히 로컬, 스테이징, 운영 환경마다 도메인이 다르기 때문에 환경 변수를 통해 허용 도메인을 유연하게 관리하는 것이 실무적인 운영 포인트입니다. 무분별한 와일드카드(*) 사용은 지양하고, 필요한 도메인만 명확히 화이트리스트로 관리하는 습관을 들이시길 권장합니다.

만약 CORS 설정을 마친 후에도 데이터가 오가지 않는다면, 서버 자체의 가용성 문제일 수 있으니 서버 점검 가이드를 참고하여 인프라 상태를 함께 점검해 보시기 바랍니다. 네트워크 통신은 여러 계층이 얽혀 있으므로, 항상 넓은 시야로 문제를 바라보는 것이 빠른 해결의 열쇠입니다.

자주 묻는 질문

Postman에서는 잘 되는데 왜 브라우저에서만 에러가 나나요?

CORS는 브라우저가 구현하는 보안 표준이기 때문입니다. Postman이나 curl 같은 도구는 브라우저가 아니므로 SOP(동일 출처 정책)를 따르지 않으며, 따라서 서버가 CORS 헤더를 보내지 않아도 응답을 정상적으로 표시합니다.

Access-Control-Allow-Origin: * 설정이 왜 위험한가요?

와일드카드를 사용하면 모든 웹사이트에서 내 API 서버에 접근할 수 있게 됩니다. 만약 API가 민감한 정보를 다루거나 사용자 세션을 이용한다면, 악의적인 사이트에서 사용자의 권한을 이용해 데이터를 가로채는 CSRF 공격에 노출될 수 있습니다.

Preflight(OPTIONS) 요청이 자꾸 발생해서 성능이 걱정됩니다.

Preflight 요청은 브라우저가 안전을 확인하기 위해 보내는 예비 요청입니다. 이를 줄이려면 서버 응답 헤더에 'Access-Control-Max-Age'를 설정하여 브라우저가 일정 시간 동안 Preflight 결과를 캐싱하게 만들면 됩니다.

함께 보면 좋은 글

• 503 에러 해결 방법: 서버 과부하와 점검 상황에서 빠르게 복구하는 4단계 점검 리스트
• 429 Too Many Requests 에러 점검 리스트: API 제한 원인 파악과 백오프 해결 전략
• 503 Service Unavailable 에러 원인 파악과 서버 복구를 위한 단계별 점검 가이드

---

해시태그

#CORS에러해결방법 #Access-Control-Allow-Origin설정 #프론트엔드API연결에러 #SOP보안정책 #Preflight요청원인 #CORS프록시설정