CORS 에러 해결 방법: 브라우저 보안 정책과 프론트엔드 API 연결 문제 대응

CORS 에러는 브라우저가 보안을 위해 서로 다른 출처(Origin) 간의 자원 공유를 제한하는 과정에서 발생하며, 서버에서 적절한 응답 헤더를 설정하거나 클라이언트에서 프록시를 사용하는 방식으로 해결할 수 있습니다. 단순히 에러 메시지를 없애는 것이 목적이 아니라, 웹 보안의 근간인 동일 출처 정책(SOP)을 이해하고 안전하게 데이터를 주고받는 구조를 만드는 것이 핵심입니다.

웹 개발을 하다 보면 로컬 환경에서는 잘 작동하던 코드가 API 서버와 연결하는 순간 붉은색 에러 메시지를 뿜어내며 멈추는 경험을 하게 됩니다. 이는 웹 브라우저가 사용자를 보호하기 위해 기본적으로 탑재하고 있는 방어 기제 때문입니다. 따라서 이 문제를 해결하기 전, 웹 보안의 전반적인 흐름을 다루는 브라우저 보안 아키텍처에 대한 이해가 선행되면 훨씬 수월하게 접근할 수 있습니다.

많은 개발자가 서버에 'Access-Control-Allow-Origin: *' 설정을 추가하면 모든 문제가 해결될 것이라고 생각하지만, 이는 보안상 매우 위험할 뿐만 아니라 인증 정보(Cookie, Authorization 헤더 등)가 포함된 요청에서는 작동하지 않는 방식입니다. 실무에서는 서비스의 도메인 구조와 인증 방식에 따라 정교한 헤더 설정이 필요합니다.

이 글에서는 CORS가 발생하는 근본적인 원인부터 시작하여, 실무에서 가장 자주 마주치는 프리플라이트(Preflight) 요청 처리와 로컬 개발 환경에서의 우회 전략까지 구체적으로 살펴보겠습니다.

CORS 에러 해결 방법 주제를 읽기 전에 먼저 보면 좋은 대표 이미지 · 핵심 포인트: 왜 생기는지, 헤더 설정, 프리플라이트와 인증 쿠키를 같이 봐야 하는 이유

핵심 내용 먼저 보기

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

동일 출처 정책(SOP)과 CORS가 발생하는 근본적인 이유

웹 브라우저는 기본적으로 동일 출처 정책(Same-Origin Policy, SOP)을 따릅니다. 이는 어떤 출처에서 불러온 문서나 스크립트가 다른 출처의 자원과 상호작용하는 것을 제한하는 보안 방식입니다. 여기서 '출처'란 프로토콜(HTTP/HTTPS), 호스트(도메인), 포트 번호가 모두 일치하는 것을 의미합니다. 예를 들어, http://localhost:3000에서 실행 중인 리액트 앱이 http://api.example.com에 데이터를 요청하면 출처가 다르기 때문에 브라우저가 이를 차단합니다.

CORS(Cross-Origin Resource Sharing)는 이러한 SOP의 제약을 안전하게 해제하기 위해 만들어진 메커니즘입니다. 즉, CORS 에러는 서버의 오류가 아니라 브라우저가 "이 서버는 너의 요청을 허용할 준비가 되어 있지 않아"라고 판단하여 응답을 차단한 결과입니다. 따라서 해결의 주도권은 요청을 받는 서버가 어떤 출처를 허용할지 명시하는 데 있습니다.

서버 응답 헤더 설정 시 흔히 하는 실수와 판단 기준

가장 표준적인 해결책은 서버의 응답 헤더에 Access-Control-Allow-Origin을 추가하는 것입니다. 이때 특정 도메인을 명시하는 것이 보안상 가장 권장됩니다. 만약 여러 도메인을 허용해야 한다면, 서버 로직에서 요청의 'Origin' 헤더를 확인하여 허용 목록에 있을 경우에만 해당 값을 응답 헤더에 동적으로 넣어주는 방식을 사용해야 합니다.

실무에서 자주 하는 실수 중 하나는 와일드카드(*)를 남용하는 것입니다. 특히 Access-Control-Allow-Credentials를 true로 설정하여 쿠키나 인증 헤더를 공유해야 하는 상황에서는 와일드카드를 사용할 수 없습니다. 이 경우 반드시 구체적인 도메인 주소가 명시되어야 브라우저가 요청을 통과시킵니다. 또한, GET이나 POST 외에 PUT, DELETE 같은 메서드를 사용한다면 Access-Control-Allow-Methods 헤더도 함께 점검해야 합니다.

프리플라이트(Preflight) 요청과 인증 쿠키 처리의 함정

