CORS 에러 해결 방법: 브라우저 차단을 풀기 위한 서버 헤더 설정과 프록시 활용법

CORS 에러는 서버가 응답을 거부한 것이 아니라, 브라우저가 보안을 위해 다른 출처의 데이터를 차단했을 때 발생합니다. 이를 해결하려면 서버 응답 헤더에 Access-Control-Allow-Origin을 추가하여 허용할 도메인을 명시하거나, 개발 환경에서 프록시(Proxy) 설정을 통해 출처를 일치시켜야 합니다.

프론트엔드 개발자가 API를 호출할 때 가장 먼저 마주치는 벽이 바로 이 CORS 문제입니다. 로컬 호스트(localhost)에서 개발 중인 클라이언트가 별도의 도메인에 있는 API 서버에 데이터를 요청하면, 브라우저는 보안상의 이유로 이 요청이 안전한지 검사하게 됩니다. 이때 적절한 권한 설정이 없으면 콘솔창에는 붉은색 에러 메시지가 가득 차게 됩니다.

단순히 에러 메시지를 없애기 위해 모든 도메인을 허용하는 와일드카드(*)를 사용하는 것은 실무에서 매우 위험한 선택입니다. 서비스의 보안 수준을 유지하면서도 원활한 통신을 가능하게 하려면, 브라우저가 왜 이런 제약을 두는지 이해하고 상황에 맞는 해결책을 적용해야 합니다.

네트워크 통신의 흐름을 파악하는 것은 웹 개발의 기초입니다. 이전에 다루었던 HTTP 상태 코드나 서버 응답 구조에 대한 이해가 있다면, CORS 에러가 발생하는 시점이 서버의 비즈니스 로직 수행 전후 중 어디인지 더 명확하게 판단할 수 있을 것입니다.

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

핵심 내용 먼저 보기

핵심 키워드 CORS 에러 해결 방법 · 연관 검색어 CORS 에러 해결 방법, Access-Control-Allow-Origin 설정, 프론트엔드 API 연동, CORS 프록시 설정, Preflight 요청 에러

브라우저가 요청을 막는 이유: 동일 출처 정책(SOP)의 이해

CORS(Cross-Origin Resource Sharing) 에러를 이해하려면 먼저 SOP(Same-Origin Policy)를 알아야 합니다. 브라우저는 잠재적으로 해로운 사이트가 사용자의 데이터를 가로채는 것을 방지하기 위해, 기본적으로 동일한 출처(도메인, 프로토콜, 포트)에서만 리소스를 공유할 수 있도록 제한합니다.

재미있는 점은 서버는 요청을 정상적으로 처리하고 응답을 보냈을 확률이 높다는 것입니다. 하지만 브라우저가 응답을 받아본 뒤 "이 서버는 현재 도메인에 데이터를 줄 권한이 설정되어 있지 않다"고 판단하여 개발자에게 전달하지 않고 에러를 띄우는 구조입니다. 따라서 이 문제는 클라이언트 코드 수정만으로는 근본적인 해결이 어렵습니다.

서버 측 해결책: Access-Control-Allow-Origin 헤더 설정

가장 정석적인 방법은 API 서버에서 응답 헤더를 설정하는 것입니다. 서버 응답에 Access-Control-Allow-Origin: https://my-frontend-domain.com과 같이 허용할 도메인을 명시해주면 브라우저는 안심하고 데이터를 통과시킵니다.

실무에서는 보안을 위해 와일드카드(*) 대신 실제 서비스되는 도메인 주소를 정확히 기입하는 것을 권장합니다. 특히 쿠키나 인증 헤더를 포함해야 하는 요청(withCredentials: true)의 경우, 와일드카드를 사용하면 브라우저가 보안 정책 위반으로 간주하여 요청을 차단하므로 주의가 필요합니다.

로컬 개발 환경에서의 우회: 프록시(Proxy) 설정 활용

서버 설정을 변경할 수 없는 상황이거나 로컬 개발 단계에서 빠르게 확인이 필요할 때는 프록시 설정을 사용합니다. React의 경우 package.json에 proxy 설정을 추가하거나, Vite나 Webpack 설정 파일에서 특정 경로로 시작하는 요청을 API 서버 주소로 대리 전달하도록 구성할 수 있습니다.