브라우저는 실제 요청을 보내기 전, OPTIONS 메서드를 사용하는 '프리플라이트' 요청을 먼저 보내 서버가 안전한지 확인합니다. 많은 개발자가 본 요청(GET/POST)에 대한 핸들러만 작성하고 OPTIONS 요청에 대한 응답을 누락하여 에러를 겪습니다. 서버는 OPTIONS 요청에 대해 200 OK 응답과 함께 적절한 CORS 헤더를 반환해야 합니다.

로그인 상태를 유지하기 위해 쿠키를 주고받아야 한다면 난이도가 올라갑니다. 클라이언트(axios, fetch 등)에서는 withCredentials 옵션을 활성화해야 하고, 서버 응답 헤더에는 Access-Control-Allow-Credentials: true가 포함되어야 합니다. 이때 앞서 언급했듯 Origin 헤더에 와일드카드를 쓸 수 없다는 점이 가장 큰 병목 구간이 되곤 합니다. 이 두 설정이 하나라도 어긋나면 브라우저는 보안상의 이유로 응답 데이터를 자바스크립트 코드에 전달하지 않습니다.

로컬 개발 환경에서 프록시(Proxy)를 활용한 우회 전략

백엔드 서버 설정을 직접 수정할 수 없거나, 로컬 개발 단계에서 빠르게 테스트가 필요할 때는 프록시 서버를 사용하는 것이 효율적입니다. 프록시는 브라우저와 서버 사이에서 중계 역할을 하며, 브라우저 입장에서는 동일한 출처로 요청을 보내는 것처럼 속이는 방식입니다. 예를 들어, Vite나 Webpack 같은 빌드 도구의 devServer 설정을 이용하면 특정 경로로 가는 요청을 대상 API 서버로 전달할 수 있습니다.

이 방식은 브라우저의 SOP 제약을 직접적으로 받지 않는 서버 대 서버 통신을 이용하는 원리입니다. 하지만 이는 개발 환경에서의 편의를 위한 것일 뿐, 실제 운영 환경(Production)에서는 결국 서버의 CORS 설정을 올바르게 잡거나, Nginx 같은 웹 서버에서 리버스 프록시 설정을 통해 도메인을 일치시켜야 합니다. 로컬에서만 해결되었다고 방치하면 배포 후 다시 에러를 마주하게 되므로 주의가 필요합니다.

CORS 에러 해결의 핵심은 브라우저, 클라이언트 코드, 서버 설정이라는 삼박자를 맞추는 데 있습니다. 단순히 에러 메시지를 지우기 위해 보안 설정을 느슨하게 풀기보다는, 우리 서비스가 어떤 도메인에서 접근을 허용할지 명확히 정의하는 과정이 필요합니다.

이후에는 API 인증 방식에 따른 HTTP 헤더의 세부적인 동작이나, 보안을 강화하기 위한 Content Security Policy(CSP) 같은 주제로 지식을 확장해 보시기 바랍니다. 웹 서비스가 복잡해질수록 이러한 기초적인 보안 정책이 전체 시스템의 안정성을 결정짓는 중요한 요소가 됩니다.

만약 서버 설정을 마쳤음에도 여전히 문제가 발생한다면, 브라우저 캐시를 삭제하거나 네트워크 탭에서 OPTIONS 요청의 응답 헤더를 하나씩 대조해 보며 누락된 설정이 없는지 확인해 보시기 바랍니다.

자주 묻는 질문

서버 설정을 바꿨는데도 왜 계속 CORS 에러가 나나요?

브라우저가 이전의 잘못된 OPTIONS 요청 응답을 캐싱하고 있을 수 있습니다. 개발자 도구의 Network 탭에서 'Disable cache'를 체크하고 다시 시도하거나, 서버에서 Access-Control-Max-Age 헤더를 낮게 설정했는지 확인해 보세요.

Access-Control-Allow-Origin에 여러 도메인을 넣을 수 없나요?

헤더 값에 쉼표로 구분하여 여러 도메인을 직접 넣는 것은 불가능합니다. 서버 코드에서 요청의 Origin 헤더를 읽어 허용된 리스트에 있는지 확인한 뒤, 해당 값을 응답 헤더에 동적으로 할당해야 합니다.

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

CORS는 브라우저가 강제하는 보안 정책이기 때문입니다. Postman이나 서버 사이드 코드(Node.js, Python 등)는 브라우저의 SOP 제약을 받지 않으므로 CORS 설정과 상관없이 응답을 받을 수 있습니다.

---

해시태그

#CORS에러해결방법 #Access-Control-Allow-Origin설정 #프리플라이트요청 #SOP보안정책 #프론트엔드API연결에러 #withCredentials쿠키설정