이 방식은 브라우저가 보기에 요청이 동일한 도메인(localhost)으로 가는 것처럼 속이는 원리입니다. 실제 요청은 개발 서버가 가로채서 타겟 API 서버로 전달하고 응답을 받아오기 때문에, 브라우저의 CORS 검사를 자연스럽게 통과하게 됩니다. 다만 이는 개발 환경용 설정이므로 배포 시에는 실제 서버의 CORS 설정이 반드시 뒷받침되어야 합니다.

실무 판단 포인트: Preflight 요청과 OPTIONS 메서드

복잡한 요청(PUT, DELETE, 커스텀 헤더 포함 등)을 보낼 때 브라우저는 본 요청을 보내기 전 OPTIONS 메서드를 사용하는 Preflight 요청을 먼저 보냅니다. 이때 서버가 OPTIONS 요청에 대해 200 OK 응답과 함께 적절한 CORS 헤더를 내려주지 않으면 본 요청은 시작조차 되지 않습니다.

흔히 하는 실수 중 하나가 GET 요청은 잘 되는데 POST나 PUT에서만 CORS 에러가 나는 경우입니다. 이는 서버 프레임워크나 보안 설정(Spring Security, AWS API Gateway 등)에서 OPTIONS 메서드에 대한 접근 권한을 막아두었기 때문일 가능성이 큽니다. 서버 로그에 본 요청이 찍히지 않는다면 Preflight 단계에서 막히고 있는 것은 아닌지 반드시 확인해야 합니다.

CORS 에러는 처음 접하면 당황스럽지만, 브라우저가 사용자를 보호하기 위해 작동하는 정상적인 보안 메커니즘입니다. 서버에서 허용 도메인을 명확히 관리하고, 개발 환경에서는 프록시를 적절히 활용하는 것이 가장 효율적인 대응 전략입니다.

네트워크 통신 과정에서는 CORS 외에도 다양한 변수가 존재합니다. 만약 CORS 설정을 마쳤음에도 연결이 원활하지 않다면, 서버 자체가 응답할 수 없는 상태인 503 Service Unavailable 에러 상황은 아닌지, 혹은 짧은 시간 내에 너무 많은 요청을 보내 429 Too Many Requests 제한에 걸린 것은 아닌지 함께 점검해 보시기 바랍니다.

결국 안정적인 서비스를 운영하기 위해서는 단순히 에러를 없애는 것을 넘어, 서버의 상태와 브라우저의 보안 정책 사이에서 균형을 잡는 능력이 필요합니다. 오늘 정리한 내용이 여러분의 디버깅 시간을 단축하는 데 도움이 되길 바랍니다.

자주 묻는 질문

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

CORS는 브라우저가 강제하는 보안 정책이기 때문입니다. Postman이나 서버 서버 간 통신(Server-to-Server)은 브라우저를 거치지 않으므로 SOP의 영향을 받지 않습니다.

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

헤더 값에 여러 도메인을 쉼표로 나열하는 것은 표준이 아닙니다. 서버 로직에서 요청의 Origin 헤더를 확인한 뒤, 허용 목록에 있다면 해당 도메인을 동적으로 응답 헤더에 넣어주는 방식을 사용해야 합니다.

프론트엔드 코드만으로 CORS를 해결할 수 없나요?

근본적으로는 서버 설정이 필요합니다. 다만 개발 단계에서는 프록시 서버를 띄우거나, 브라우저의 보안 설정을 끄는 확장 프로그램을 사용할 수 있지만 이는 임시방편일 뿐입니다.

함께 보면 좋은 글

• 503 Service Unavailable 에러 해결 방법: 서버 과부하와 점검 상황에서 빠르게 복구하는 순서
• 429 Too Many Requests 해결 방법: API 호출 제한이 걸리는 이유와 실무 대응 전략
• 503 에러 점검: 서버 과부하와 설정 오류를 구분하고 해결하는 실무 체크리스트
• AI 관련주 투자, 단순 기대감과 실제 이익을 구분하는 실무적인 검증 방법

---

해시태그

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